Themeparks

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the return format (per-model {score, confidence, signals, raw_response} + combined view), cost implications (free default, BYO key for Anthropic), and the fact that it probes external LLMs. It does not contradict annotations.

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

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

Description is four sentences, front-loaded with the core action and output. Each sentence adds essential information without redundancy or verbosity.

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

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

No output schema exists, so the description must explain return values, which it does clearly. All four parameters are described with sufficient context. Minor gap: does not mention error handling or rate limits, but is otherwise complete for the tool's purpose.

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 meaning beyond schema: provides example values for entity ('Pipeworx'), clarifies default model for models, explains necessity of _apiKey for Anthropic, and gives disambiguation example for context. This extra context elevates the score.

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

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

The description clearly states the action ('probe one or more LLMs', 'score visibility'), specifies the resource ('business / brand / product / topic'), and provides a 0-100 score range. It distinguishes itself from siblings by being unique in function; no other sibling tool performs AI visibility checks.

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 examples ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model behavior and how to include Anthropic with an API key. However, it lacks explicit when-not-to-use or mention of alternative tools, though no siblings overlap.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it routes to one of many tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and explicitly routes breaking-news queries to live news sources. This is solid behavioral disclosure, though it stops short of describing failure modes or edge cases.

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

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

The description is long, but the length is warranted for a broad meta-tool that dispatches across thousands of sources. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and organized into use triggers, examples, and alternative routing. A little redundancy exists in the repeated examples and domain lists, so it is not maximally concise, but every section earns its place.

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

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

Given the tool's complexity — no output schema, one free-text parameter, and a routing behavior over thousands of tools — the description provides enough context to call it correctly. It explains what the tool does, when to prefer it, what the output includes (structured answer with citation URIs), and how it compares to siblings. Nothing critical is missing for an agent to decide to invoke it.

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

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

Schema description coverage is 100% — the schema already documents the 'question' parameter and its aliases. The description adds helpful example questions and clarifies that the input is a natural-language factual query, but it does not add substantial parameter-level semantics beyond the schema. Baseline 3 is appropriate given the 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 uses a specific verb and resource: it 'routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes itself from web search and lists concrete domains it covers, so an agent can identify when this tool is the intended one.

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 is exceptionally explicit about when to use this tool: 'PREFER OVER WEB SEARCH' for factual questions, and 'START HERE for most questions.' It also names alternatives and the conditions that select them: use ask_pipeworx_grounded for crawler-based live pages and deep_research for broad/multi-part questions, which gives the agent clear routing logic.

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

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

Beyond the readOnly/idempotent annotations, the description reveals the beta status, that no candidate is currently active, the retirement date of the last candidate, and that it currently matches ask_pipeworx exactly. This is unusually transparent about experimental behavior.

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

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

The description is front-loaded with the core identity and includes only relevant operational detail. It is slightly verbose with the specific tool count and date, but each sentence contributes useful context.

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

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

The description gives enough context for an agent to understand the tool's role, current behavior, and relationship to ask_pipeworx. The response shape is referenced but not detailed, and since there is no output schema, a bit more specificity would improve completeness.

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

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

The input schema already provides 100% coverage and clearly documents all six properties as aliases for 'question.' The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with the same 5,798 tools, arguments, and response shape. It distinguishes the tool from its stable sibling by calling out 'candidate routing improvements' and the experimental edge.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router. It also preempts a likely misuse by clarifying 'Falls back to nothing — this IS a full working router.'

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals refusal behavior, the exact refusal_reason enum, the guarantee that only tool results are used, and the return shape including evidence, confidence, and fetched_at. This is substantial behavioral disclosure that an agent needs to predict outcomes correctly.

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

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

Every sentence earns its place: mode, routing behavior, return contract, refusal contract, use cases, and cost/alternative. The most important differentiator ('hallucination-resistant') is front-loaded, and the rest is dense but not padded.

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 no output schema, the description fully compensates by specifying success and refusal payloads, failure reasons, source behavior, and when to choose the sibling. Nothing an agent needs to decide between this and ask_pipeworx 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 fully documents the question parameter and its aliases. The description adds no new parameter-level detail beyond implying the natural-language question is the sole input. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description uses a specific verb ('answer') with a defined mode ('hallucination-resistant', 'grounded') and clearly distinguishes this tool from ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains'. It also names the sibling routing and what makes this variant different, so an agent can select it without ambiguity.

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

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

Explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also gives a direct alternative preference: 'prefer ask_pipeworx for casual lookups' and discloses the extra LLM call cost, making the trade-off concrete and actionable.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds extensive behavioral context: safety mechanisms (low-confidence short-circuit, closed market handling), resolution-rule risk, cancellation rule parsing, response shapes, and edge cases like wide spreads. It significantly enriches the agent's understanding of tool behavior.

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

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

The description is front-loaded with purpose and usage, then systematically details classifiers, fan-out examples, response shapes, and safety. While lengthy, every sentence adds essential information. It could be slightly more concise by grouping related details, but remains well-organized.

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

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

The tool is complex (multiple classifiers, fan-out to various sources, detailed response shapes). The description covers all essential aspects: input formats, behavior, output structure, edge cases, and safety. Since there is no output schema, the description fully compensates by explaining return values and fields like resolver contract and parent_event.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context: 'market' accepts slug, URL, or question text; 'depth' and 'include_raw' are explained with practical recommendations. This goes 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 uses a specific verb ('Research') and resource ('a Polymarket bet by pulling the relevant Pipeworx data'), clearly distinguishing the tool from siblings like polymarket_edges or validate_claim. It states the tool's core function in the first sentence and provides concrete usage examples.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also explains classifiers and fan-out patterns. However, it does not explicitly state when not to use it or mention alternative tools, which would clarify boundaries further.

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

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

Description adds significant behavioral context beyond annotations: off-calendar fiscal year handling, specific metrics pulled, sorting behavior, and output format with citation URIs. Annotations already indicate read-only, idempotent, open-world, non-destructive; description reinforces and details.

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

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

Concise yet comprehensive: trigger phrases first, then core purpose, type-specific details, sorting, output references. No wasted words.

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

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

Covers all necessary aspects for an agent to decide and invoke correctly: inputs, data sources, accuracy notes, output shape (paired data + URIs). No gaps despite lack of output schema.

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

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

Schema already defines parameters with enums and array constraints (100% coverage). Description adds examples (e.g., tickers, drug names) and clarifies meaning of values for each type, which is helpful but not essential given schema completeness.

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 does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases. It distinguishes from siblings by explicitly preferring over sequential single-entity 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?

Provides explicit guidance on when to use (comparisons, rankings) and when not (sequential lookups). Also explains type-specific use cases and data sources.

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

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

The description goes well beyond the annotations by disclosing auth requirements, latency expectations, parallel execution, the gaps[] guarantee that findings are never invented, citation URI resolvability, contradictions[] behavior, and semantic excerpting. These are meaningful behavioral details that annotations like readOnlyHint and idempotentHint do not 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 dense but generally front-loaded: account requirements and the ask_pipeworx alternative appear first, then core behavior, depth nuances, and performance expectations. It is longer than strictly necessary because some depth and citation details overlap with the schema or are restated, but each sentence still adds meaningful context.

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

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

Even without an output schema, the description documents the return packet's key fields, citation behavior, gaps[], contradictions[], latency, authentication, and boundary with ask_pipeworx. For a complex parallel-research tool, this is enough for an agent to know what the tool does, what to expect, and when to choose it.

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

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

Schema coverage of both parameters is 100%, so the baseline is 3. The description adds value by explaining how depth levels behave in terms of hops, gap recovery, contradiction scanning, and the paid tier, and by clarifying that the question is meant to be broad or multi-part. Some depth details repeat the schema enum descriptions, preventing a 5.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call, with decomposition and parallel routing. It also directly distinguishes itself from open-web search and names the single-lookup sibling ask_pipeworx, so an agent can tell them apart.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data are the sweet spot, single lookups should use ask_pipeworx, and unsigned-in users should use ask_pipeworx. It also discloses the paid-plan requirement for the thorough depth, which is a concrete usage constraint.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds that results include full schemas and are ready to call, reinforcing safe, non-destructive behavior 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 front-loaded with purpose and usage, though the list of domains is lengthy. It remains efficient and focused, with minimal 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 no output schema, the description adequately describes return format (top-N tools with schemas). It covers the core use case and invocation order, missing only error handling or edge cases.

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

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

Schema coverage is 100% with descriptions for each parameter. The description supplements with alias information and explains the 'limit' parameter's defaults, adding value beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists numerous domains, making the tool's purpose explicit and distinct from siblings which focus on specific tasks.

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 advises 'Call this FIRST when you have many tools available' and enumerates scenarios like 'browse, search, look up', providing clear usage context but no explicit exclusions.

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

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

The description goes far beyond the annotations: it discloses parallel fan-out across multiple data sources, sources_used/sources_failed semantics, the meaning of empty sections as real 'no data', the resolved:false behavior for private companies, and expected absence of fda_products for small-molecule-only companies. This is exceptional behavioral disclosure.

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

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

The description is a single dense run-on paragraph with nested parentheses and a garbled fragment ('patents (USPTO patents'; 'fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted ...)'). It front-loads usage examples but then dumps a long unstructured list of return fields, making it hard to scan despite the valuable content.

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

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

With no output schema, the description compensates well by covering input formats, source fan-out, fallback behavior, no-data semantics, and private-company resolution behavior. The only gaps are the garbled return-field list and the lack of a concrete output example, leaving minor ambiguity about the exact response shape.

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 already documents ticker/CIK/company-name input, name resolution via SEC EDGAR, and type interchangeability. The description adds a private-company failure behavior and resolved_from/resolved_to notes, but largely repeats what the schema already states, so it stays at 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?

The description opens with concrete user queries and a crisp statement: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact resource (company profile) and scope (cross-source, holistic), and explicitly contrasts with single-pack SEO/XBRL/news lookups, making it easy for an agent to distinguish from sibling tools.

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

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

The description provides explicit trigger examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and a clear directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It does not name sibling tools like get_entity or resolve_entity explicitly, but the holistic-vs-single-pack contrast gives a strong usage signal.

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 destructiveHint=true, so the description adds value by specifying 'clear sensitive data' context, but does not add much beyond that.

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

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

Two efficient sentences, front-loaded purpose, no waste; every sentence earns its place.

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

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

For a simple delete tool with one parameter and strong annotations, the description adequately covers purpose and usage, though missing potential edge cases (e.g., what if key doesn't exist) is minor.

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 does not add extra meaning beyond the schema's 'Memory key to delete'. Baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use ('context is stale, task is done, or clear sensitive data') and pairs with related tools, providing clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe, idempotent operation. The description adds valuable behavioral details: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. No contradictions.

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

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

The description is a single paragraph of three sentences, each serving a purpose: stating the action, explaining the process, and listing use cases. No wasted words; 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 simplicity (2 params, no nested objects, no output schema), the description covers all necessary context: input (URL), optional param, process (fetch, extract, emit), and output format (text blob). The annotations further fill safety and idempotency 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 description coverage is 100%, so the baseline is 3. The description reiterates the parameters (url, max_links) but does not add significant new semantics beyond what the schema provides. It confirms default and max values for max_links, but that is already in the schema description.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the resource (URL) and action (generate), and provides concrete use cases, making it highly distinct from sibling tools.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it does not provide negative examples or alternatives, the given context is sufficient for an agent to understand when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds value by specifying the exact fields returned and the types of entities covered, providing context beyond the annotations.

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

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

Single sentence, no redundant information, front-loaded with key details. Highly concise.

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

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

For a simple read-only tool with one parameter and no output schema, the description is adequately complete. It could mention error handling or output format, but the core functionality is clear.

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 a clear description of entity_id. The tool description does not add new semantic information for the parameter beyond what the schema already provides.

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

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

Description clearly states it returns metadata for theme park entities and lists specific fields (name, type, location, timezone, parent ids) and entity types. It distinguishes from siblings like get_wait_times but could be more explicit about how it differs from entity_profile 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?

No explicit guidance on when to use this tool versus alternatives. The schema description hints at where to get entity IDs but does not provide usage context or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool returns data 'over the coming weeks', which provides temporal context beyond annotations. No contradictions.

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

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

Two sentences with no redundant wording. The description is front-loaded with the resource and provides a clear instruction. Every word adds value.

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

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

For a simple read-only tool with one parameter and no output schema, the description explains what the tool returns (hours over weeks) and how to get the entity_id. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100% and the description restates the parameter guidance ('Pass a PARK entity_id from list_destinations') without adding new detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('get' is implied by title) and resource: 'Park operating hours — opening and closing times for a theme park over the coming weeks'. This distinguishes it from sibling tools like 'get_wait_times' and 'list_destinations'.

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

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

The description provides a clear usage instruction: 'Pass a PARK entity_id from list_destinations'. This implies a prerequisite to call list_destinations first. It does not explicitly state when not to use it, but the context is sufficient for an agent to infer appropriate usage.

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 this is a read-only, idempotent, open-world operation with no destructive behavior. The description adds behavioral details: what data is returned (standby and single-rider queue minutes, operating status) and that it covers every attraction in a park, which adds value beyond annotations.

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

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

The description is concise and well-structured: two sentences that first explain the purpose and then provide usage instructions. No extraneous information, front-loaded with key details.

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

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

Given the absence of an output schema, the description compensates by explaining what the tool returns (standby and single-rider queue minutes, operating status). It is adequate for a single-parameter tool, though a more detailed example of the output could improve completeness. Context signals indicate low complexity, so the description is nearly complete.

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

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

Schema coverage is 100%, with the schema providing a description for entity_id ('A PARK entity id from list_destinations.'). The description reinforces this same information but does not add additional semantic detail. Baseline 3 is appropriate since the schema already covers the parameter meaning adequately.

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

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

The description clearly states that it returns live theme park wait times, including standby and single-rider queue minutes and operating status for every attraction in a park. It specifies the resource (live wait times) and the action (get/return), and differentiates from siblings by focusing on wait times specifically.

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

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

The description provides clear context: use this tool to get current wait times for a park, and requires passing a PARK entity_id from list_destinations. However, it does not explicitly state when not to use this tool or mention alternatives, which would improve guidance.

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

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

Annotations cover safety profile (readOnly, idempotent). Description adds workflow context (discovery of park IDs). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with purpose, followed by 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?

Complete for a parameterless, read-only listing tool with good annotations. Tells agent what it returns and how to use the output.

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?

No parameters in schema (coverage 100%), so baseline 4. Description doesn't need to add parameter info.

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

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

Clearly states it lists theme park destinations and parks, with specific examples. Differentiates from siblings by describing the workflow of using this tool first to get entity IDs for other tools.

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

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

Explicitly states when to use (first step) and provides next steps (feed entity ID to other tools). Missing explicit 'when not to use' or alternative tools, but the workflow guidance is strong.

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

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

Annotations already indicate read-only, idempotent behavior. Description adds details on returned fields and default filtering (active subscriptions). No contradictions.

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

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

Two sentences: first states purpose and output, second gives usage guidance. No fluff, front-loaded.

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

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

For a simple read-only tool with full annotations and schema coverage, description adequately explains behavior, return fields, and usage context. No gaps.

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

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

Schema coverage is 100% for the single parameter; description does not add further meaning but is consistent with schema. Baseline 3 is appropriate.

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

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

Description clearly states verb 'list' and resource 'subscriptions' for the caller, and specifies returned fields. It distinguishes from siblings 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?

Provides explicit use cases: 'review what you're monitoring' and '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?

Since all annotation hints are false, the description carries the full burden of disclosing behavior. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), the fact that filing returns a claim_token, that it is free and doesn't count against quota, and that the team reads digests daily. This goes well beyond the minimal safety info 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 lengthy but every sentence serves a purpose: usage, exclusions, token mechanics, rate limits, and quota impact. It is front-loaded with the core action and use cases, though the sentence about 'Pipeworx tool names are the ones this connection lists' is slightly redundant given the exclusion earlier.

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 explains all post-invocation behavior: returning a claim_token, how to check status later, rate limiting, and quota exemption. It fully covers the tool's lifecycle and boundaries, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage guidance not in the schema, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and clarifies the claim_token flow for checking status later. This adds value beyond the schema's dry 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb-resource phrase. It clearly distinguishes itself from siblings like ask_pipeworx by framing itself as feedback submission about Pipeworx tools, not a query tool.

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

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

The description explicitly states when to use it: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with the other server for different MCP servers.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: data source (CF analytics-engine), privacy assurance (no PII, only counts), caching behavior (5min-1h depending on window). This fully meets the behavioral transparency burden.

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

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

The description is four sentences with zero waste. It is front-loaded with the primary output, followed by bulleted use cases, then technical details. Every sentence contributes meaningfully.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the output, use cases, data source, privacy, and caching. No gaps remain given the tool's complexity and the richness of 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?

The schema covers the single parameter 'window' with 100% description coverage. The description adds semantic value by explaining the effect of different window lengths: shorter windows surface what's hot right now, longer show steady-state demand. This goes beyond the schema's basic description and aids the agent in choosing wisely.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a configurable time window. The verb 'returns' and the resource context ('what other AI agents are calling') are specific, and the tool is well-distinguished from siblings focused on querying (e.g., 'ask_pipeworx') or other analytics.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking use-case alignment. While no explicit 'when not to use' is stated, the context makes it clear that this tool is for trending insight rather than factual queries, which suffices given the sibling list.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: fill check against live CLOB depth, partition filter for placeholder slugs, semantic anchor for cross-event pairs, and when realizable edge is non-positive do not trade.

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 slightly verbose; it could be trimmed without losing critical information. However, it is well-structured with clear sections for each mode and additional notes.

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 comprehensively explains the response structure, including opportunities array fields, partition_check object, and fill check details. Covers edge cases and references related 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 coverage is 100%, but description adds significant meaning: examples of slugs, accepted URLs, modes triggered, and details like 'Full Polymarket URLs also accepted'. It clearly defines what each parameter does beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from siblings like polymarket_edges by specifying the exact methodology and modes (trending, event, topic).

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 on when to use each parameter: no args for trending scan, event for per-event partition check, topic for cross-event scan. Also explains when not to trade (fill check) and directs to 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?

The description provides extensive behavioral details beyond the annotations: caching (1h at KV level), response structure (by_segment segments), edge calculation methods, Kelly sizing, tradeable-edge knobs, and diagnostics. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with a read-only scan tool. No contradictions.

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

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

The description is well-structured with clear sections (model families, knobs, response), but it is quite long. It is front-loaded with the purpose, and every major concept is explained. Could be slightly more concise, but the detailed structure aids understanding for an AI agent.

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

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

Despite having no output schema, the description thoroughly explains the return format (by_segment, top-level fields, diagnostics) and all relevant concepts (edge calculation, Kelly, caching). Given the tool's complexity (9 parameters, three segments), the description is completely adequate for an AI agent to use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters with descriptions. The main description adds context for how the knobs relate to filtering (e.g., 'Tradeable-edge filter') but does not provide substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and resources ('top Polymarket markets', 'Pipeworx data'), and the purpose is well distinguished from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly includes the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context on when to use it. However, it does not explicitly state when not to use it or name alternatives, though the scope is clear given the 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 already indicate read-only and idempotent. The description adds beyond: explains snapshot-based data, 60-day TTL, limitation of daily closes (not intraday), and structure of response fields like first_seen, trend, decay_pp_per_day. No contradictions.

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

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

The description is somewhat long but efficiently structured: starts with core purpose, then detailed response format, then limits. Almost every sentence adds value, though minor redundancy could be trimmed.

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

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

Despite no output schema, the description fully explains return structure (tracked[], expired[], snapshot_dates[]) with field semantics. Parameters are thoroughly described. Covers all necessary details for correct usage.

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

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

Schema coverage is 100%, baseline 3. The description adds context: explains 'days' as lookback with default/max beyond schema constraints, and describes 'window' as snapshot family with examples. This provides useful additional 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?

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes from sibling tool 'polymarket_edges' by focusing on historical trends rather than current values.

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

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

The description implies when to use (analyzing edge history/decay) and contrasts fresh vs. aged edges. However, it lacks explicit instructions on when not to use or direct alternatives beyond the implied sibling tool.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds details: walking the ladder, returning fields (top_of_book, vwap_fill_price, etc.), and warns about forced directional risk. No contradiction with annotations.

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

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

Dense but front-loaded with purpose and requirements. Every sentence adds value, though it could be slightly more concise. Good structure with clear sections for single-market and basket modes.

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

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

No output schema, but description thoroughly explains return fields. Covers two modes, edge cases (thin legs, forced directional risk), and usage context. Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds context: explains single-market vs basket modes, defaults for side and size_usd, interpretation of size_usd for basket (settlement notional). Adds meaningful nuance beyond the schema.

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

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

The description clearly states the tool's function as a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why—theoretical overround on thin books is not capturable and partial fills convert arb to directional risk.

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

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

The description extensively discloses behavioral traits beyond the readOnly/annotations: matching algorithm ('matched by keyword and word overlap, not a shared resolution source'), fee treatment ('Kalshi charges per-contract trading fees... every spread_pp is gross'), null semantics for temporal_alignment, skipped-leg counters, and the meaning of each compatibility code. The annotation contradiction check is clean; readOnlyHint=true aligns with the read-only 'fetch/compare' behavior.

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

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

The description is long but front-loaded and well-structured, using capital labels like 'TWO MODES:', 'RESPONSE:', 'SAFETY FIELDS:' and bullet-like enumerations. A few points are reiterated (e.g., the keyword-overlap caveat appears twice), but the density of caveats is warranted for a cross-venue comparison tool with many edge cases.

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

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

With no output schema, the description must explain the return shape, and it does: leg-by-leg prices, top_spreads_pp, compatibility fields, temporal_alignment, fees_note, and skipped counters. It covers failure/safety semantics, mode-specific behavior, and the tool's practical reliability limitations, leaving little an agent needs to infer.

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 each parameter already having a description (topic list, override semantics). The description adds context that topic 'auto-fetch[es] the matching event' and that both modes run the same matcher, but it does not add significant new per-parameter meaning beyond the schema. Thus 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 first sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from siblings like polymarket_arbitrage (same-venue) and compare_entities by naming the exact two venues and the cross-venue comparison purpose.

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

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

The description gives clear guidance on when to use each mode: 'TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings.' It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning today, setting expectations. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' 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 two sentences, efficient, and front-loaded with the main action. Every sentence provides essential 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 no output schema, the description explains the expected return (value or list of keys). It also covers scoping and pairing with sibling tools, making it fully informative.

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 has 100% coverage with description for the 'key' parameter. The description repeats the schema's info about omitting the key to list all keys, adding minimal additional value.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from sibling tools like remember and forget by specifying the retrieval and listing functions.

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

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

The description provides clear guidance on when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget, but doesn't explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the returned fields (source, citation_uri, raw payload) and the effect of mark_read flagging events as read. However, it does not fully contradict annotations, but the mark_read behavior might imply a state change, creating a slight inconsistency.

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

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

The description is concise at four sentences, each adding essential information. It front-loads the purpose and immediately describes return fields. There is no redundancy or unnecessary detail.

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

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

With no output schema, the description adequately explains the return structure (source, citation_uri, payload). It covers key parameters and usage scenarios. However, it could mention default values or error handling, but overall it is complete for a filtered-list 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 all 5 parameters with descriptions (100% coverage). The description adds value by providing an example for 'type' ('sec_8k') and clarifying that 'since' expects an ISO timestamp. It also explains the behavior of 'mark_read' beyond the schema. This is above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull recent alerts). The description distinguishes it from siblings like 'list_subscriptions' or 'recent_changes' by focusing on fired events from the feed.

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

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

The description implies usage for retrieving recent subscription alerts and mentions polling is acceptable, but it does not explicitly state when to use this tool versus alternatives like 'list_subscriptions' or 'recent_changes'. There is no direct comparison or when-not-to-use guidance.

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

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

The description details the tool's behavior beyond the annotations: it fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains the fallback strategy, accepts ISO dates or relative shorthand, and returns structured changes with citation URIs. The annotations already indicate read-only and idempotent, and the description adds context on source selection and error handling.

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

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

The description is a single paragraph but front-loaded with example queries and ends with a clear alternative. It efficiently conveys all necessary information without extraneous text. A more structured format (e.g., bullet points) could improve readability, but it is not overly long.

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

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

Given there is no output schema, the description adequately explains the return structure: changes grouped by source, total_changes count, and pipeworx:// citation URIs. It also notes the patents soft-failure. The tool covers three complex sources and the description addresses all aspects.

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

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

The input schema has 100% description coverage, but the tool description adds significant meaning: it explains that 'type' only supports 'company', gives examples for 'since' (ISO date and relative shorthand like '7d', '30d', '1y'), and explains that 'value' can be a ticker or zero-padded CIK. This goes 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 opens with example queries ('What's new with X', 'latest on Y') that directly convey the tool's purpose. It clearly states it returns a change feed for a company covering SEC filings, news, and patents, and distinguishes itself from the sibling tool 'entity_profile' which provides static profiles.

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

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

The description explicitly tells when to use this tool (for recent changes) and when not to ('Use entity_profile instead when you want the static profile'). It also explains the fallback behavior between GDELT and GNews, and specifies that patents may soft-fail. This provides clear usage 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 indicate idempotentHint=true and non-destructive. Description adds key behavioral traits: key-value storage scoped by identifier, persistent memory for authenticated users, 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?

Description is well-structured and front-loaded with purpose, but slightly verbose. Could be tightened without losing meaning. Still mostly 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 simplicity of the tool (2 required params, no output schema), the description fully covers purpose, usage, storage details, and persistence. 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 has 100% coverage with descriptions for both key and value. The description adds example values but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples like tickers, addresses, preferences. It also distinguishes from sibling tools 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 states when to use: when discovering something worth carrying forward. Provides context on scoping and persistence, and mentions pairing with recall and forget for retrieval 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 establish read-only/idempotent safety, and the description adds substantial behavioral detail on top: multi-endpoint cascading, graceful degradation if GLEIF or OpenFIGI is unavailable, ambiguity behavior returning figi_candidates instead of asserting, and explicit unresolved identifiers. This far exceeds the annotation baseline.

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

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

The description is long but dense and front-loaded: the trigger examples and 'Use FIRST' instruction come immediately, and later detail is organized by entity type and failure/ambiguity behavior. Every section addresses a real calling decision, so the length is appropriate for the tool's complexity.

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

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

With no output schema, the description compensates by enumerating the identifiers returned per type, stating that unresolved identifiers are listed explicitly rather than omitted, and describing the candidate list on ambiguous matches. It also covers degradation and cross-source coverage, so an agent has everything needed to call correctly and interpret results.

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

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

Although schema coverage is 100%, the description materially expands parameter meaning: company accepts ticker, CIK, ISIN, or name; ISIN resolves via GLEIF to the legal entity; and the value field warns against appended security-class words for bonds. It also clarifies ambiguity and unresolved presentation in the returned identifiers, beyond the schema's terse examples.

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

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

The description opens with recognizable user queries and then states a specific transformation: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It enumerates supported entity types and the identifier sets for each, and frames itself as the first tool to invoke when a name needs to become an ID, which separates it from sibling lookup/profile 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 explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger. It also gives detailed formatting rules (e.g., pass the entity name only for bonds, never the full noun phrase) and explains that it replaces 2-3 manual lookups. It does not name specific sibling tools to avoid or state when not to use it, so exclusion guidance is absent.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds behavioral details beyond annotations, such as that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides valuable context without contradicting annotations.

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

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

The description is concise with two short paragraphs. The first sentence provides a clear summary. Every sentence adds value, and there is no redundancy or fluff. The structure is logical: overview, process, use case, and output.

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 (4 parameters, batch operation), the description comprehensively covers input, process, and output. There is no output schema, so the description adequately describes the return format (ranked list with score, confidence, signal density per entity). All essential behavioral aspects are covered.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds meaning by explaining that 'entities' first entry is the subject, and 'context' disambiguates common names. It also clarifies the 'models' parameter's default and the dependency on _apiKey. This adds value beyond the schema.

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

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

The description uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces' to clearly state the tool's function. It distinguishes itself from sibling tools like ai_visibility_check and compare_entities by explicitly describing the multi-entity comparison and ranking aspect. The example use case 'competitive AI-marketing audits' further clarifies its purpose.

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

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

The description provides clear usage context: 'useful for competitive AI-marketing audits' and an example question. It implicitly excludes single-entity checks (which would use ai_visibility_check) but does not explicitly state when not to use or list prerequisites like needing an API key for certain models. The note about the first entity being the 'subject' is helpful.

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

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

Description adds value beyond annotations by disclosing partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts), graceful degradation, and that it's a composite fan-out call.

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

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

Front-loaded with core purpose and usage, every sentence provides essential information, no redundancy. Under 100 words but highly informative.

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

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

No output schema, but description fully explains return structure (summary block, advisories, links, alternative versions) and failure modes. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that scoped packages are accepted and version defaults to latest, enhancing understanding. Slight extra value justifies 4.

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

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

The description clearly states it's a composite check for npm package evaluation, listing specific data sources (deps.dev, bundlephobia) and exact return fields. It distinguishes itself from sibling tools by its specific purpose.

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

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

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and provides exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already indicate safe, idempotent, open-world behavior. Description adds valuable detail: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (truncation flagged).' Also mentions offsets for verification. 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 sentences, front-loaded with core purpose. Each sentence adds distinct value: usage scenario, pairing, technical details. No redundancy or fluff.

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

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

No output schema, but description explains return: 'top-N passages with character offsets and similarity scores.' Covers chunking, metric, and input limits. Sufficient for a simple 3-parameter search 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 detailed descriptions. Description adds extra constraints: text max length (200K chars), limit range (1-20, default 5), and query examples. This provides more context than schema alone.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the resource (fetched text) and action (search with query). It differentiates from siblings by noting it's for records too large for the prompt and pairs with ask_pipeworx_grounded.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt.' Describes the workflow with ask_pipeworx_grounded. Does not explicitly mention when not to use or list alternatives, but provides clear 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?

The description adds behavioral context: requires OAuth, phone verification for SMS, 10/day cap, webhook auto-disable. However, it implies a new subscription ID each call, which may contradict the idempotentHint=true annotation. No mention of idempotency or mutation semantics beyond what's implied.

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 types and delivery. It is front-loaded with the purpose. While it is detailed, it remains focused and does not waste words. Could be slightly shorter 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 tool's complexity (3 params, nested objects, 5 enum values, delivery options), the description covers all necessary aspects: return value, prerequisites, limitations, and edge cases (auto-disable, phone cap). It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: provides examples and constraints for each type, details on delivery behaviors (email templated, SMS verified, webhook HMAC-signed with auto-disable). This goes 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 verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and mentions the return value (new subscription id). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context: requires a Pipeworx OAuth account; explains supported types and delivery channels. It does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about returning example questions and optional topic filtering, which is useful but not contradictory.

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 natural language queries, efficiently lists categories, and uses parentheses for examples. No redundant sentences.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, when to use, and parameter behavior. No gaps.

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

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

Schema coverage is 100% with description of topic parameter. Description adds context on how to use it (omit for full spread, pass topic to focus), exceeding schema alone.

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

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

The description states it's the onboarding entry point, returns category-bucketed example questions, and explicitly distinguishes from siblings by being the first tool to use when unsure.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists alternatives like ask_pipeworx, entity_profile, etc.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical data. Fully transparent.

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 with no unnecessary words. Front-loaded with the action 'Cancel a subscription by id'.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, behavior, ownership, side effects, and relation to other tools. Fully complete.

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

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

Schema coverage is 100% with single parameter 'id' described in schema. Description adds that the id is the subscription id returned by subscribe, linking to another tool – provides meaningful context beyond schema.

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

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

Description clearly states 'Cancel a subscription by id' – specific verb and resource. 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?

Explains ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated, not deleted, so historical events remain available via recent_alerts. Provides clear context on when to use and what happens, though does not explicitly name alternative tools.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses crucial behavioral details: the two pipeline paths, exact percent-delta math for financials, and the semantic distinction between 'could_not_verify' (an error, not evidence) and 'unsupported' (no source found). This prevents misinterpretation of results and is essential context.

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

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

The description is long but every sentence earns its place, covering usage, pipelines, return values, and caller warnings. It is front-loaded with intuitive examples and includes a clearly marked 'IMPORTANT' warning section. The length is justified by the tool's complexity, though a slight trim could aid scanning.

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

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

Since there is no output schema, the description carries the burden of explaining return values. It lists all verdict types, mentions the value with citation and reasoning, and clarifies the meaning of error-related verdicts. It also covers the two execution paths and the consolidation of multiple calls, making it sufficiently complete 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?

The main description does not add parameter-level detail; both parameters are thoroughly described in the input schema (100% coverage). Since the description itself doesn't elaborate beyond the schema, it meets the baseline of 3 without adding extra semantics.

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

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

The description clearly identifies the tool as a natural-language claim verifier that returns a verdict, citing several example phrasings ('fact check', 'verify the claim that…'). It distinguishes itself from sibling tools by focusing on fact-checking with verdicts, making it stand out from generic question-answering or research 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 explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (via SEC EDGAR fast path) and all other factual claims (grounded pipeline), giving concrete routing guidance. Mentioning that it replaces 4–6 sequential calls clarifies its efficiency advantage.

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