Entertainment Feeds

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds context: it probes LLMs, returns per-model score/confidence/signals/raw_response, and mentions BYO key for Anthropic. No contradiction with annotations, and adds valuable behavioral details about return format and authorization.

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

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

Description is three sentences, front-loaded with the main action and outcome. Every sentence adds value: first sentence states purpose and result, second sentence explains parameters and model choice, third sentence lists use cases. No fluff.

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

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

Given moderate complexity, 4 parameters (1 required), and no output schema, the description covers purpose, parameters, and return structure (score/confidence/signals/raw_response + combined view). It lacks potential details like rate limits or cost, but is sufficient for an agent to decide to use 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 description coverage is 100% with detailed descriptions for all 4 parameters. Description further clarifies parameter usage (e.g., entity can be brand/business/topic, models defaults to workers-ai, _apiKey needed for anthropic, context for disambiguation). Adds meaning beyond schema.

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

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

Description clearly states verb (probe), resource (LLMs), and outcome (score visibility). It specifies probing one or more LLMs and scoring 0-100 per model, distinguishing itself from sibling tools like 'scan_competitor_ai_presence' by focusing on brand/product visibility across models.

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

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

Description provides use cases (AI-marketing audits, pre-launch checks) and mentions default model vs BYO key for Anthropic. However, it does not explicitly state when not to use it or compare with alternatives among siblings (e.g., 'scan_competitor_ai_presence'). Usage context is implied but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it returns citations, fills arguments automatically, works on every tier, and is 'one fast call'. No contradiction with annotations.

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

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

The description is long but front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and maintains structured sections: priority, examples, default behavior, and step-up alternatives. A few phrases ('START HERE', 'default entry point') are mildly redundant, but every sentence contributes actionable guidance.

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

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

Despite having no output schema, the description explains the return format (structured answer with stable citation URIs), the routing scope, performance expectations, and when to escalate to siblings. For a simple single-question tool with a single required parameter, nothing the agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter plus all aliases with a clear natural-language description. The tool description focuses on usage scenarios and examples rather than parameter-specific syntax, which is acceptable since the schema carries the full parameter burden.

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

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

The description names a specific verb (ask/routes), a clear scope (5,743 tools across 1,500 verified sources), and a concrete deliverable (structured answer with stable pipeworx:// citation URIs). It also distinguishes itself from close siblings ask_pipeworx_grounded and deep_research, so an agent can tell them apart without inspecting schemas.

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

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

It explicitly says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases and examples. It also gives when-not-to-use: use ask_pipeworx_grounded for single hallucination-resistant answers and deep_research for broad/multi-part questions. This is direct routing guidance with named alternatives.

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

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

Annotations are rich (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuine context beyond those hints: the current state (no active candidate, last retired 2026-07-26), that behavior currently matches ask_pipeworx exactly, that it is a full working router with no fallback, and that it is an experimental edge. No contradiction with 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?

Purpose is front-loaded, but the description is verbose — a dense paragraph with background detail (specific dates, 'the last was retired on outcome evidence 2026-07-26', 'falls back to nothing', 'the experimental edge') that could be trimmed. Some redundancy ('identical universal router', 'same 5,743 tools, same arguments, same response shape'). Informative but not economical.

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

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

For an experimental router with a single free-text parameter and no output schema, the description covers what matters: the tool count, argument equivalence, response-shape equivalence to ask_pipeworx, current identity with the stable version, and how results are evaluated. It references the sibling for response shape rather than describing it, which is adequate given no output schema exists on either.

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

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

Schema coverage is 100% and the schema fully documents all six parameters, including that q/text/input/query/prompt are aliases for question. The description adds nothing about parameter meaning, which is fine — the schema carries the entire burden and does so completely, so the 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 states a specific role — a beta 'universal router' that mirrors ask_pipeworx — and explicitly differentiates it from its stable sibling and from ask_pipeworx_grounded. It names the verb/resource scope, identifies the exact number of tools and that the response shape is identical to ask_pipeworx, leaving no ambiguity about what this tool is.

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

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

States the trigger condition clearly ('Use it exactly like ask_pipeworx when you want the newest routing') and explains the experimental purpose — results compared against the stable router to decide what merges. It names the alternative (ask_pipeworx, the stable router) but does not explicitly say when NOT to use it versus the stable version (e.g., reliability/behavioral stability), which would push it higher.

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 cover readOnly/idempotent/non-destructive, and the description adds far more: refusal behavior with enumerated refusal_reason values, verbatim-evidence extraction constrained to tool result content, the success-versus-refusal response contract, and the extra LLM call cost. It also surfaces failure modes like data_truncated and no_tool_match that annotations cannot express. 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?

Four dense sentences in a logical flow: definition, mechanics, return/refusal contract, and usage/cost tradeoff. Every sentence carries high-value information, and the key differentiator (hallucination-resistant grounded extraction) 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?

Despite having no output schema, the description documents the exact success and refusal response shapes, enumerates the refusal reasons, and covers when to use versus avoid the tool. For a complex tool with automatic argument filling, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it reveals the tool performs routing and 'fills arguments' automatically, so the agent only needs to supply a natural-language question rather than pre-resolving parameters. This tells the agent how to interact with the parameters in a way 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 opens with a precise definition: 'Hallucination-resistant answer mode for high-stakes reads' — a specific verb+resource with a distinctive attribute. It explicitly differentiates from siblings by stating it 'EXTRACTS the answer using ONLY what the tool result contains' while acknowledging the same routing as ask_pipeworx, so an agent can distinguish it without opening the schema.

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

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

Explicit when-to-use guidance is given: use whenever an answer will be quoted, cited, or acted on and facts must not be invented (financial verdicts, legal claims, medical lookups, public statements). It names the alternative and the exclusion: 'costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' Nothing is left to inference.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds extensive detail on fan-out logic, classifier list, response structure, resolver contract, parent event extraction, news fallback, safety mechanisms, and cancellation rule parsing. 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 well-structured with sections, each adding value. It front-loads the purpose. However, it is lengthy and could be trimmed while retaining essentials.

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?

Exceptionally complete for a tool with no output schema. Covers input variations, internal behavior, response structure, error modes, edge cases (low-confidence, closed markets, wide spreads), and risk considerations (cancellation rules).

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

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

Schema descriptions cover 100% of parameters. The tool description adds meaningful context: market input formats, depth quick vs thorough, include_raw recommendation. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's action (research a Polymarket bet), resource (market), and method (pull Pipeworx data). It includes usage examples. However, it does not explicitly distinguish from sibling tools like polymarket_edges, which could lead to confusion.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and describes behavior in various scenarios. Missing explicit when-not-to-use or alternatives, but the 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?

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. Annotations confirm read-only, idempotent, non-destructive behavior; description adds rich behavioral context 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?

Description is relatively long but every sentence adds value. Front-loaded with usage examples. Could be slightly more concise, but structure is logical and 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?

Despite no output schema, description explains return format (paired data + citation URIs) and mentions efficiency gains. Adequately covers all aspects for a comparison tool with good schema and annotations.

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

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

Schema coverage is 100%. Description adds meaningful context: explains type enum values (company/drug) and values parameter (tickers/CIKs or drug names) with examples and constraints (2-5 items). Goes beyond schema definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) with explicit verb phrases and usage examples. It distinguishes from sibling tools by noting it replaces 8-15 sequential 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?

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete use cases like 'which is bigger / better / larger' and specifies the entity count range. Implicitly excludes single-entity lookups, which are served by sibling tools.

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

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

Annotations declare readOnly=true, openWorld=true, idempotent=true, and destructive=false, so the description is not required to restate those. It adds substantial behavioral detail beyond annotations: returns a findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations; explicitly never invents answers and reports gaps[]; explains hop iteration, contradictions[], semantic excerpting, and expected latency. This rich behavior disclosure goes well beyond what annotations provide.

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

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

The description is information-dense and front-loaded with the critical signup/account constraint, but it is very long and packs many distinct behavioral promises into a single paragraph. While every sentence earns its place, the lack of paragraph breaks or bullet structure makes it harder to parse; it is closer to a spec sheet than a scannable tool description.

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 two parameters, an output-finding behavior not documented by any output schema, and important account/depth constraints, the description covers all the essential context: prerequisites, alternatives, expected latency, return shape, failure behavior (gaps[], contradictions[]), citation fetchability, and scope boundaries. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds meaning beyond the schema by clarifying what each depth level actually does (quick=single hop, standard=gap recovery + contradictions[], thorough=6 facets + iterative lead-chasing) and confirms that broad/multi-part natural-language questions are acceptable. This is helpful incremental value, though the schema alone is already strong.

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 is specific about what this tool does: grounded multi-source research across Pipeworx's 1500 structured data sources in one call, with decomposition into facets and parallel routing to 5,743 tools. It explicitly contrasts itself with open-web search and names sibling ask_pipeworx for single lookups, making its purpose and differentiation clear.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also states when NOT to use it: for single lookups use ask_pipeworx, and for breaking/colloquial current-news topics prefer ask_pipeworx because deep_research returns mostly empty gaps[]. Account requirements and depth-tier conditions are also spelled out.

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 and idempotentHint=true, making it safe and idempotent. The description adds context about returning top-N relevant tools with full schemas and examples, confirming the behavior. 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 well-structured paragraph that front-loads the purpose. It includes a list of domains, which is slightly verbose but helpful. It could be more concise by trimming the domain list, but it 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?

Given the tool's complexity (multiple parameters with aliases, no output schema), the description covers what it does, how to use it, and what it returns. It explains the result format (schemas with examples) and usage hint. Some details like error handling are missing, but overall it is complete 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%, so baseline is 3. The description adds value by explaining the query parameter's aliases (task, q, etc.) and providing examples like 'look up FDA drug approvals'. It also clarifies the limit parameter's default and max. This goes beyond the schema's brief 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?

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes itself from sibling tools by focusing on discovery rather than direct data retrieval. It is specific and actionable.

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

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

Description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it. However, it lacks explicit exclusions (e.g., when you already know the tool), which would elevate it to a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent non-destructive. The description goes far beyond by detailing the fan-out across sources, the meaning of empty sections (real 'no data' not bugs), the USPTO PatentsView sunset soft-fail, the expected empty FDA products for small-molecule companies, and the return of sources_used/sources_failed. This is rich behavioral context not present in 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 every sentence adds value—trigger examples, fan-out list, return fields, caveats, and edge cases. It front-loads the purpose and usage, then structures the rest with semicolons. It could be tightened, but the density justifies its length 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?

With no output schema, the description carries the burden of explaining return structure, and it does: it lists all key fields (cik, company_name, recent_filings, fundamentals, patents, etc.), explains sources_used/failed, and covers behavioral edge cases like private companies and empty FDA sections. An agent has everything needed to interpret and call the tool correctly, with no major gaps.

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

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

Schema description coverage is 100% and already documents both `type` and `value` with the same interchangeability and accepted shapes. The description restates that 'type' accepts either value and mentions name-resolution via SEC EDGAR, but adds little beyond the schema. With full coverage, baseline 3 is appropriate; the restatement is helpful but not novel.

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 precise verb+resource: 'full cross-source profile of a US public company' via one parallel call. It explicitly lists example triggers ('Tell me about X', 'research Acme') and distinguishes itself from chaining single-pack lookups, making its purpose unambiguous and differentiated from siblings like deep_research or resolve_entity.

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

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

It gives concrete trigger phrases, explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and covers edge cases like private companies (resolved:false with a notes line). This provides clear when-to-use and implicitly when-not-to-use guidance, though it could name an alternative tool explicitly (e.g., for single filings).

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses the CF-robust fallback mechanism: 'fetches directly and falls back to a proxy if the source blocks the gateway'. This adds valuable behavioral context not in 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 short, front-loaded sentences. First sentence covers purpose and key behavior (normalize, CF-robust). Second sentence provides usage guidance. 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 low complexity (3 params, no output schema, but good annotations), the description covers purpose, behavior, and usage hint. It does not detail the return format or normalization specifics, but it is sufficient for an agent to use correctly.

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

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

Schema description coverage is 100% with clear descriptions for all 3 parameters. The description does not add further detail on parameters beyond what the schema provides, so it meets the 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?

Clearly states the verb 'Fetch' and resource 'any RSS/Atom/RDF feed by URL', distinguishing it from siblings like 'list_feeds' (curated sources) and 'read_feed' (likely reading already fetched content). Mentions normalization.

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 'Use list_feeds first for curated sources', which guides the agent to the appropriate sibling for that use case. Directs agent to the right 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 idempotentHint=true. Description adds 'clear sensitive data' context but does not go beyond what annotations indicate. No contradiction.

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

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

Two concise sentences: first states action, second provides usage guidelines and tool pairing. No wasted information.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description sufficiently covers purpose, usage, and pairing. Lacks details on behavior after deletion (e.g., confirmation), but adequate for a simple delete operation.

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

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

Schema coverage is 100% with a clear parameter description. The description adds 'by key' which aligns with schema, but no additional meaning beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the action and resource. It also references sibling tools 'remember' and 'recall,' distinguishing the tool's role.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' No when-not-to-use or alternatives, but context is clear.

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

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

Annotations already convey readOnly, idempotent, and non-destructive nature. The description adds that the tool fetches the URL (network call), extracts specific elements, and produces a standard markdown blob. This complements the annotations without contradiction and provides insight into the output format.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value. No fluff or redundancy.

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

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

Given rich annotations and full schema coverage, the description is complete. It explains the output format (single text blob for site-root/llms.txt), the extraction process, and the intended use. No gaps in essential context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds critical details beyond schema: the default value for max_links (25) and its maximum (50). This significantly helps an agent choose appropriate values.

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

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

The description clearly states the verb 'generate' and resource 'llms.txt file', specifies the process (fetches page, extracts metadata, emits markdown), and distinguishes from a broad set of unrelated sibling tools. It provides concrete use cases, making the purpose unmistakable.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing). It does not specify when not to use it or directly compare to siblings, but the use cases provide clear context for when this tool is appropriate.

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 cover safety and idempotency; description adds field names and filter options. No contradictions, but could mention pagination or output format.

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, front-loaded with purpose, zero waste.

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

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

Given simple functionality, complete with returned fields, optional filters, and pointer to read_feed. Annotations fill 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 has 100% coverage; description only rephrases schema info, adding no new meaning.

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 lists feeds with optional filters and references sibling tool read_feed, making purpose unambiguous.

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

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

Implicitly tells when to use this vs read_feed (list vs specific feed), but lacks explicit 'when not to use' or other 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 cover safety (readOnly, idempotent, non-destructive). Description adds minor context about return fields but no additional behavioral traits. No contradiction.

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

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

Two concise sentences: first explains purpose and output, second gives usage guidance. No redundant words.

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

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

For a simple list tool with one optional parameter, the description covers purpose, usage, return fields, and parameter. Annotations provide safety context. Complete.

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

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

Schema already covers the single parameter with full description. The description does not add parameter-specific meaning beyond what's in the schema.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and specifies the return fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Does not explicitly state 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?

Despite annotations carrying no useful hints (all false), the description fully discloses behavior: filing returns a claim_token, which can be passed later to check status, rate-limiting to 5 per identifier per day, free quota, and daily human review. This goes well beyond the annotations and sets clear expectations.

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

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

The description is a single dense paragraph but is front-loaded with the tool's purpose and use cases, and every sentence contributes meaningful information (exclusions, token flow, rate limits, quota). It could be more scannable with structured sections or bullets, but it is not verbose or redundant.

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

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

Given the tool's medium complexity, no output schema, and minimal annotations, the description covers the necessary context: what to report, how to phrase it, token-based follow-up, and rate limits. A minor gap is that it does not explicitly describe the return payload when an account is used or when the claim_token is resolved, but this is enough for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable guidance beyond the schema: it warns against pasting end-user prompts and explains the claim_token round-trip workflow, making the parameter semantics more actionable. It does not, however, add extra detail to the type or context parameters beyond the schema.

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

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

The description opens with a specific verb+resource pairing—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and immediately enumerates the concrete use cases (bug, feature/data_gap, praise). This clearly distinguishes the tool from sibling tools like ask_pipeworx or discover_tools.

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

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

It provides explicit when-to-use guidance (wrong/stale data, missing tool, praise) and explicit when-not-to-use guidance (feedback about non-Pipeworx MCP servers, with instruction to file those with the respective server). It even offers a heuristic for disambiguation ('Pipeworx tool names are the ones this connection lists').

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 context beyond annotations: caching duration (5min-1h), data source (CF analytics-engine), no PII, and self-aggregating nature. Annotations already cover read-only, idempotent, and non-destructive traits.

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

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

The description is concise and front-loaded with the return value and use cases in bullet points, with 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?

For a simple read-only tool, the description covers caching, data source, privacy, and use cases. Lack of output format details is acceptable given the description's clarity on what is returned.

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 repeats the schema's parameter explanation verbatim, adding 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?

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, distinguishing it from siblings like discover_tools by focusing on what other AI agents are calling.

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 lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases) but does not mention when not to use or name alternatives.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) already indicate safety. The description adds substantial behavioral details: algorithms used (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and explicit advice not to trade when realizable edge ≤ 0. 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 with clear sections for each mode and sub-mechanisms. Though long, every sentence adds unique value—no filler or redundancy. Information is front-loaded with the primary purpose and usage guidance.

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 the lack of an output schema, the description fully explains the response structure (opportunities array with fields, partition_check object, fill check details). It also covers edge cases (default behavior, topic mode limitations, when not to trade). For a complex tool, the description is thorough and sufficient.

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: it explains that 'event' expects Polymarket event slugs like 'fed-decision-may-2026' and that 'topic' expects a seed question. It also clarifies the default behavior when neither parameter is provided. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and describes the default trending scan. The purpose is specific and verifiable.

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

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

Explicit guidance is provided for when to use each parameter: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event for specific markets and topic for cross-event scanning. It also mentions an alternative tool (polymarket_fill_risk) for custom sizing.

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 goes far beyond, detailing the three model families, the 24h-move warning, the diagnostics for empty segments, and caching behavior ('Cached 1h at the KV level'). It provides transparency on how edges are computed and why certain opportunities might be suppressed.

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

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

The description is thorough but verbose, using dense paragraphs with many embedded explanations. While it is well-structured with sections and key terms in uppercase, some sentences could be streamlined. The front-loading of purpose and then detailed breakdown is effective, but the overall length might overwhelm a quick scan.

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

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

Given the complexity (9 parameters, no output schema, nested structures), the description is remarkably complete. It outlines the response structure (by_segment, fed_candidates, _diagnostics), explains each segment's methodology, and describes caching, tradeable-edge filters, and edge cases (Fed bets, placeholder slugs). No gaps remain for an agent to understand what the tool returns and how to use it.

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

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

With 100% schema coverage, the description adds substantial meaning beyond the schema. For example, it explains that min_kelly filters 'opportunities that are too small to bet sensibly even if the edge is large' and that slippage_pp is 'subtracted from raw |edge| before ranking and Kelly sizing.' It also clarifies interactions like min_partition_leg_kelly applying to per-leg Kelly for partitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scan and return), and the unique value (discovering opportunities without paging). It distinguishes itself from siblings like polymarket_arbitrage by detailing its internal segments and tradeable-edge knobs.

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 frames the use case as 'what should I bet on today' and explains how knobs (min_liquidity, max_spread_pp) filter opportunities. It also notes that Fed bets are excluded from ranking. However, it does not explicitly contrast with sibling tools like polymarket_edge_tracker or polymarket_arbitrage, leaving some ambiguity about when to prefer this tool over those.

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

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

The description adds significant behavioral context beyond annotations: the rationale for decay analysis, specifics of the response structure (tracked, expired, snapshot_dates), and limitations (60-day TTL, daily closes not intraday). This enriches the agent's understanding of what the tool does and its constraints.

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, front-loading the core purpose and then detailing parameters, response, and limits. While verbose, every sentence adds meaningful information, and the structure facilitates quick parsing.

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

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

Given no output schema, the description fully explains the return fields and their semantics. It also covers limits and potential gaps (snapshot gaps). This ensures the agent knows exactly what to expect.

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

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

With 100% schema coverage, the description adds value by specifying defaults (days=14, window='1wk'), value ranges (days clamp 2-30), and clarifying the meaning of 'window' (snapshot family). This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific language ('answers how long has this edge existed and is it shrinking?') and distinguishes from sibling tools like polymarket_edges by focusing on temporal aspects.

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 if an edge is fresh or decaying) and implies when alternatives might be better (e.g., for current edges, use polymarket_edges). It provides context but lacks explicit when-not-to-use or alternative tool names.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds behavioral details: walks the ladder, returns slippage, fill details, and verdict for single-market; for basket, captures ratio, thin legs, and forced directional risk. No contradictions with annotations.

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

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

The description is dense yet well-structured with clear sections for single-market mode, basket mode, and usage guidance. Every sentence serves a purpose, no unnecessary text, and it is front-loaded with the core function.

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

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

Given the tool's complexity (two modes, multiple outputs, no output schema), the description thoroughly covers behavior, return fields (top_of_book, vwap, slippage, verdict, per-leg detail, etc.), and risk considerations. It provides all necessary context 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 description coverage is 100%, baseline 3. The description adds extra meaning: side defaults depend on mode (auto for basket), size_usd interpretation differs (max spend vs target proceeds for single-market, settlement notional for basket), and clamp limits are mentioned.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing single-market and basket modes, and lists specific return fields like top_of_book, vwap_fill_price, slippage_pp, and verdict. This precisely defines the tool's purpose and differentiates it from sibling Polymarket tools.

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

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

The description explicitly instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500, and warns about partial basket fills converting arbs to unhedged positions. It provides clear when-to-use context but does not exhaustively list 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?

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false already present, the description still adds extensive behavioral detail: compatibility_warning and compatibility_codes behavior, the meaning of null temporal_alignment, unclassified legs never being paired, skipped comparison counters, and the standing disclosure that spreads are gross and do not model Kalshi fees. This is far beyond what annotations convey.

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

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

The description is long and dense, but nearly every sentence carries safety or behavioral nuance needed to interpret the tool's output correctly, and the structure is front-loaded with purpose and modes. Some repetition of the compatibility-code explanations could be trimmed, but the complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, temporal_alignment, fees_note, skipped counters, and low-confidence pairs are all covered. An agent has enough information to call the tool and correctly interpret its response.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains that topic auto-fetches the matching event on each venue, that explicit kalshi_event_ticker and polymarket_event_slug override the mapped sides, and that both modes run the identical token-overlap matcher. This goes beyond the raw schema descriptions without being redundant.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific delimited outcome and two modes. It does not explicitly differentiate itself from closely related siblings like polymarket_arbitrage, though the Kalshi–Polymarket pairing and spread framing make the core purpose unambiguous.

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

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

The description gives clear when-to-use context: it explains the two modes, when to use topic shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics are not necessarily tradeable. It does not name alternative sibling tools or state explicit exclusion conditions, but the mode-selection guidance and caveats provide strong practical orientation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the curated nature of the feed and the filtering capability, which are behavioral traits beyond what annotations provide.

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

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

The description is only two sentences, front-loaded with the core purpose, and efficiently includes key details about return format and optional filtering. 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 simplicity of the tool (3 parameters, no output schema) and the presence of comprehensive annotations, the description is fully adequate. It covers the feed source, return structure, and optional filtering.

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%, meaning all parameters are described in the input schema. The description adds minimal extra meaning (e.g., query filters over title/summary), but the schema already covers this. Baseline is 3.

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

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

The description clearly states the tool reads a curated feed by ID, specifies the return format (normalized items with title, link, published, summary), and distinguishes from sibling tools like list_feeds and fetch_feed by focusing on curated entertainment/culture feeds.

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 references 'from list_feeds' to indicate prerequisite knowledge, and the optional keyword filter is mentioned. However, it does not explicitly state when not to use this tool or provide alternatives beyond the implicit 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about identifier scoping and pairing with other tools, but does not contradict annotations.

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

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

Three concise sentences, front-loaded with core action, then usage guidance, then scoping. No redundant 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 simplicity (1 optional param, no output schema, good annotations), the description completely covers retrieval, listing, scoping, and pairing with remember/forget.

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

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

Schema coverage is 100% for single param 'key'. Description adds meaning by explaining that omitting key lists all keys, which goes beyond schema description.

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

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

The description uses specific verb-resource pair ('Retrieve a value previously saved via remember, or list all saved keys') and clearly distinguishes from sibling tools like remember and forget.

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

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

Explicitly states when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget.

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 contradicts annotations: readOnlyHint=true but description says mark_read:true flags events read, implying a state change. Such contradiction undermines trust. Otherwise, description does disclose filter behavior and mark_read effect.

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, no extraneous information. Front-loaded with purpose, then details. Every sentence serves a purpose. Efficiently covers key aspects.

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 summarizes return fields (source, citation_uri, raw payload). Covers filtering and mark_read behavior. Could mention sorting or pagination details, but adequate for most use cases.

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

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

Schema coverage is 100%, baseline 3. Description adds value with examples (e.g., 'sec_8k'), clarifies 'since' as ISO timestamp, and explains default and range for limit. Exceeds baseline by providing concrete usage guidance.

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

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

Clearly states the verb 'pull' and resource 'fired events from your subscription feed'. Specifies return fields (source, citation_uri, raw payload) and filtering options (type, since). Differentiates from sibling tools by detailing specific capabilities.

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

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

Provides context on when to use (polls work fine) and an alternative via direct HTTP endpoint. Mentions mark_read behavior for state management. However, does not explicitly compare to similar sibling tools like read_feed or fetch_feed.

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

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

Annotations already mark the tool as readonly, idempotent, and non-destructive. The description adds valuable behavioral details: it fans out to multiple sources, has a fallback mechanism for news (GDELT preferred, GNews on rate-limit/5xx), and notes that USPTO patents may soft-fail until reactivated. It also explains the 'since' parameter format. This goes beyond annotations.

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

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

The description is a single, dense paragraph that conveys all necessary information. It's front-loaded with example queries. While it's efficient, it could be slightly more structured (e.g., bullet points for sources) to improve readability. Still, every sentence contributes meaning.

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

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

Given the 3 parameters, absence of output schema, and rich annotations, the description is complete. It explains the tool's behavior, sources, fallback, and return structure (changes grouped by source, total count, citation URIs). It also directs users to an alternative tool for static profiles. No gaps remain.

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

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

Schema coverage is 100%, with descriptions for all three parameters. The description adds meaning: it clarifies the 'since' format with examples (ISO date and relative shorthand), explains 'value' accepts ticker or CIK, and notes 'type' is restricted to 'company'. This adds value 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 provides a change feed for a company, covering SEC filings, news, and patents. It lists example queries ('What's new with X', 'latest on Y') and explicitly distinguishes from sibling 'entity_profile' which is for static profiles. The verb 'fan out' and specific sources make the purpose unambiguous.

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

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

The description gives explicit direction: 'Use entity_profile instead when you want the static profile...' It also explains fallback behavior between GDELT and GNews. However, it could more explicitly state when not to use this tool (e.g., if you need only one source or real-time data). Overall, the guidance is helpful and clear.

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

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

Annotations idempotentHint=true, destructiveHint=false, readOnlyHint=false. Description adds context: scoped by identifier, 24-hour retention for anonymous. No contradictions.

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

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

Front-loaded with purpose, then usage, then behavioral details. Every sentence adds value; no waste.

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 key-value store with no output schema, the description provides all necessary information: persistence, scope, pairing with other 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 covers both parameters with descriptions (100% coverage). Description adds useful examples like 'subject_property' and clarifies that value can be any text, slightly exceeding schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples. It distinguishes from siblings like 'recall' and 'forget'.

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

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

Explicitly advises when to use: 'when you discover something worth carrying forward'. Pairs with recall and forget, and clarifies scope and persistence differences between authenticated and anonymous users.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description greatly enriches this by explaining multi-source cascades (EDGAR, GLEIF, OpenFIGI), graceful degradation, explicit unresolved identifiers, and figi_candidates behavior. This goes well beyond the annotation-only picture.

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

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

The description is long but densely packed with actionable guidance, front-loaded with example queries and the core use case. Most sentences add distinct value, though a few parentheticals and explanatory asides could be trimmed without losing meaning.

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

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

Given the tool's complexity, multiple entity types, and lack of an output schema, the description is remarkably complete. It covers accepted inputs, return semantics, ambiguous-match behavior, unresolved-identifier handling, and failure degradation for upstream sources, leaving an agent well-equipped to invoke it correctly.

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

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

The schema covers both parameters at 100%, but the description adds valuable semantics: it explains that 'value' must be the entity name only (with the bond issuer example), clarifies accepted input forms like ticker/CIK/ISIN/name, and details what each type resolves to. This meaningfully exceeds the schema descriptions.

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

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

States a specific verb ('resolve') with a clear resource (user-spoken names to canonical identifiers) and explicitly lists the identifier types handled (CIK, ticker, LEI, FIGI, RxCUI). It also implicitly distinguishes from sibling tools by noting these identifiers are what other tools require as input, making the tool's niche clear.

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

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

Gives explicit guidance with 'Use FIRST whenever you have a name but need an ID' and details supported entity types with input examples. It does not explicitly name alternatives or state when not to use the tool, so it falls short of a full 5.

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

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

Describes internal process (probing with ai_visibility_check, ranking, surfacing most/least recognized) and output fields (score, confidence, signal density). Annotations already indicate read-only and idempotent; description adds non-redundant detail.

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

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

Two purposeful sentences plus a clarifying parenthetical. No wasted words; front-loaded with action and purpose.

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

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

With no output schema, the description fully explains return structure (ranked list with score, confidence, signal density). Process and parameters are adequately covered given schema richness and annotations.

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

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

Adds meaning beyond 100% schema coverage: clarifies that the first entity in 'entities' is treated as subject for narrative, and explains how 'models' and 'context' are used. This contextualizes parameter 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?

Specific verb 'Compare' and resource 'AI visibility across multiple entities', clearly distinguishing from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 usefulness for competitive AI-marketing audits and the question it answers. Does not list exclusions, but context implies it's for multi-entity comparison vs. single entity check.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals fan-out across two APIs (deps.dev, bundlephobia), partial failure degradation with 'sources_failed', and timing details (bundlephobia first measurement 5-30s). This adds significant behavioral context 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 detailed but each sentence contributes essential information: composite nature, usage guidance, return format, and limitations. While slightly long, it is well-structured and free of fluff.

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

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

Given no output schema, the description lists all return fields (summary block, advisories, links, alternative versions) and explains data sources and failure modes. For a complex composite tool, this is highly complete.

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

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

Schema coverage is 100%, but the description adds value by explaining that scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. This enriches the semantic understanding beyond the schema descriptions.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, covering license, security, bundle size, and more. It specifies the verb 'scan' and resource 'dependency', and distinguishes from sibling tools which are unrelated (e.g., betting, AI visibility).

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM-only in v1 and directs to deps.dev:version for other ecosystems, providing clear when-to-use and when-not-to alternatives.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral details: embedding model ('BGE-base-en embeddings'), similarity measure ('cosine'), window size ('500-char overlapping windows'), character limit ('cap is 200K chars, longer inputs truncated and flagged'). This fully discloses what happens under the hood.

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, each serving a distinct purpose: core purpose, use case guidance, and technical details. It is front-loaded with the main action and efficiently conveys all necessary information without redundancy.

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

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

Given the complexity of the tool (semantic search, embedding, truncation), the description covers input constraints (200K char limit), output format ('top-N passages with character offsets and similarity scores'), and integration with a sibling tool. There is no output schema, but the description adequately conveys what the agent can expect.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds usage examples for the query parameter and clarifies the text parameter as 'document text', but does not add critical new information beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying it returns top-N passages with offsets and scores. It distinguishes from sibling ask_pipeworx_grounded by explaining how it pairs and differs: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides a clear use case and differentiation.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also mentions an alternative workflow ('Pairs with ask_pipeworx_grounded'). However, it does not provide explicit when-not-to-use instructions or list other alternatives beyond that one sibling.

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

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

Annotations indicate non-readonly, non-destructive, and idempotent. The description adds valuable context: OAuth requirement, per-type parameter examples, delivery channel details (email, SMS with caps, webhook with auto-disable after failures), and return of subscription id. No contradictions with annotations.

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

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

The description is relatively concise given the complexity, front-loading the core action. It organizes details logically (types then delivery). A few more sentences could be trimmed, but the clarity justifies the length.

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

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

The description covers purpose, return value, auth, types, and delivery options comprehensively. It does not mention error scenarios or explicit idempotency behavior, but for a creation tool with no output schema, it provides sufficient guidance for agent invocation.

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

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

Schema coverage is 100%, but the description enriches parameters with concrete examples (e.g., sec_8k with items:["5.02"]) and explains nested delivery objects (email format, SMS verification, webhook signing). This goes well beyond the schema's minimal 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists specific subscription types and delivery channels, distinguishing it from siblings 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 explains the tool's purpose and requirements (e.g., Pipeworx OAuth account) but does not explicitly contrast with alternative tools. However, the context makes it clear that this is the creation tool, and siblings handle listing and deletion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about returning category-bucketed example questions with exact tool+argument shapes, which is beyond what annotations provide.

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

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

The description is front-loaded with the purpose and examples. It is somewhat lengthy but each part adds value (examples, categories, instruction). Could be slightly tighter but overall efficient.

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

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

Given the annotations cover safety, the schema covers the parameter well, and there is no output schema, the description fully explains what the tool returns (category-bucketed examples with tool calls) and when to use it. It is complete for an onboarding 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 one optional 'topic' parameter. The description provides additional meaning: lists example topics ('finance', 'pharma', etc.) and explains that omitting it gives a cross-category spread. This adds value beyond the schema's description.

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

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

The description clearly states the tool as an onboarding entry point that returns categorized example questions with exact tool calls. It distinguishes from sibling tools by being the first tool to use when uncertain about Pipeworx's capabilities.

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 instructs to use this FIRST when you don't know what Pipeworx can do. It also explains how to focus on a topic using the 'topic' parameter. Implicitly suggests when not to use (when you already know).

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 value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. 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 concise sentences, front-loaded with the core action, 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?

Fully adequate for a single-parameter tool with annotations and no output schema; covers purpose, ownership constraint, and soft-delete behavior.

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

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

Schema coverage is 100%, and description adds minimal extra meaning beyond schema field description. Baseline score appropriate.

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

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

Clearly states the action (cancel a subscription by id) 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?

Explicitly mentions ownership enforcement (only cancel own subscriptions), providing context for when the tool is applicable. Could mention alternatives explicitly but 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 mark the tool read-only, open-world, idempotent, and non-destructive. The description adds crucial behavior: exact verdicts, the distinction between could_not_verify and unsupported, and the fact that could_not_verify is not evidence for or against a claim — none of that is in 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 paragraph is dense but well-organized, leading with trigger phrases and usage, then return semantics, then critical caveats. It's not the shortest description, but the length is justified by the tool's complexity and no sentence is 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?

With no output schema, the description fully enumerates the verdict values, citation format, and reasoning return. It also explains the two failure statuses and the fast-path vs grounded routing, making it complete for a complex verification tool.

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

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

Input schema covers 100% of parameters and provides detailed descriptions for both claim and tolerance_pct. The tool description adds minimal parameter-specific meaning (e.g., percent-delta math) beyond the schema, so it stays at the baseline for high schema coverage.

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

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

The description names the specific verb 'verify' and resource 'claim,' and opens with natural-language trigger phrases. It clearly distinguishes the tool from siblings by focusing on claim verification against authoritative sources with a verdict output.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' establishing when to choose it. It also explains the financial vs general routing and notes it replaces 4–6 sequential calls, but doesn't explicitly name sibling tools as alternatives not to use.

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