Conceptnet

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

Annotations declared readOnlyHint, openWorldHint, idempotentHint, destructiveHint – so safety is clear. The description adds behavioral context: default model is free, Anthropic requires BYO key, return structure includes per-model {score, confidence, signals, raw_response} + combined view. 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?

Three sentences: core function + scoring, model/cost detail, and return/usages. Front-loaded with key info, no redundancy, efficient.

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

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

Despite no output schema, the description details return structure (score, confidence, signals, raw_response + combined view). Parameters are fully described in schema (100% coverage). The description is sufficient for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% – each parameter already has a clear description. The description adds minimal extra meaning (e.g., scoring range 0-100, purpose of context). Baseline 3 is appropriate as schema covers parameters 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 the tool probes LLMs for brand visibility and scores 0-100 per model. It distinguishes from sibling tools like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (similar but sibling name suggests broader scan), making its specific purpose evident.

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 identifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It mentions default vs BYO key for Anthropic, but does not explicitly contrast with sibling alternatives or say when not to use it, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/non-destructive, and the description adds meaningful behavioral context: it fills arguments, works on every tier in one fast call, and returns stable pipeworx:// citation URIs. It also discloses routing behavior across many sources. No contradiction with annotations; only minor edge-case and failure behavior is left unspecified.

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 section earns its place: the 'PREFER OVER WEB SEARCH' directive is front-loaded, followed by domain coverage, trigger phrases, examples, and escalation rules. It is dense and scannable rather than padded, though a tighter version could trim some redundancy around the news/breaking-news note.

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 routing tool with no output schema, this description provides all needed context: invocation triggers, scope, examples, sibling alternatives, behavior, and return format. The explicit statement that it returns 'the structured answer with stable pipeworx:// citation URIs' compensates for the missing output schema. An agent can confidently decide when to call this tool and predict what it will return.

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 fully covers all six parameters, with question as primary and five documented aliases, so the baseline is 3. The description adds value by giving natural-language query guidance through trigger phrases and concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'. This helps an agent formulate the single required parameter effectively.

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

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

States a specific verb and resource: the tool routes natural-language questions to one of 5,706 tools across 1,493 verified sources and returns structured answers with citations. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point. This is far from a tautology and tells an agent exactly what the tool does.

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

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

Explicitly instructs agents to prefer it over web search for factual/authoritative questions and lists trigger phrases such as 'what is', 'look up', 'find', and 'get the latest'. It also provides concrete alternative routing: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions, and notes that breaking news is already handled. This is strong, decision-ready usage guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: candidate routing improvements may be live, no candidate is currently active, results are compared against the stable router, and it has no fallback because it is a full working router. This goes beyond what the annotations alone 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 a bit longer than strictly necessary but every sentence adds useful context about beta status, current parity, usage intent, and the experimental nature. It is front-loaded with the core identity and ends with reassurance that it is a fully functional router.

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 read-only, idempotent tool with a single required parameter and complete schema coverage, the description provides enough operational context. It clarifies current behavior, parity with ask_pipeworx, and the experimental edge. It does not explicitly spell out the return value, but it does state that the response shape is identical to ask_pipeworx.

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% coverage, documenting all six parameters as aliases for 'question.' The description only references 'same arguments' and adds no additional parameter-level detail, so the baseline 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 the tool as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by noting candidate routing improvements and that it currently matches the stable version exactly. It still leans on the reader knowing what ask_pipeworx does, but it is sufficiently specific and differentiated.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, which is a clear usage context. It does not explicitly state when not to use it or mention alternatives like ask_pipeworx_grounded, but it makes the experimental edge and comparison-to-stable behavior 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?

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing how the tool behaves on failure, the exact refusal_reason values, the success/refusal response shapes, and the cost tradeoff of an extra LLM call. This gives agents an accurate model of outcomes without overstating guarantees.

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

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

The description is dense but every clause earns its place: core capability, routing mechanism, success/refusal output contract, use cases, and cost tradeoff are all covered without fluff. The most important behavioral distinction is front-loaded.

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

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

With no output schema present, the description fully documents return values for success and refusal, enumerates refusal reasons, and explains when and why to prefer the sibling. This is complete enough for an agent to invoke the tool safely and interpret its result.

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 describes all parameters at 100% coverage, and the description adds no additional parameter-level nuance. The default baseline of 3 applies because the schema carries the parameter documentation burden and does so 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 identifies a specific behavior: a hallucination-resistant answer mode that routes through the same tool-selection logic as ask_pipeworx, fetches data, and extracts answers only from the tool result. It differentiates itself from the sibling ask_pipeworx by emphasizing evidence grounding and explicit refusals, so an agent can understand its unique role.

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

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

Usage guidance is explicit: use this tool when answers will be quoted, cited, or acted on and facts must not be invented, with concrete examples. It also names ask_pipeworx as the preferred alternative for casual lookups and cites the extra LLM call cost, giving a clear selection rule.

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?

Disclosures go far beyond annotations: resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits, closed market handling, wide spread illiquidity, and resolution-rule risk. No contradiction with annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false).

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

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

The description is lengthy but every section adds unique information: core purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety, and resolution rules. It is well-structured with clear headings, justifying its length for a complex tool.

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

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

Covers all aspects: input format, output shape (with key fields), edge cases (closed markets, low confidence, wide spreads, resolution rules), and behavioral details. No output schema exists, but response shapes are described in sufficient detail.

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

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

With 100% schema coverage, the description adds meaning: explains how 'market' interprets slug/URL/question text, how 'depth' controls quick vs thorough fan-out, and how 'include_raw' affects response size. This is valuable context beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, accepts multiple input formats (slug, URL, question text), and returns an evidence packet with comparison. It distinguishes itself from sibling research tools by focusing on Polymarket bets and mentioning Pipeworx.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailed examples of fan-outs. Does not explicitly list when not to use or alternatives, but the guidance is strong and contextually rich.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, repeatable behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS, FDA, ClinicalTrials), specific financial metrics, handling of off-calendar fiscal years, sorting by primary metric, and citation URI format. No contradictions with annotations.

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

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

The description is a single paragraph that packs extensive information. It is front-loaded with example queries and includes necessary details. While dense, it is still relatively concise for the complexity, though minor restructuring could improve readability.

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

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

Given the tool's complexity (two entity types, diverse data sources, sorting, citations) and the lack of an output schema, the description is remarkably complete. It covers return format (paired data + citation URIs), sorting behavior, and edge cases (off-calendar fiscal years), leaving no major gaps.

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

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

Schema coverage is 100%, but the description adds richness beyond the schema: for 'type', it explains data sources and metrics; for 'values', it gives concrete examples (tickers/CIKs, drug names) and constraints. This significantly aids parameter understanding.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs. It provides example queries like 'Compare X and Y' and explicitly distinguishes from sequential lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong usage guidance. It also details when to use each type (company vs drug) and what data to expect, though it doesn't mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context beyond those: parallel decomposition across 5,706 tools, the findings packet structure with evidence/confidence/source/fetched_at/citation, explicit gaps[] and contradictions[], 'never invented' behavior, semantic excerpting, latency expectations, and the conditionality of citation_uri. There is no contradiction with annotations.

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

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

The description is long, but every sentence carries essential operational information—auth, alternatives, output format, gaps behavior, latency, citation semantics, and depth options. It is front-loaded with the most critical constraint (ACCOUNT REQUIRED). The trade-off is density: a wall of text without visual structure, though this is justified by 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?

For a complex tool with no output schema and only two parameters, the description is exceptionally complete. It covers the return format in detail, error/edge behavior (empty gaps[] for uncataloged topics), citation resolvability, latency, authentication, and sibling-tool routing. An agent has all the context needed to invoke this tool correctly and interpret its results.

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

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

Schema description coverage is 100% for both parameters, giving a baseline of 3. The description adds meaningful value beyond the schema by explaining the paid-plan requirement for depth:'thorough', concrete latency expectations per depth (15-60s, up to ~90s), and clarifying the hop/iteration behavior for standard vs thorough. This enhances an agent's ability to choose a depth value correctly.

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 ('research') and a precise resource ('Pipeworx's 1493 STRUCTURED data sources'), explicitly distinguishing itself from open-web search and naming the sibling alternative ask_pipeworx. It clearly identifies the tool's scope: 'broad/multi-part questions over structured data.' This is far beyond a vague or tautological 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 explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also provides a prerequisite and fallback: 'If you are not signed in, use ask_pipeworx instead.' This is exemplary routing behavior that leaves no ambiguity for an agent.

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=true, idempotentHint=true, destructiveHint=false, which are consistent with a discovery tool. The description adds that results are 'ready to call directly, no second schema lookup needed,' providing useful behavioral detail beyond annotations.

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

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

The description is a single dense paragraph but front-loaded with the core purpose. The list of domains could be trimmed, but it effectively communicates scope. Overall, it is well-structured and informative without excessive 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?

Given no output schema, the description compensates by detailing the return value (names, descriptions, schemas with examples). It covers the main usage scenario and provides examples. Minor gaps (e.g., no error handling details) but sufficient for a discovery tool.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining that the query parameter accepts aliases (task, q, search, description) and provides examples (e.g., 'analyze housing market trends'). This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains the output: top-N relevant tools with names, descriptions, and schemas. This clearly distinguishes discover_tools from siblings like 'query' or 'lookup' which are for direct data retrieval.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies use cases (browse, search, look up) and domains. While it doesn't explicitly say when not to use it, the 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?

Discloses specific behaviors: returns data from multiple sources, mentions USPTO API sunset with soft-fail, and states it fans out in one parallel call. Annotations already indicate safe read-only behavior, and the description aligns 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 information-dense but well-structured with example queries and a clear breakdown of returned data. Slightly long but every sentence adds value; could benefit from bullet points for readability.

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

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

Despite no output schema, the description comprehensively explains all returned data fields, their sources, and limitations (e.g., patents sunset). Covers enough context for correct tool invocation without needing additional documentation.

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

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

Adds meaning beyond schema by clarifying that 'value' accepts ticker or zero-padded CIK and explicitly states names are not supported, directing to resolve_entity. Schema coverage is 100%, so the extra guidance is valuable.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with example queries and specific data sources. It distinguishes from siblings like resolve_entity by noting that names are not supported.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack lookups for a holistic view' and directs users to resolve_entity if they have only a name. Provides clear context for 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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is beyond annotations. However, it doesn't specify behavior when key is missing, but the idempotent hint implies safe repeated deletion.

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 with the action stated first. It includes purpose, use cases, and pairing, all in concise language with no wasted words.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description covers purpose, usage, and context within the sibling tools. It lacks return value specification but the destructive annotation and idempotent hint provide sufficient guidance.

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% coverage with a description of the 'key' parameter as 'Memory key to delete'. The description simply repeats 'by key' without adding new meaning or examples, so 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 explicitly states 'Delete a previously stored memory by key', which is a specific verb+resource. It also distinguishes from siblings 'remember' and 'recall' by its action.

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 specific scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, guiding when to use this tool in the context of the memory system.

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 (read-only, idempotent, non-destructive), the description explains the internal steps: fetches the page, extracts title/description/key links, and emits standard markdown format. This adds significant behavioral context that annotations alone do not 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?

Two concise sentences with a bulleted usage list. Every sentence earns its place, front-loaded with the primary action. No wasted words.

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

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

Given no output schema, the description explains the output format (single text blob, standard markdown). Parameter count is low. Missing error handling or edge cases (invalid URLs), but overall adequate for a straightforward 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 two parameters well-described in the schema. The description mentions 'fetches the page' (implied url) and 'maximum number of link entries' (max_links), but does not add extra semantics beyond the schema. Baseline 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 states the tool generates a production-ready llms.txt file for a URL, specifying the exact resource and action. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence, which address related but distinct use cases.

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

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

The description provides explicit use cases (client site indexing, personal project, competitor audit) but does not mention when not to use this tool or suggest alternatives. It offers clear context but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read. The description adds that it returns specific fields (id, type, etc.), which is useful but not critical. 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: first states purpose and return fields, second gives usage context. Every sentence adds value, with no wasted words.

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

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

Given no output schema, the description lists the return fields (id, type, etc.), which is helpful. It does not explain field meanings or pagination, but for a simple list of subscriptions, this is adequate.

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 fully documents the single parameter 'include_inactive'. The description does not add extra meaning beyond what the schema provides, earning 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 verb 'list' and resource 'subscriptions', specifying 'the caller's active subscriptions'. It differentiates from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. This tells when to use it and implicitly suggests alternatives (subscribe, unsubscribe).

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

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

Annotations clearly indicate the tool is read-only, idempotent, and non-destructive. The description adds minimal behavioral context (e.g., 'edges'), but nothing 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?

The description is extremely short (one phrase), which is concise but lacks structure and clarity. It could benefit from a clearer sentence without being overly verbose.

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 six parameters and the knowledge-graph domain, the description is too sparse. It doesn't explain offset/limit pagination, relation types, or the return format, even though an output schema exists.

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 each parameter is documented. The description adds no additional semantic 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 states 'All edges touching a term in a language', which gives a general idea of retrieving relationships but is vague about what 'edges' are and doesn't differentiate from similar sibling tools like '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?

There is no guidance on when to use this tool versus alternatives. No context for usage or exclusions are provided.

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

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

Annotations are all false, so the description carries the full burden of behavioral disclosure. It covers rate limiting (5 per identifier per day), free/quota-exempt status, the claim_token return behavior when no account is provided, the daily digest review by the team, and the roadmap impact. No annotation 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 dense but every sentence earns its place. It is front-loaded with the core purpose, then flows through usage conditions, exclusions, token workflow, rate limits, and quota impact. No filler or redundancy.

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

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

For a tool with no output schema, the description fully covers the user-facing workflow: what to report, how to scope it to Pipeworx, what happens when filing anonymously, how to claim the token, and operational constraints (rate limit, quota, team review cadence). It is 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 the baseline is 3. The description adds meaningful usage semantics beyond the schema: it explains the claim_token round-trip (file returns token → pass back later to read status), reinforces the type enum with concrete examples, and advises message crafting (be specific, 1-2 sentences, don't paste user prompt). This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact scenarios (bug, feature/data_gap, praise) and clearly distinguishes this tool from the research/query siblings by positioning it as the feedback channel for Pipeworx 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 ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It also provides formatting guidance (describe in terms of Pipeworx tools/packs, don't paste user prompt) and the claim_token workflow.

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

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

Adds context beyond annotations: data source (CF analytics-engine), privacy (no PII), returned fields (pack, tool, count), and caching (5min-1h). 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?

Concise, front-loaded purpose, use cases in bullet-like format, and additional details in the last sentence. No unnecessary words.

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

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

Given low complexity (1 param, no output schema, rich annotations), the description covers all needed info: what is returned, how it works, caching, and usage context.

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

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

Single parameter `window` with enum is well-described, including behavior implications (hot vs steady-state). Schema coverage 100% supports baseline 3, but description adds 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?

Clearly states the tool returns trending tools/packs and call volume over configurable windows, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and guidance on window selection for different needs.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safe, read-only, open-world behavior. The description adds critical behavioral details: the 'FILL CHECK' explains that realizable_edge_pp ≤ 0 means the arbitrage is not tradeable, and it references polymarket_fill_risk for custom sizing. No contradiction with annotations.

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

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

The description is comprehensive but slightly verbose. It is well-structured with clear sections (modes, semantic anchor, partition filter, response details, fill check). Every sentence adds value, though some details could be trimmed without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check object, fill check details). It also addresses edge cases (low similarity, placeholder filter) and references a sibling tool for custom sizing, making it complete for agent use.

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

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

Input schema has 100% coverage with descriptions for both parameters (event, topic). The description enriches these by explaining that event takes a slug (with examples) and topic takes a seed question, and it details how these modes affect the analysis (walking child markets, cross-event scanning, similarity checks).

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges by focusing on arbitrage detection through specific mathematical checks, and it details three distinct usage modes (no args, event, topic) with specific behaviors.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets and explains when cross-event mode is beneficial. No explicit when-not-to-use, but the clarity of modes makes it highly usable.

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 explains the three model families, caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge and Kelly calculation, and tradeable-edge knobs. It adds significant behavioral context beyond the annotations, which already indicate readOnlyHint, idempotentHint, etc. No contradiction.

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

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

The description is long but well-structured, front-loaded with the core purpose, and each section (segments, response fields, knobs, diagnostics) adds necessary detail. While it could be more concise, the complexity of the tool justifies the length.

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

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

Given the tool's complexity (9 parameters, no output schema, nested structures), the description is highly complete. It explains the output structure, why segments may be empty, Fed bet handling, and how parameters affect results. This provides excellent context for the 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 schema already provides 100% coverage with detailed parameter descriptions. The tool description adds some context (e.g., summarizing knobs and explaining min_partition_leg_kelly), but it doesn't significantly enhance understanding beyond what the schema already offers. Baseline 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 states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. It distinguishes itself from siblings by focusing on three specific model families and the Pipeworx data disagreement.

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

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

The description provides guidance on when to use the tool (for discovering opportunities without paging hundreds of markets) and mentions the tradeable-edge knobs. However, it does not explicitly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving the agent to infer distinctions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: it returns full edge_pp_net time-series, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot_dates. It also discloses limits (60-day TTL, no intraday data) and data source (daily closes).

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

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

The description is relatively long but every sentence adds value. It front-loads the core question and then organizes response fields (tracked[], expired[], snapshot_dates[]) clearly. Could be slightly more structured with bullet points, but overall effective.

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

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

Given no output schema, the description fully explains the response structure including all fields and edge cases (gaps due to cache-miss, TTL bounding, start time). It covers the tool's complexity with 2 parameters and no nested objects completely.

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

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

Schema coverage is 100%, so both 'days' and 'window' are documented. The description adds meaning beyond schema: 'days' is lookback (default 14, max 30, with clamp 2-30), 'window' default is '1wk'. It also explains that history depth is bounded by 60-day TTL, adding subtle parameter constraint context.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry' and answers a concrete question: 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on time-series trend analysis rather than raw snapshot data.

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 on when to use the tool ('Answers...'), including a concrete example differentiating fresh vs old wide edges. It explains interpreting results (trend, decay, lifespan) but does not explicitly name alternative tools for different use cases.

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 substantial behavioral context beyond annotations: walking the order-book ladder, returning detailed metrics like slippage, fill details, and risks like partial basket fills converting arb into directional positions. 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 dense and well-structured with bold mode headers, but slightly verbose at several sentences. However, every sentence earns its place, and the information is front-loaded with the core purpose.

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

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

Despite no output schema, the description comprehensively enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, capture_ratio, profit_usd, per-leg details, thin_legs, forced_directional_risk) and explains their meaning. No gaps for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant value: e.g., for size_usd it distinguishes buys vs sells and basket mode interpretation; for side it explains default auto behavior. This enhances the schema definitions.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' with explicit modes (single-market and basket) and specific differentiation from sibling tools like polymarket_arbitrage and polymarket_edges by being a prerequisite validation step.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills causing unhedged positions) and implies when not to use (small trades).

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive; the description goes far beyond this by explaining compatibility codes, unclassified leg handling, skipped comparisons, temporal alignment fields, and per-entry flags. It also discloses that unknown metric types are never paired and that returned pairs may still carry warnings. This is exemplary transparency.

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

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

The description is long, but the tool is genuinely complex with two modes, safety fields, and detailed response semantics. The purpose and modes are front-loaded, and the later sections cover response structure and caveats. Some repetition and density remain, but overall each 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?

Even without an output schema, the description documents the response shape: leg-by-leg prices, matched spreads in top_spreads_pp, compatibility_warning and compatibility_codes, temporal_alignment, skipped_cross_type/subtype counters, and low_confidence_pairs. It also covers failure modes and warnings. Nothing essential for calling this tool correctly seems missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how the parameters relate to the two modes, that topic auto-fetches the matching event on each venue, and that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This clarifies the interplay between parameters beyond their individual 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 states a specific verb and resource: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly defines the tool's core function and two modes. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, which may overlap conceptually.

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 scenarios for using topic mode versus explicit ticker/slug mode, and warns that most pre-mapped topics currently return compatibility warnings and are not necessarily tradeable. It lacks explicit guidance on when to prefer this tool over sibling comparison tools, but the operational guidance within the tool is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description confirms it's an edge search but adds minimal behavioral context about combining parameters or response structure. Since annotations are rich, the description is adequate but not enhanced.

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

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

The description is a single sentence that is concise and front-loaded with the core purpose. Every part contributes meaning without redundancy.

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

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

Given the rich annotations and presence of an output schema, the description is adequate but lacks explanation of parameter combination behavior and default scoping (e.g., how offset/limit apply). An agent may benefit from more context on usage patterns.

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 71%, and the description lists parameters (rel, start, end, node, source) but does not explain how they combine (e.g., AND/OR logic) or provide additional semantics beyond the schema. Examples in the input schema partially compensate, but the description itself adds limited 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 'Generic /query edge search (combine rel, start, end, node, source)' clearly indicates the tool performs edge searches in a graph, specifying the main parameters. However, it does not explicitly differentiate itself from sibling tools like 'lookup' or 'deep_research', which may serve similar purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. With siblings such as 'lookup', 'search_within', and 'entity_profile', explicit context on when this low-level 'query' is appropriate would aid selection.

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

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

Adds scoping detail (by identifier) 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?

Four sentences, no fluff, well-organized with clear functionality, usage, scoping, and pairing.

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 essential aspects for a simple retrieval tool; lacks return format details but not critical given examples.

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

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

Schema coverage is 100% and description echoes schema info; minimal added value beyond 'omit to list'.

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 retrieves a value saved via remember or lists all keys, and differentiates from siblings remember and forget.

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

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

Explicitly says when to use (look up stored context) and when not (save/delete via remember/forget), with concrete examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: mark_read flag affects future calls by marking events read, polling works fine, and the feed is also available via GET. No contradiction with annotations.

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

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

The description is a single focused paragraph of 5 sentences, each adding value: purpose, return fields, filtering, mark_read behavior, alternative endpoint. It is front-loaded with the main purpose and avoids 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 exhaustive schema coverage and comprehensive annotations, the description fully covers return format, filtering, mark_read behavior, and provides an alternative access method. No output schema exists, but the return fields are described. The tool is well-understood for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances semantics by providing examples (type filter 'sec_8k', since as ISO timestamp), explaining mark_read behavior, and noting limit defaults. This adds meaningful guidance 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 pulls fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and distinguishes itself by mentioning an alternative endpoint for scripts/dashboards. The verb 'pull' and resource 'fired events' are specific and unambiguous.

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

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

The description provides context for when to use this tool (polling works fine) and mentions an alternative GET endpoint for scripts/dashboards, implying when not to use this tool. However, it does not explicitly exclude usage scenarios or compare with sibling tools, leaving some room for ambiguity.

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

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

The description richly details behavioral traits beyond the annotations: it fans out to multiple sources, has fallback mechanisms, accepts various date formats, and returns structured data with citation URIs. No contradictions with annotations (readOnly, idempotent). The soft-fail for patents is explicitly noted.

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 query examples and provides thorough context. While every sentence adds value, it is somewhat long. However, the structure is logical, moving from examples to behavior to alternatives.

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

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

Given the tool's complexity (multiple sources, date windows) and the lack of an output schema, the description sufficiently explains what the tool returns (changes grouped by source, total_changes, citations). It also mentions the alternative tool for static profiles, making it complete for selection and invocation.

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

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

Schema coverage is 100%, but the description adds significant value: it explains the 'since' parameter accepts ISO dates or relative shorthand and recommends '30d' or '1m'. It clarifies 'value' accepts ticker or CIK, and 'type' is only 'company'. This goes beyond the schema's descriptions.

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

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

The description begins with concrete example queries and explicitly states it is a change feed for a company. It distinguishes itself from the sibling 'entity_profile' tool, which is for static profiles. The verb 'fan out' and listing of sources (SEC EDGAR, GDELT, USPTO) makes the action and resource very clear.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' (static profile). It also explains internal fallback logic (GDELT preferred, GNews when rate-limited) and soft-fail behavior for USPTO. This gives clear context for expected behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the output range (0..1) and clarifies it's a semantic-relatedness score, which is not in annotations. No contradictions. However, it does not detail the model or knowledge base used.

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 wasted words. The key details (what it does, output range) are front-loaded. 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?

Output schema exists, so return value details are not needed. The description covers the core functionality. It could mention the underlying data source or default language handling, but the schema examples and parameter descriptions provide sufficient context. Missing use case guidance slightly lowers 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?

Input schema coverage is 100% with descriptions for each parameter. The description does not add new meaning beyond the schema (e.g., 'node1' and 'node2' are already described). 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?

Clear and specific: 'Semantic-relatedness score (0..1) between two terms.' The verb 'compute' is implied, and 'score (0..1)' defines the output. It distinguishes from sibling tools like compare_entities or entity_profile by focusing on a numeric relatedness score.

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

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

No guidance on when to use this tool vs alternatives. Lacks mention of use cases or when not to use. Sibling tools include other semantic/lookup tools, but the description does not differentiate.

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

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

Adds significant context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous), 24-hour retention for anonymous, and cross-session use. No contradiction with annotations.

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

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

Two compact sentences front-loaded with purpose and usage, followed by essential behavioral details. No extraneous words.

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

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

Fully covers purpose, usage, behavior, parameter hints, and tool relationships. Given two simple parameters, no output schema, and rich annotations, no gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds naming conventions (e.g., 'subject_property') and usage context, providing slight additional value beyond schema.

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

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

Clearly states 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference) and distinguishes from siblings 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 instructs when to use ('when you discover something worth carrying forward') and pairs with recall/forget, providing clear usage context and alternatives.

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

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

The description richly discloses behavior beyond the read-only/idempotent annotations: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, explicitly lists unresolved identifiers under `unresolved`, and labels every identifier with its source. This gives the agent a clear understanding of expected behavior and failure modes.

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

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

The description is lengthy but well-structured, starting with user intents, then the core purpose, followed by a SUPPORTED TYPES breakdown. Each paragraph adds useful detail (identifier formats, unresolved behavior, graceful degradation), and the density justifies the length, though it could be slightly trimmed without losing meaning.

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

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

With no output schema, the description fully specifies return expectations: for company it lists CIK, ticker, company_name, LEI with ownership, FIGI, and unresolved fields; for drug it lists RxCUI, ingredient, brand, and a citation. It also covers input variations and failure handling, making it complete for a complex resolution 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 already covers both parameters with descriptions (100% coverage), but the tool description adds valuable semantics: for company it expands accepted inputs to 'ticker, CIK, ISIN, or company name' and explains ISIN-to-LEI resolution; for drug it clarifies that value accepts brand or generic names. This goes beyond the baseline schema documentation.

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

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

The description opens with concrete user queries ("What's the ticker for...", "find the CIK for...") and immediately states the core action: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." This clearly distinguishes it from siblings like lookup or entity_profile by focusing on identifier resolution rather than general search or profile retrieval.

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

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

Provides an explicit when-to-use rule: "Use FIRST whenever you have a name but need an ID." It also explains that it replaces 2-3 manual lookups, implying it is a faster alternative for identifier resolution. However, it does not name specific alternative tools or provide explicit when-not-to-use conditions, so it falls short of a top score.

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

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

The description adds behavioral detail beyond annotations: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and specifies return fields (score, confidence, signal density). Annotations already indicate safety (readOnly, idempotent), so bar is lower; description enhances transparency.

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

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

The description is concise (~3 sentences), front-loaded with purpose, and uses clear language. No unnecessary words or repetition, though it could include a bit more structure for readability.

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

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

The description covers main functionality but lacks details on error handling, edge cases (e.g., entity not found), or interpretation of returned scores. Given no output schema, additional context on return format 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?

Schema coverage is 100%, so baseline is 3. The description adds value: 'First entry treated as subject for narrative' and 'Omit for just workers-ai' for models. This provides practical guidance beyond parameter descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use against alternatives (e.g., instead of ai_visibility_check for single entity) but does not explicitly mention 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, openWorldHint, idempotentHint, destructiveHint. The description adds beyond this: explains the composite nature (fans out across deps.dev and bundlephobia), mentions partial failures and timing (bundlephobia first measurement 5-30s), and sources_failed list. 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 but dense with information. It front-loads the composite nature. While it could be broken into bullet points, it remains clear and efficient.

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

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

No output schema exists, but the description explains the return structure (summary block, per-advisory detail, links, alternative versions) and covers edge cases like partial failures. It is fairly 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 descriptions for both parameters. The description adds additional context: explains the default version behavior and that scoped packages are accepted, 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 the tool's purpose as a composite check for npm packages covering license, advisories, and bundle size. It distinguishes itself from siblings by specifying the ecosystem (NPM) and mentioning alternative tools like deps.dev:version.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small"...' It also notes limitations: NPM only in v1, and mentions partial failures. This provides clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, non-destructive. Description adds significant behavioral details: truncation cap (200K chars), embedding model (BGE-base-en), window size (500-char overlapping), offset feature. 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?

Three concise sentences, front-loaded with purpose. Every sentence earns its place: function, use-case, technical details. Zero waste.

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

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

No output schema, but description fully covers return format (passages with offsets and similarity scores). Also covers limits, model, truncation, and pairing with sibling. Complete for a tool with 3 simple params.

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

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

Schema covers all 3 params with descriptions. Description adds meaning: explains query parameter with example queries ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies the truncation behavior for text parameter, and mentions output features (offsets, scores) not otherwise documented.

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 semantic search inside a fetched record, specifies inputs (text + query) and output (top-N passages with offsets and similarity scores). It distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with fetching full records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and highlights context-saving benefit. Also provides an alternative workflow with ask_pipeworx_grounded, giving clear when-to-use guidance.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: returns subscription id, OAuth requirement, supported event types with examples, delivery channel options with specific constraints (SMS phone verification, 10/day cap, webhook HMAC signing, auto-disable after 10 failures). Exceeds annotation coverage.

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

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

The description is well-structured: starts with action, then requirement, supported types, delivery channels. Every sentence adds value. Slightly lengthy but appropriate given the detail needed for complex subscription types. Could be slightly more concise, but no waste.

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

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

Given the tool's complexity (3 parameters with nested objects, no output schema), the description is complete. It explains return value (subscription id), all type-specific parameters, delivery options with restrictions, and prerequisites. No apparent gaps that would hinder an agent's correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: explains enum values with real-world examples (e.g., sec_8k items field), details type-specific params structure, and elaborates on delivery sub-fields including security (webhook HMAC) and rate limits (SMS cap). This provides clarity beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' This is a specific verb+resource combination. The tool is meaningfully distinguished from siblings like list_subscriptions, unsubscribe, and recent_alerts, which serve different 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 explicitly states a prerequisite (Pipeworx OAuth account required, anonymous/BYO cannot persist), which guides when to use. It mentions the always-on feed available via recent_alerts as an alternative for pulling alerts without subscribing. However, it could more explicitly contrast with other tools or state when not to use subscribe.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns example questions with exact tool and argument shapes, drawn from a live catalog, and differentiates behavior with/without the topic argument. 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 front-loaded with synonyms and purpose, then explains output and usage. It's a bit long but every sentence adds value. Could be slightly more concise but still well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description thoroughly explains what it returns (category-bucketed example questions with tool+argument shapes) and how to call it. No gaps for the intended use case.

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% (one parameter fully described). The description adds meaning by explaining the effect of omitting vs. providing 'topic' (full spread vs focused), and lists example values beyond the schema's enum list.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by indicating it should be used first when the agent doesn't know what Pipeworx can do.

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

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

Explicitly recommends using this tool first when unfamiliar with Pipeworx, and offers to focus on a topic by passing a parameter. It also implies when not to use it (if already know what to ask).

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

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

Discloses that the row is deactivated (not deleted) and that historical events remain available, which goes beyond the annotations (destructiveHint=false). No contradiction.

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

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

Two sentences, each adding value. First sentence states action and constraint, second explains behavioral effect. 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?

Complete for a simple mutation: covers purpose, usage constraint, and behavioral effect. No output schema needed.

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

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

Schema covers 100% of parameters with description for 'id'. Description adds no extra meaning beyond the schema, so baseline score 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?

Clearly states the action (cancel) and resource (subscription). Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Mentions ownership enforcement and that only own subscriptions can be canceled, providing clear context. However, no explicit comparison to 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 readOnly/openWorld/idempotent annotations, the description discloses critical non-obvious behavior: 'could_not_verify' means the check did not happen and includes a verification_error object, while 'unsupported' means no source covers the claim. This prevents misinterpretation and adds real 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 longer than ideal but every sentence contributes distinct information: example intents, usage scope, routing logic, return payload, error semantics, and performance benefit. It is front-loaded with the query patterns and logically organized, though a tighter edit could remove minor 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?

There is no output schema, so the description compensates well by specifying the verdict set, the grounded/structured value with pipeworx:// citation, and reasoning. It also explains the two failure-like verdicts and the tolerance behavior. This is comprehensive 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?

The input schema already fully documents both parameters (claim and tolerance_pct), so the baseline is 3. The description adds practical nuance—tolerance_pct overrides the wording-implied tolerance and recommends setting 1–2 for hallucination detection—offering guidance beyond the schema.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, provides example phrasings, and distinguishes itself from siblings by detailing the two processing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for others) and noting it replaces 4–6 sequential calls. This is a specific verb+resource with clear differentiation.

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

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

Explicitly says to use whenever the agent needs to check whether something a user said is factually correct, and divides claims into company-financial vs any other, giving clear scope. It does not explicitly name sibling tools as alternatives or state when-not-to-use, 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.