Commons Wikimedia

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, consistent with a probing tool. The description adds behavioral context: it mentions default model, note about Anthropic API key being passed directly (BYO key), and the return structure. No contradictions.

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

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

The description is a single paragraph of about 4 sentences, efficiently conveying purpose, defaults, options, and return format. It is front-loaded with the core action and score range, followed by details and use cases. 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 no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response, combined view). All 4 parameters are described and contextualized. The complexity of multiple models and optional API key is fully addressed. The tool seems adequately described for an agent.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds valuable context: clarifies 'entity' as the thing to ask about, 'models' default to workers-ai, '_apiKey' is passed through directly to Anthropic, and 'context' helps disambiguate. This goes beyond the schema's bare 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 specifies the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score (0-100) per model. It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on LLM visibility rather than general scanning, and from 'ask_pipeworx' variants by providing a structured score.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also specifies when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use this tool or suggest alternative sibling tools for different scenarios.

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

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

Annotations already provide safety and behavioral hints (readOnly, openWorld, idempotent), but the description adds meaningful operational context: it routes among thousands of tools, fills arguments automatically, returns structured answers with pipeworx:// citation URIs, and is described as a 'single fast call'. 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 long but each section serves a purpose: usage priority, examples, alternatives, and tool routing. There is slight repetition (e.g., listing many domains and then listing query examples), but overall it is well-structured and front-loaded with the most important directive ('PREFER OVER WEB SEARCH').

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 what the tool does, when to use it, how it differs from alternatives, and what it returns (structured answer with citation URIs). Since there is no output schema, the description adequately fills the gap by describing the return value. It does not mention failure modes or rate limits, but these are not critical for this type of tool.

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

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

The input schema is exceptionally detailed, listing 'question' and all aliases with a clear description. The tool description adds example questions but these illustrate use cases rather than parameter format or semantics. Since schema coverage is 100%, the description does not need to compensate, and it adds only marginal value in this dimension.

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: it routes factual questions to appropriate sources, returns structured data with citations, and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It uses specific verbs ('routes', 'returns') and describes a concrete resource (5,529 tools across verified sources).

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). It also provides many concrete examples of appropriate queries.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it is a beta version with possible routing changes, currently matches ask_pipeworx exactly, and 'Falls back to nothing — this IS a full working router', which prevents incorrect assumptions about reduced functionality. 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 4 sentences and each one contributes meaning: purpose, current status, usage guidance, and assurance of full functionality. It is somewhat verbose but not wasteful, and the key information 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?

With a single input parameter and no output schema, the description covers the essential context: beta nature, relationship to ask_pipeworx, and current equivalence. It references the response shape but doesn't detail it, but since it says 'same response shape' as ask_pipeworx, this is sufficient if the agent knows ask_pipeworx. Overall, it is complete enough for an experimental router.

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

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

The schema covers 100% of parameters with descriptions for all aliases, so the baseline is 3. The description only mentions 'same arguments' without adding any new parameter-level detail beyond what is already in the schema. It does not compensate for any gaps because there are none.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with access to 5,529 tools. It distinguishes itself from the stable sibling by emphasizing the 'experimental edge' and 'newest routing', making its role unambiguous.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing', which serves as a clear when-to-use directive. The comparison against the stable router implies experimental intent, but it does not explicitly state when NOT to use it, such as for production stability.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description never contradicts them. It adds significant behavioral context: refusal reasons, exact return shape, evidence quoting, and the extra LLM call cost, which goes well 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 front-loaded with the essential purpose, then details behavior, usage, and tradeoffs. Every sentence adds value, though it is somewhat dense. Still, it is well-structured and not 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?

Even without an output schema, the description fully specifies the success return shape and all refusal reasons. It also clarifies routing, source count, and when to use alternatives, making the tool fully self-contained.

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

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

Schema description coverage is 100% and all six parameters are aliases for 'question.' The description adds no new parameter-level semantics beyond what the schema already provides. Baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from ask_pipeworx by emphasizing grounded extraction and evidence, and explicitly names the sibling tool it relates to.

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

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

Explicitly states when to use ('Use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of one extra LLM call. This is model guidance.

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

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

The description extensively covers behavioral details beyond annotations: fan-out patterns, response shapes, resolution logic, safety checks (low-confidence, closed markets, wide spreads), and cancellation rules. Annotations already declare readOnlyHint, but the description adds crucial context for safe usage without contradiction.

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

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

The description is very long and dense, covering many edge cases and technical details. While well-structured with labeled sections, it could be more concise. Every sentence adds value, but the length may overwhelm agents; a slightly tighter summarization would improve.

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 (multiple classifiers, fan-out examples, response shapes, edge cases), the description is extremely complete. It covers failure modes, low-confidence matches, closed markets, wide spreads, and cancellation rules. No output schema exists, but the description explains response fields thoroughly.

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%, baseline 3. The description adds significant meaning: explains that 'market' can be slug, URL, or text; 'depth' defaults to 'thorough'; 'include_raw' default false with guidance on when to set true. Examples in schema further clarify. Goes beyond baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and differentiates from sibling tools like polymarket_edges by emphasizing comprehensive research for a single bet.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies when to use the tool but does not explicitly state when not to use it or compare to alternatives. Clear enough for an agent to decide.

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 and idempotentHint=true, so the description adds no behavioral context. It fails to mention pagination (cmcontinue), rate limits, or output structure, missing an opportunity to enhance transparency.

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

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

The description is under-specified to the point of being unhelpful. While short, it fails to convey essential information, making it ineffective rather than concise.

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 3 parameters and an output schema, the description should clarify what the tool returns and how pagination works. It does not, leaving significant gaps for an AI agent to infer correct usage.

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 33% (only category has a description). The description does not explain the purpose of limit, cmcontinue, or how they interact. It adds no value beyond the schema's minimal 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 'Items in a Commons category.' is a noun phrase and does not specify the action (e.g., list, retrieve). It vaguely hints at the resource but lacks a clear verb, making it insufficient for an agent to understand what the tool does.

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

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

No guidance is provided on when to use this tool versus alternatives. Sibling tools like search or entity_profile could overlap, but the description does not differentiate or suggest 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?

Description discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), metrics (revenue, net income, etc.), handling of off-calendar fiscal years, and output format (paired data + citations). Annotations already indicate read-only, open-world, idempotent behavior; description adds rich behavioral context beyond annotations.

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

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

Description is 4–5 sentences with front-loaded examples and key instructions. Every sentence adds value, though it could be slightly more structured. 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?

Covers all relevant aspects for a tool with no output schema: data sources, metrics, sorting, output format, and efficiency gain (replaces 8–15 lookups). Complete for its 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 has 100% coverage with descriptions for both parameters. Description adds value by explaining that type='company' pulls SEC data and type='drug' pulls FAERS/FDA/trial data, and gives example values. Baseline 3, elevated to 4 due to added 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?

Description clearly states it performs side-by-side comparisons of 2–5 companies or drugs, with specific verb phrases like 'compare X and Y', 'which is bigger', 'rank these companies'. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

Explicitly advises to ALWAYS PREFER this tool over sequential single-pack lookups for comparisons. Provides examples of when to use (e.g., 'which is bigger', 'head to head') and constraints (2–5 entities). No when-not-to-use is needed given the specificity.

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

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

Adds extensive behavioral context beyond the annotations: account/payment requirements, decomposition into facets, parallel routing, output packet format (verbatim evidence, confidence, source, fetched_at, citation), gap[] and contradictions[] fields, semantic excerpting, latency expectations, and a 'never invented' guarantee. 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 and front-loaded with the critical account requirement, but it becomes quite long with many details on output behavior and performance. However, every sentence carries substantive information and the structure flows logically from requirements to purpose to usage to behavior, so it is appropriately detailed for a complex tool.

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

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

Without an output schema, the description thoroughly explains what is returned (findings with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), how the tool handles large records, and expected latency. It also covers prerequisites and alternative tools, making it very complete for an agent to select and invoke correctly.

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

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

The schema already covers both parameters with 100% coverage, so baseline is 3. The description adds meaningful context: clarifies that depth:'thorough' requires a paid plan, explains the behavioral differences between depth levels (gap recovery, iterative hops, contradictions scanning), and shows example questions for the question parameter. This goes beyond the schema but is not essential.

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 action and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly distinguishes from alternatives ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'). It clearly identifies what the tool does and how it differs from sibling tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even notes account requirements with a fallback tool. This fully covers usage contexts and alternatives.

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

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

Annotations already mark as read-only and idempotent. Description adds value by explaining return format (full schemas, curated examples) and that results are ready to call.

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

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

Description is moderately concise, front-loads purpose, and avoids fluff. Could be trimmed slightly but overall efficient.

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

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

Despite no output schema, description explains what is returned (names, descriptions, schemas, examples). Covers behavioral aspects and usage context well for a discovery tool.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. Description mentions aliases and gives examples but does not add significant meaning beyond schema.

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

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

Clearly states 'Find tools by describing the data or task' with specific verb and resource. Distinguishes itself from sibling tools like 'search' by focusing on tool discovery.

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

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

Explicitly says 'Call this FIRST' and lists domains like SEC filings, FDA drugs, etc. Gives clear use case scenarios, though lacks explicit '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?

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds concrete behavior: fans out across multiple sources, returns specific fields, and notes that patents soft-fails until reactivated. 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?

Front-loaded with examples, but the description is somewhat verbose. Every sentence adds value, yet could be trimmed slightly. Still well-structured and easy to parse.

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

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

No output schema exists, but the description thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It sets expectations for what the tool provides, though could mention result limits or pagination.

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 each parameter described, but the description adds critical context: 'value' can be ticker or zero-padded CIK, explicitly states names are not supported, and 'type' is only 'company' today. This enhances the schema's own descriptions.

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

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

The description opens with clear example queries ('Tell me about X', 'research Acme') and explicitly states 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from siblings by urging preference over chaining single-pack lookups.

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

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

It explicitly says when to use: 'when the user asks for a holistic view' and directs to prefer this tool over chaining separate lookups. It also clarifies limitations: 'names not supported (use resolve_entity first)' and provides accepted input formats.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is well-covered. The description adds no new behavioral details (e.g., error cases, rate limits, or data freshness). Adequate but not enhanced.

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?

Single sentence listing key metadata fields, with no extraneous content. Efficient and front-loaded. Could be slightly more structured (e.g., bullet points), but within acceptable limits.

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 (1 simple parameter, rich annotations, and an output schema present), the description covers the core purpose and return fields. Lacks usage guidance, but overall adequate for a read-only lookup tool.

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

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

Schema description coverage is 100%, so the parameter 'title' is fully documented in the schema. The description does not add extra meaning beyond listing return fields, which is not about the parameter. Baseline 3 is appropriate as the description provides no additional semantic value for parameters.

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

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

Description specifies the resource ('File metadata') and lists specific fields (size, mime, license, upload date, thumbnail urls), clearly indicating what is returned. It distinguishes from sibling 'file_revisions' by focusing on current metadata rather than version history. Missing an explicit verb like 'retrieve' or 'get', but still strong.

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?

No guidance on when to use this tool versus alternatives like 'file_revisions' or search tools. The description does not mention prerequisites, limitations, or context for usage, leaving the agent to infer without clear direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the name itself, such as authorization requirements or rate limits.

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

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

While short, the description is under-specified and does not front-load essential information. Single phrase lacks structure; every word does not earn its place because it fails to add 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 low schema coverage and missing parameter documentation, the description is incomplete. Even though an output schema exists, the input side is not adequately described for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain the purpose or constraints of the 'title' or 'limit' parameters. The agent has no guidance on how to use them.

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 'File revision history.' is essentially a tautology, restating the name 'file_revisions' and title 'File Revisions'. It does not use a specific verb or resource to differentiate from siblings like file_info.

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?

No guidance is provided on when to use this tool versus alternatives (e.g., file_info). The context signals show many sibling tools, but the description offers no 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 already provide destructiveHint=true and readOnlyHint=false. Description adds 'delete' which is consistent with the annotation. No extra behavioral context beyond what annotations indicate. Adequate but not additional 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?

Two sentences, front-loaded with action and resource. Every sentence is useful, no filler.

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

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

Simple tool with one required parameter and no output schema. Description covers purpose, usage, and parameter. Could mention return behavior (e.g., success confirmation) but not essential.

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

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

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so description adds no new meaning. Baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key.' Verb+resource is specific, and it distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall. Could be improved by noting when not to use, but guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by stating the tool fetches the page, extracts title/description/key links, and emits standard markdown. This provides a clear process beyond annotations.

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

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

The description is three sentences long, front-loads the main purpose, and lists use cases concisely. No fluff or unnecessary details, though it could be more structured with bullet points for readability.

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

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

Given the tool's simplicity (2 parameters, no output schema, rich annotations), the description covers core behavior and use cases. It lacks details on error handling or edge cases (e.g., invalid URL), but for a straightforward read-only tool, it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add new meaning about parameter syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and purpose for AI crawlers. It distinguishes itself from sibling tools by focusing on generating a specific file for AI indexing.

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 lists concrete use cases: indexing client sites, drafting personal llms.txt, and auditing competitors. It does not explicitly mention when not to use the tool or provide alternatives, but the context is clear enough for an agent to decide appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return fields and usage context, but doesn't disclose additional behavioral traits like pagination or rate limits. 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: first states what it does and returns, second gives usage guidance. No fluff, information is front-loaded.

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

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

For a simple read tool with one optional parameter and rich annotations, the description fully covers purpose, return values, and usage scenarios. No output schema needed.

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

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

Schema coverage is 100% with description for 'include_inactive'. The tool description reinforces that it lists active subscriptions by default, adding meaning beyond the schema.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools like subscribe and unsubscribe by focusing on read-only listing.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context and alternatives (subscribe/unsubscribe).

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 set readOnlyHint=false and destructiveHint=false, but the description adds meaningful context beyond this: rate limits ('5 per identifier per day'), no tool-call quota impact, claim_token behavior, and daily digest review. 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?

While longer than average, every sentence earns its place: purpose, exclusions, content rules, token flow, and operational details. It is front-loaded with the main action and structured logically without redundancy.

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

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

The description covers the full feedback lifecycle: when to use, what to include, how to check resolution, scope boundaries, and rate limits. Given the nested context object and two-mode usage, it provides complete guidance even without an output schema.

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

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

Schema covers all 4 parameters (100%), but the description adds cross-parameter value by illustrating the two workflows: filing with message/context and later reading via claim_token, including a concrete invocation example. It also clarifies that context should reference Pipeworx tools/packs, enriching the semantics.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the types of feedback (bug, feature/data_gap, praise), making it distinct from sibling research/data 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 explicit when-to-use conditions (tool returns wrong data, tool you wish existed, praise) and when-not-to-use (for tools from other MCP servers), even directing users to file elsewhere. It also provides content guidance: describe in terms of Pipeworx tools, don't paste the end-user prompt.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides extra behavioral 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?

Four sentences, no wasted words. Front-loaded with the core output, followed by use cases and supplementary details. Each sentence adds value.

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

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

No output schema, but the description clearly states what is returned (top tools, top packs, total call volume). Combined with thorough annotations, the description is complete for a simple trending 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% and already describes the window parameter with enum and description. The description adds value by explaining the effect of window length on the results, which is not 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 explicitly states what the tool returns: 'top tools, top packs, and total call volume over a recent window.' The verb 'returns' and resource 'trending data' are clear. It is distinct from siblings like 'ask_pipeworx' or 'search' which are query-based.

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 three specific use cases and gives guidance on window selection: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Implicitly tells when not to use (when PII or detailed call data is needed).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: monotonicity checks, partition-sum logic, semantic anchor, partition filter, fill check with CLOB depth, and response structure. This goes well beyond annotations and is internally consistent.

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 detailed and well-structured, front-loading the purpose and modes. However, it is somewhat lengthy with technical jargon (e.g., 'Jaccard similarity', 'partition_sum_yes_prices'), which could be condensed without losing clarity.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array with fields, partition_check object). It covers edge cases (skipped_low_similarity, placeholder filter, fill check) and references a related tool (polymarket_fill_risk). The description is complete for a complex tool with multiple modes.

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

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

Schema description coverage is 100% with descriptions for both parameters. The tool description adds significant value: explains mode semantics, provides concrete examples (event slugs, seed questions), and specifies URL acceptance. This far exceeds the baseline of 3 for high coverage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (default, event, topic) with specific use cases, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description gives explicit when-to-use instructions for each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It recommends event mode for specific markets. However, it does not provide comparisons to sibling tools or explicit when-not-to-use scenarios.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral details: model families, edge metrics, response segments, tradeable-edge knobs, and diagnostics, far exceeding the annotation baseline.

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

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

The description is front-loaded with the core purpose and well-structured with sections for models, knobs, and response format. However, it is quite verbose, containing detailed explanations that could be condensed.

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 complex tool with 9 parameters, no output schema, and intricate internal logic, the description is remarkably complete. It covers response structure (by_segment), edge metrics, filtering knobs, caching behavior, and diagnostics for empty segments, leaving no significant gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds some extra context about knob usage (e.g., 'min_liquidity drops opportunities where edge isn't realizable'), but this is marginal given the schema already explains each parameter well.

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 scans Polymarket markets for discrepancies with Pipeworx data, specifying it's for 'what should I bet on today' agents. However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Provides clear context for when to use the tool (discovering betting opportunities without paging hundreds of markets) but lacks explicit when-not-to-use guidance or mention of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant transparency: data source (daily snapshots), decay calculation details, limitations (60-day TTL, snapshot gaps), and response structure (tracked, expired, snapshot_dates). 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 fairly long but well-organized: purpose, args, response shape, limitations. It is front-loaded with the core question. Could be slightly more concise by integrating limitations into response description, but all information is valuable.

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 three response arrays (tracked, expired, snapshot_dates) with field meanings. It also covers limits (60-day TTL, snapshot gaps) and data interpretation (decay based on daily closes). Complete for a telemetry 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 covers 100% of parameters. Description adds context: default values, clamps, and window families with examples. It explains the meaning of 'days' (lookback) and 'window' (snapshot family) 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 it provides 'edge persistence and decay telemetry' answering specific questions about edge duration and decay. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current snapshots.

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

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

The description explains when to use the tool (to assess edge age and decay) and contrasts new vs stale edges. It implicitly distinguishes from polymarket_edges but does not explicitly list alternatives or when not to use, which would make it a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it walks the ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. 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 detailed and front-loaded with the main purpose and required parameters. It is longer but every sentence adds value. Could benefit from slightly more structured formatting (e.g., bullet points for return fields), but remains clear and efficient.

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

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

Despite no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also addresses critical context about partial basket fills and directional risk, making it complete for a check tool.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains default behavior for size_usd (max spend on buys, target proceeds on sells), side defaults (auto for basket), and basket size_usd as settlement notional. Goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific verbs and resources. It is highly specific and differentiates from sibling tools like polymarket_arbitrage and 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills convert arb to directional). Provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds substantial context beyond annotations, detailing response components (spread, safety fields, skipped counters), the two modes of operation, and conditions under which spreads are invalid (compatibility_warning, temporal_alignment). It discloses that most pre-mapped topics return warnings and that the tool is not tradeable by default.

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

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

The description is long but information-dense, with a clear front-loaded purpose and organized sections using parentheses and capitalization. It could be more concise by omitting some repeated details, but the length is justified given the complexity and lack of output schema.

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

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

Despite no output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers all key aspects needed for an agent to understand and use the tool 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 coverage is 100%, and the description adds value by explaining the relationship between parameters: topic vs explicit tickers, and that explicit ones override the topic side. It lists all pre-mapped topic values and clarifies that they are shortcuts.

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

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

The description clearly states that the tool calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (pre-mapped topics and explicit tickers) and notes that the tool does not guarantee tradeable spreads.

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 guidance on when to use each mode and explains that most pre-mapped topics return compatibility warnings, implying they may not yield meaningful spreads. It warns that temporal alignment must be true for spreads to be meaningful. However, it does not explicitly compare with sibling tools (e.g., polymarket_arbitrage) to advise when this tool is preferable.

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 claims 'random image' which suggests non-deterministic behavior, but the annotation idempotentHint=true contradicts this by implying the same input yields the same output. This contradiction undermines clarity.

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 sentence that conveys the essential purpose without extraneous words. It is appropriately front-loaded and concise.

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 and the presence of annotations and output schema, the description covers basic functionality. However, the contradiction with idempotentHint and lack of details about return format (though output schema exists) leave room for improvement.

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

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

The description adds that the category parameter is optional and filters the image, which is not present in the schema (0% coverage). However, it does not specify valid category formats or provide examples beyond what appears in the schema's examples array.

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 random image, optionally filtered by category. It distinguishes itself from sibling tools which are unrelated to images.

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?

No guidance on when to use this tool versus alternatives. The description implies its purpose but does not specify any conditions, exclusions, or related tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and is a retrieval operation. It also mentions pairing with 'remember' for saving and 'forget' for deletion, enhancing transparency beyond the annotations.

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

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

The description is concise (three sentences) with no redundant words. It front-loads the main action, provides examples, and pairs with related tools efficiently. Every sentence adds value, making it highly effective.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is complete. It explains the purpose, usage pattern, scoping, and relationship with sibling tools. No gaps remain for an AI agent to fill.

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

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

With 100% schema coverage and only one optional parameter, the description adds significant meaning: it explains that omitting the key lists all saved keys, and provides concrete examples ('user_research_topic' and empty object). This fully compensates for the minimal schema, exceeding the baseline 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 identifies the verb 'Retrieve' and the resource 'a value previously saved via remember', with the alternative of listing all keys if the key argument is omitted. It distinguishes from sibling tools like 'remember' and 'forget' by explicitly pairing with them, making the purpose specific and unambiguous.

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

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

The description provides clear context for when to use the tool (look up stored context like ticker, address, notes) and explicitly states the behavior when the key is omitted (list all keys). It does not include explicit when-not or alternatives, but the pairing with 'remember' and 'forget' implies appropriate usage boundaries, earning a 4 instead of 5.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds specific behavioral details: returns source, citation_uri, raw payload; mark_read flag changes subsequent calls; polling works. 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?

Concise, front-loaded with main action, every sentence adds value. No unnecessary words.

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

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

No output schema, but description mentions return fields. Covers usage, filtering, read flag, polling. For a read tool, it is fairly complete, though more detail on pagination or performance could be added.

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 meaningful context for type, since, and mark_read parameters, explaining their effect and examples, which 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?

Uses specific verb 'Pull fired events from your subscription feed', clearly distinguishes from sibling tools like list_subscriptions, subscribe, unsubscribe. Mentions return fields and filtering.

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 states when to use: to get alerts, with filtering options. Mentions polling and alternative access via URL. Does not explicitly say when not to use but context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral info: fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and response structure. No contradictions.

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

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

The description is informative but slightly lengthy. It front-loads with example queries and efficiently packs source details, fallback logic, and parameter guidance. Nearly 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?

Despite no output schema, the description adequately specifies return structure (changes grouped by source, total_changes count, citation URIs) and covers edge cases (USPTO soft-fail, API sunset). Complete for 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?

Schema coverage is 100%, but description enriches with examples (e.g., relative shorthand '7d', '30d', '3m', '1y') and usage advice ('Use "30d" or "1m" for typical monitoring'), adding meaning beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using specific verbs like 'What's new' and 'latest on'. It distinguishes from the sibling tool entity_profile, which serves static profiles.

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 examples and contexts are provided (e.g., 'What's new with X'), and it advises using entity_profile for static profile needs. However, it does not explicitly contrast with other search or monitoring tools among siblings, leaving some ambiguity.

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 idempotentHint=true and destructiveHint=false. Description adds key behavioral details: key-value pair scoped by identifier, persistence difference between auth and anonymous (24hr), and mentions storage lifetime. 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?

Four sentences, each adding essential information. Front-loaded with purpose, then usage, then behavioral detail. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers usage, behavior, lifetime, and pairing with sibling tools. No gaps for an agent to misuse.

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

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

Schema coverage is 100% with clear descriptions. Description adds value with naming conventions and example keys like 'subject_property', 'target_ticker', and explains value as 'any text'. Provides useful context 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?

Clearly states 'Save data the agent will need to reuse later', with specific verb 'save' and resource 'data'. Distinguishes from sibling tools 'recall' and 'forget' mentioned directly. Highly specific.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward' with concrete examples. Mentions pairing with recall/forget. Could be improved by noting when not to use (e.g., large data), but overall strong.

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

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

Even with readOnlyHint, idempotentHint, and openWorldHint annotations, the description adds critical behavior: 'LEI/FIGI enrichment degrades gracefully' and unresolved identifiers are stated explicitly under `unresolved`. It also discloses internal cascading lookups, going beyond the annotations.

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

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

The description is long but dense and well-structured with a clear SUPPORTED TYPES section. The opening example phrase list is useful for intent recognition but could be slightly trimmed. Every major clause contributes value, making it appropriately sized for a multi-type lookup tool.

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

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

For a tool with no output schema, the description thoroughly covers input types, output identifiers, data sources, failure handling, and graceful degradation. It even mentions the `unresolved` field, giving agents enough context to invoke it correctly and interpret results.

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

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

The schema already describes both parameters with 100% coverage, including accepted formats (ticker/CIK/name, brand/generic). The description repeats some of this (e.g., 'accepts ticker, CIK, or company name') but does not add new parameter-level constraints or relationships. The extra detail focuses on output behavior rather than input semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete examples (ticker, CIK, LEI, RxCUI) and lists supported types, distinguishing it from sibling tools like entity_profile.

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

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

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, implying it should be preferred for entity ID resolution. This provides strong 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?

Description adds valuable behavioral context beyond annotations: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns ranked list with score, confidence, signal density. 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 with an example, front-loaded purpose. Each sentence contributes. Could be slightly more concise but overall efficient.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers purpose, usage, parameter behavior, and output sufficiently for an agent to understand and invoke the 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%, baseline 3. Description adds meaning: explains that first entity is treated as 'subject' for narrative, others as competitors, clarifies models parameter options and _apiKey purpose, and provides context parameter use.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI visibility'. It distinguishes from sibling ai_visibility_check by emphasizing multiple entities and ranking.

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

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

Provides explicit usage context: 'useful for competitive AI-marketing audits' with an example question. Does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 well-structured and front-loaded with purpose. Each sentence adds value, though it is somewhat lengthy. It efficiently covers purpose, usage, return details, limitations, and error handling.

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 (composite from two sources, many return fields, error handling), the description covers all essential aspects: purpose, usage, return structure, limitations, and graceful degradation. No output schema, but return fields are detailed sufficiently.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds minor context like NPM-only and version defaults, but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool is a composite check for adding an npm package to a project, combining data from deps.dev and bundlephobia. It distinguishes itself from siblings by focusing on npm packages and a specific use case.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only scope and redirects other ecosystems to deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'full-text search' but no further behavioral traits such as rate limits or result details.

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 clear sentence front-loaded with the action. It is concise but lacks informative depth necessary for effective tool selection.

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 4 parameters, an output schema, and many sibling tools, the description is insufficient. It omits pagination behavior, namespace usage, result format, and differentiation from similar search tools.

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 50% (descriptions for limit and namespace only). The description does not add meaning for query or offset parameters, failing to compensate for the low coverage.

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

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

The description clearly states the verb 'search' and the resource 'Commons', indicating full-text search. However, it does not distinguish from sibling tools like 'search_within' or 'deep_research', which have overlapping purposes.

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?

No guidance on when to use this tool versus alternatives such as 'search_within' or 'category_members'. The description provides no context for appropriate usage scenarios.

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

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

Provides rich detail beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars, truncated and flagged). No annotation contradiction.

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

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

The description is somewhat lengthy but well-structured with a clear first sentence, examples, and technical details. Every sentence contributes value; no redundancy. Front-loaded with key information.

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

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

For a tool with 3 parameters, no output schema, its description explains return format (passages with offsets and scores), technical details (embedding model, cap), and usage context. It is complete enough for an agent to select and invoke correctly.

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

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

Schema descriptions already cover all three parameters (text, limit, query) with good detail. The tool description adds context on usage (e.g., 'pass the text you already pulled') and explains the return format, adding meaning beyond the schema for 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 performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article) and specifics about output (passages, offsets, similarity scores). It distinguishes from siblings by emphasizing it searches within already-fetched text, contrasting with broader search tools.

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

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

Explicitly says 'use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages). Mentions pairing with ask_pipeworx_grounded. Lacks explicit guidance on when not to use, but the positive guidance is strong.

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

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

Annotations already provide idempotentHint=true, openWorldHint=true. The description adds context about account requirements, delivery channels, and rate limits (10/day for SMS). However, it does not clarify idempotency; the phrase 'Returns the new subscription id' might imply non-idempotent behavior, potentially contradicting the idempotentHint annotation. Overall, useful but with a minor inconsistency.

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

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

The description is relatively long but all information is relevant and efficiently presented. It front-loads the core purpose and then lists types and delivery options in a structured manner. A slightly more uniform formatting could improve readability, but it earns its place.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description fully covers input semantics, including all subscription types, parameter structures, delivery channels with constraints, and account requirements. It also mentions the return value. No obvious gaps remain.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond schema definitions. For each type, it provides concrete examples (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE") and explains requirements. The delivery object is elaborated with phone verification, webhook signing, and auto-disable conditions.

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 'Create a proactive monitoring subscription' and the resource 'live-data event stream'. It also specifies the return value 'Returns the new subscription id'. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit guidance on when to use: creating subscriptions for live data events. It lists supported types with examples and delivery options. It also states a prerequisite: Requires a Pipeworx OAuth account. However, it does not explicitly mention when not to use or contrast with alternatives beyond implicit differentiation.

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, openWorldHint, idempotentHint, destructiveHint) already convey safety and idempotency. The description adds detail about the response format (category-bucketed example questions with tool+argument shapes) and the optional topic parameter, which provides 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?

The description is well-structured, starting with common queries, then explaining response characteristics, and ending with usage guidance. It is informative but slightly verbose; however, all sentences add 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?

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool and argument shapes) and the effect of the topic parameter. For a tool with a single optional parameter, this provides complete context for the agent to use it correctly.

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

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

Schema coverage is 100%, but the description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter (full spread). This provides guidance the schema alone does not.

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

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

The description clearly states it returns category-bucketed example questions and serves as the onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it's for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. Provides clear usage context, and the description implies when not to use it (if already familiar).

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

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

Description adds ownership enforcement and deactivation (not deletion) behavior beyond annotations. Annotations already indicate non-destructive, but the description provides important context that it's a soft cancellation.

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, front-loaded with core action, no filler. 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?

For a one-parameter tool with clear annotations and no output schema, the description fully covers purpose, ownership constraints, and side effects.

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 adequate description for the single parameter. Description does not add extra detail beyond what schema provides, so baseline score of 3 applies.

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

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

Description clearly states the action ('Cancel a subscription by id'), specifies the resource ('subscription'), and distinguishes from siblings 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?

Mentions ownership enforcement ('only cancel your own subscriptions'), guiding when to use. Implies when not to use (others' subscriptions) and explains non-destructive behavior 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 state readOnlyHint=true, destructiveHint=false, but the description adds significant behavioral context: routing logic, the distinction between could_not_verify (check did not happen) and unsupported (no source covers it), and the explicit warning that could_not_verify must not be treated as evidence. These details go well beyond the annotations and help the agent interpret results safely.

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

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

The description is long but well-structured: triggers, usage, routing, return values, special verdicts, and efficiency. Each sentence contributes substantive information, though some redundancy exists (e.g., repeating the 'could_not_verify' warning). It is appropriately verbose for the tool's complexity, but not maximally concise.

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

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

With no output schema, the description compensates by enumerating the verdict types and explaining the two ambiguous ones (could_not_verify, unsupported). It covers input expectations, routing, evidence citation, and why this tool is a shortcut over multiple calls. Given the tool's complexity, this is a complete picture for an agent to select and invoke it.

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

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

Although schema coverage is 100%, the description adds crucial semantics: for tolerance_pct it explains how it overrides the claim's implied tolerance, recommends 1–2 for hallucination detection, and states the default is capped at 5. For claim, it provides realistic examples. This enriches the schema descriptions and guides correct usage.

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

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

The description clearly states the tool verifies natural-language factual claims ('fact check', 'verify the claim that…') against authoritative sources. It distinguishes from siblings by detailing the structured SEC EDGAR fast path for company-financial claims and the grounded pipeline for all other claims, and notes it replaces 4–6 sequential calls, making its unique role explicit.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives concrete criteria for when to use the fast path vs grounded pipeline. It also clarifies the meaning of could_not_verify and unsupported verdicts, guiding callers on how to interpret results, which effectively says when the tool's answer is not usable.

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