Eol

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

Annotations already indicate readOnlyHint, destructiveHint, etc. The description adds valuable behavioral context: default free model, BYO key for Anthropic with direct billing, and the structure of return data. 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?

Three well-structured sentences that front-load the action and cover purpose, usage, and behavior without wasted words. Every sentence earns its place.

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

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

Despite no output schema, the description details return fields (score, confidence, signals, raw_response, combined view), making the tool's behavior fully understandable. Annotations, sibling list, and schema are well complemented.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default model, requiring _apiKey only for anthropic models, and clarifying billing responsibility, which goes beyond the schema's 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 uses specific verbs ('Probe', 'score visibility') and clearly identifies the resource (LLMs for a given entity). It distinguishes the tool from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on AI visibility scoring for brand audits.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it doesn't list when not to use or name alternative siblings, the context is clear and actionable.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by explaining internal behavior: routes to 5,529 tools, fills arguments, returns structured answer with stable citation URIs, and notes 'one fast call'. It also clarifies breaking-news routing. No contradictions with annotations. The added context about output format and routing justifies a 4.

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-loading the key message ('PREFER OVER WEB SEARCH') and following with usage triggers, examples, and alternatives. Some redundancy exists (repeated mention of web search preference and breaking news), but it earns its length given the tool's complexity and many sibling tools. Score 4.

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 routing tool with no output schema, the description provides sufficient context: it enumerates supported domains (SEC, FDA, FRED, etc.), explains output format with citations, covers tier availability, and gives concrete examples. It also disambiguates from siblings. This is complete for an agent to select and invoke correctly.

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

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

The input schema already covers all 6 parameters with 100% coverage, describing question and its aliases. The description provides examples of valid questions but doesn't add parameter-level semantics beyond the schema. Baseline of 3 is appropriate since schema does the heavy lifting.

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 routes natural language questions to the appropriate sources/tools among thousands, returns structured answers with citations, and explicitly says 'PREFER OVER WEB SEARCH' for various factual queries. It distinguishes from sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

It provides explicit guidance on when to use: any factual question about real-world entities, with trigger phrases ('what is', 'look up', etc.), and says 'START HERE for most questions'. It also explains when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answer, deep_research for broad/multi-part questions. This is a model of clear 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?

Adds substantial context beyond annotations: experimental status, no active candidate currently, matches ask_pipeworx exactly at this time, results compared against stable router for merge decisions, and it's fully functional (not a stub). This gives the agent important behavioral expectations.

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

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

The description is four sentences and information-dense, but slightly verbose. Each sentence adds value, yet it could be tightened 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?

For a beta tool, the description covers the essential context: relationship to stable version, current state, usage, and response shape. No output schema exists, but the description points to ask_pipeworx for response shape. The behavior is sufficiently specified.

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

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

Schema coverage is 100%, with all parameters documented as aliases for question. The description adds no parameter-specific information, but the schema fully handles semantics, 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?

Description clearly states this is the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and the grounded variant by positioning as the experimental edge with candidate routing improvements.

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 it exactly like ask_pipeworx when wanting the newest routing, giving clear context for use. However, it doesn't explicitly state when not to use it or name alternatives like the stable ask_pipeworx for production use, though that is implied.

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

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

The description discloses key behavioral traits beyond the annotations: it returns explicit refusals with reasons, includes a verbatim evidence quote, and incurs an extra LLM call. This complements the readOnlyHint and idempotentHint annotations 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 long but every sentence carries essential information: purpose, mechanism, output format, refusal reasons, use cases, and cost trade-off. It is somewhat dense but front-loaded with the primary purpose, making it navigable for an agent.

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

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

Given there is no output schema, the description compensates by fully specifying the success response format ({answer, evidence, ...}) and all possible refusal reasons. It also covers practical scenarios (financial, legal, medical) and compares to the sibling, making it highly complete for tool 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?

The schema fully covers the parameters (100% coverage), including aliases and natural language examples. The description adds no extra parameter semantics, but since the schema is comprehensive, the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it provides a hallucination-resistant answer mode using grounded extraction from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it uses only the tool result as evidence and returns verbatim quotes, addressing high-stakes scenarios.

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

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

Explicit usage guidance is given: use when answers will be quoted, cited, or acted upon, and prefer the cheaper ask_pipeworx for casual lookups. It also mentions the extra LLM call cost, helping the agent decide between 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?

Description extensively details behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract, parent event extractor, news fields, safety checks (low-confidence short-circuit, closed markets, wide spreads), and resolution-rule risk. No contradiction with annotations (readOnly, openWorld, idempotent).

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) that aid readability. Every sentence adds value, but could be slightly trimmed for conciseness while retaining essential details.

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

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

Given complexity, no output schema, and rich behavior, the description is exceptionally complete. It covers input formats, depth options, include_raw behavior, classification, fan-out examples, response details, safety mechanisms, and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Agents have all needed information.

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

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

All 3 parameters have descriptions in schema (100% coverage), and the description adds meaningful context: market accepts slug/URL/text, depth defaults to thorough and explains quick as 2-3 sources, include_raw summarizes vs full payloads. This enriches the schema guidance.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb('Research') and resource('Polymarket bet'). It provides use cases ('should I bet on X', 'what does the data say about Y') and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Description gives explicit usage context (e.g., 'Use for should I bet on X') and important warnings about inspecting resolver contract before trusting analysis. However, it does not explicitly state when not to use this tool versus alternatives, though sibling tool names imply boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about sorting by primary metric, handling off-calendar fiscal years, and returning citation URIs, which go 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?

The description is one paragraph but front-loads example queries and states the tool's purpose immediately. It is packed with information without fluff, though it could be slightly more 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?

Despite having no output schema, the description clearly states what is returned (paired data + citation URIs per entity) and covers behavior for each entity type, sorting, and efficiency gains. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and descriptions are present, but the description enriches by explaining what data is fetched for each enum value (company vs drug) and providing examples for the values array. This adds significant meaning beyond the schema alone.

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

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

The description starts with explicit example queries like 'Compare X and Y' and 'which is bigger', clearly stating it performs side-by-side comparison of 2–5 entities in one call. It distinguishes from siblings like entity_profile by specifying it replaces sequential single-entity lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive on when to use this tool versus alternatives. It also implies not to use it for single entity lookups.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing account requirements, paid tiers, output structure (gaps[], contradictions[], hop field, citation_uri). It also explains behavior like semantic excerpting, latency expectations, and that it never invents answers. This is rich, accurate behavioral disclosure.

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

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

The description is long but well-structured and front-loaded with the critical account requirement, then core functionality, usage guidance, and output details. Every sentence contributes distinct information (auth, scope, output, latency, caveats), though some tightening could improve brevity. It is dense without unnecessary fluff.

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

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

Given no output schema, the description thoroughly explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, stable citation URIs, gaps[]). It covers failure modes, contradictions, latency, examples, alternatives, and depth semantics. This is as complete as needed for a complex research tool.

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

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

Schema coverage is 100% and both parameters are described in the schema, which sets a baseline of 3. The description adds further value by clarifying depth levels: quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hops and contradictions scanning, plus the paid-plan restriction. This enriches the schema's enum descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in one call, with decomposition into facets and parallel tool routing. It explicitly contrasts with ask_pipeworx for single lookups and current-news topics, providing examples and scope. The verb+resource+differentiation from siblings is 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?

Offers explicit when-to-use guidance: best for broad/multi-part structured-data questions, while ask_pipeworx is recommended for single lookups or breaking/current-news. Also states that unsigned-in users should use ask_pipeworx and that thorough depth requires a paid plan. Explicit alternatives and conditions 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly. 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?

Single paragraph with clear structure: purpose, examples, return behavior, guidance. Every sentence adds information without redundancy.

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

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

Despite having no output schema, the description fully explains what is returned (tool names, descriptions, schemas with examples) and how it can be used immediately. Parameter aliases and limits are covered. No missing context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that query aliases (task, q, etc.) are accepted and that limit defaults to 20 with max 50, reinforcing schema information and clarifying natural language usage.

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

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

Description states 'Find tools by describing the data or task.' and gives concrete examples like SEC filings, FDA drugs, etc., clearly establishing it as a tool discovery mechanism. It distinguishes from siblings by implying it's a meta-tool to be used first, unlike search tools that retrieve 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it vs. other tools, and the examples further guide usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' and notes that 'patents via USPTO PatentsView API sunset May 2025 — soft-fails until reactivated.' This transparently discloses a known limitation and the tool's behavior when that source is unavailable.

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 each sentence adds value. It begins with example queries, then states the primary use case, followed by a structured list of return data. The use of dashes and semicolons creates a compact but readable format. It could be slightly more structured (e.g., bullet points), but the front-loading with examples is effective.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description provides a comprehensive overview of what is returned: cik, company_name, recent_filings with URIs, fundamentals (specific fields), patents, news, and LEI. It also notes the patent soft-failure and the need for ticker/CIK format. This is sufficient for an agent to understand the output 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 coverage is 100%, so both parameters are documented in the schema. The description adds meaningful context beyond the schema: it specifies that 'type' is restricted to 'company' (with 'person/place coming soon'), and clarifies that 'value' accepts ticker or zero-padded CIK but not names. It reinforces the constraint that names require a different tool (resolve_entity), which is essential for correct invocation.

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

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

The description clearly states the tool's purpose: returns a full cross-source profile of a US public company. It provides numerous example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and explicitly distinguishes from siblings like resolve_entity (for name resolution) and compare_entities. The verb 'profile' and resource 'US public company' 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 explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides exclusion criteria: 'names not supported (use resolve_entity first if you only have a name).' This gives clear guidance on when to prefer this tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns with these. It adds the context of clearing sensitive data, which is beyond the annotations. No contradiction is present.

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

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

The description is concise with two sentences, clear and front-loaded. It could be slightly more structured, but every sentence serves a purpose with no fluff.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is fully complete. It covers purpose, usage guidance, and parameter meaning, with no gaps.

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

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

The schema has 100% coverage for the single 'key' parameter with description 'Memory key to delete'. The description adds no additional meaning beyond what the schema provides, so it meets 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 'Delete a previously stored memory by key', specifying a precise verb and resource. It explicitly pairs with sibling tools 'remember' and 'recall', distinguishing its function as the deletion counterpart.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', offering context for alternatives, though it lacks explicit when-not-to-use guidance.

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

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

Describes fetching the page, extracting title/description/key links, and emitting markdown. Adds context beyond annotations, which already declare readOnly and idempotent. 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?

Single well-structured paragraph with no redundant sentences. Front-loaded with purpose, then details, then use cases. Highly concise.

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

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

For a simple tool with no output schema, the description explains the input, process, and output format completely. Annotations cover safety. No gaps.

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

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

Schema has 100% coverage with parameter descriptions. The description adds no new semantic details beyond schema, so baseline 3 is appropriate.

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

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

Clearly states the action: 'Generate a production-ready llms.txt file for any URL'. Specifies the resource (URL) and output format. The tool is uniquely defined among siblings.

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 lists three use cases (client indexing, own project, competitor audit). Does not mention when NOT to use or compare to alternatives, but gives clear context.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds value by specifying the returned content (synonyms, common names, hierarchy summary), enhancing transparency 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, concise sentence with only 12 words. It efficiently conveys the tool's purpose without unnecessary information.

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

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

For a simple, read-only tool with two parameters and an output schema, the description is complete. It covers what the tool does and what it returns. No additional context seems necessary.

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 description does not add new parameter information. It merely echoes the schema by mentioning 'EOL id', but the schema already provides detailed descriptions for both parameters.

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

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

The description clearly states the tool fetches a taxon page by EOL id, with specific content (synonyms, common names, hierarchy summary). This precise verb-resource-object combination distinguishes it from sibling tools like pages_by_name or search.

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

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

The description implies use when an EOL id is available but does not explicitly state when to use this tool versus alternatives like pages_by_name or search. No exclusion criteria or prerequisites 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds no further behavioral details beyond the core functionality, which is fine but doesn't exceed what annotations provide.

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

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

Single sentence that is concise, front-loaded, and contains 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 the low complexity (one parameter, existing output schema), the description provides sufficient context for an AI agent to understand the tool's purpose and usage.

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

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

Schema coverage is 100% with a clear description of taxon_id. The tool description adds context by linking it to get_page, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool returns a taxonomic hierarchy for a given EOL hierarchy entry ID, and ties it to the get_page tool, distinguishing it from siblings like get_page.

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 specifies the use case: after getting a page, to retrieve its hierarchy. It implies context but does not explicitly state when not to use or mention 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 and destructiveHint. The description adds return field details and parameter behavior, providing useful context beyond annotations.

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

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

Two concise sentences front-load the core purpose, with no wasted words. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately covers return fields and use case. Slightly higher complexity would benefit from more 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?

Schema coverage is 100% and includes a description for 'include_inactive'. The tool description adds no further parameter semantics, so 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 'List the caller's active subscriptions' and enumerates return fields, effectively distinguishing from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, covering behavioral safety. The description adds no further behavioral details (e.g., rate limits, authentication, or what happens on missing names). It does not contradict annotations.

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

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

The description is a single, concise sentence (10 words) that communicates the core purpose efficiently. No extraneous information, and the key verb and resource are 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?

Given the tool's simplicity (1 required parameter, output schema present), the description adequately explains input and output. It could mention whether multiple IDs are possible or what happens if the name is not found, but this is minor given the output schema likely covers return format.

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

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

Schema coverage is 100% and the parameter description in the schema ('e.g. "Panthera leo"') is already clear. The tool description ('exact scientific name') adds no new semantic value beyond what the schema provides, meeting baseline expectations.

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 a specific action ('Find'), a specific resource ('EOL page id(s)'), and a specific input condition ('exact scientific name'). This distinguishes it from sibling tools like get_page (which retrieves a page by ID) and search (which supports partial matches).

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

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

The description implies usage for exact scientific name lookups but does not explicitly state when to use this tool over alternatives (e.g., search, search_within) or when not to use it (e.g., for common names). No exclusions or prerequisites are mentioned.

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 and uninformative, but the description carries the full burden and does excellently. It discloses the rate limit ('5 per identifier per day'), the claim_token flow for anonymous filing, the fact that it's free and doesn't count against tool-call quota, and how feedback is consumed ('team reads digests daily'). 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 long but dense: each sentence provides distinct value (purpose, usage categories, exclusion, content rules, token flow, rate limit, cost). It is front-loaded with the core purpose and then elaborates. Slightly verbose, but 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?

Given the tool's moderate complexity (4 params, no output schema, all optional), the description covers the full lifecycle: what the tool does, when to use it, exclusions, content guidelines, follow-up token mechanism, rate limit, and cost. An agent can invoke it correctly without 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?

All 4 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value with an explicit claim_token usage example (pipeworx_feedback({claim_token:'pwfb_…'})) and explains the token's role in retrieving resolution status, which reinforces and extends the schema's parameter 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 a clear, specific purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and enumerates the feedback types (bug, feature, data_gap, praise). It distinguishes itself from sibling tools by being the only feedback channel among the listed 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?

Provides explicit when-to-use heuristics for each feedback type (bug, feature/data_gap, praise) and an explicit exclusion for tools from other MCP servers: 'if the tool came from a different MCP server ... file it with that server instead.' It also gives content guidance (describe in terms of Pipeworx tools/packs, don't paste the end-user prompt). This is textbook 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 declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable transparency: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' 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?

Six sentences, front-loaded with the primary function, followed by use cases and technical details. Every sentence adds value without redundancy or fluff.

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

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

Covers purpose, usage, transparency, and parameters well. No output schema exists, but the description hints at return structure ('top tools, top packs, and total call volume'). Could be more explicit but sufficient for a simple trending tool.

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

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

Schema description coverage is 100% for the single parameter 'window', with full enum values and meanings. The main description mentions the window in passing but adds no additional value beyond the schema, meeting the baseline for high coverage.

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

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

The description states 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume' with specific verb 'returns' and resource 'trending data', clearly distinguishing it from sibling tools like 'discover_tools' by focusing on current popularity.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. It does not provide explicit when-not-to-use guidance but 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?

Annotations provide readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: monotonicity checks, partition filter, semantic anchor, fill check, and response structure. No contradictions.

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

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

The description is long but every sentence adds value. It is front-loaded with purpose and well-structured with clear sections. Minor redundancy but overall efficient for the 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?

Despite no output schema, the description fully explains response fields (opportunities, partition_check), fill check, and trade guidance. Comprehensive for a complex arbitrage 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%. Description adds value: explains event slug format, accepts full URLs, defines topic as seed question, and clarifies mode behavior beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: trending_scan with no args, event for a specific market, topic for cross-event scanning. Recommends event mode and explains fill check with conditions not to trade.

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 mark it as read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral details: model families, edge calculation, caching (1h KV-level), response structure with diagnostics, and tradeable-edge knobs. 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 adds value. It is front-loaded with purpose, then organized into segments, knobs, and response fields. Zero waste, highly 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?

For a 9-parameter tool with no output schema and no required parameters, the description is remarkably complete. It covers response structure, segment details, caching, edge calculation, slippage, knobs, and diagnostics, leaving no important 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%, so baseline is 3. However, the description adds significant context beyond the schema by explaining how knobs like min_liquidity and max_spread_pp work in the tradeable-edge pipeline and how they affect opportunity filtering.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'top Polymarket markets' are specific, and the phrasing distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly says 'Built for what should I bet on today' and explains that agents discover opportunities without paging hundreds of markets. It provides context for knobs but does not explicitly state when to use this tool versus alternatives like polymarket_edge_tracker or polymarket_arbitrage.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: return structure (tracked[], expired[], snapshot_dates[]), field explanations, limitations (60-day TTL, daily closes), and data gaps due to cache-miss. 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 dense paragraph that front-loads the purpose. It is efficient but could be improved with structured formatting (e.g., bullet points for return fields). Every sentence adds value, and there is no redundancy.

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

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

Given no output schema, the description fully explains the return format (tracked[], expired[], snapshot_dates[] with field definitions), limitations (TTL, daily closes), and parameter behavior. This is comprehensive for a tool with simple parameters.

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 context by explaining how days and window parameters affect the query (e.g., defaults, bounds, snapshot family) and their role in the tool's functionality.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge duration and shrinkage, distinguishing it from similar 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?

The description explains when to use this tool (to assess edge longevity) and contrasts with other tools implicitly, but does not explicitly list when not to use it or provide 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?

Description adds significant behavioral context beyond annotations: it is a read-only check (aligns with readOnlyHint), explains it does not execute trades, details return fields for both modes, and warns about partial fill risks. 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?

Description is approximately 200 words, structured with clear sections (single-market vs basket), uses bold for key terms, and front-loads the core purpose. It is slightly long but every sentence adds value; no redundancy. Could be trimmed slightly but remains effective.

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

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

Despite no output schema, the description thoroughly explains all return values for both modes (e.g., top_of_book, vwap_fill_price, verdict, capture_ratio, thin_legs). It also covers the use case, risks, and prerequisites. Given the tool's complexity (4 params, 2 modes), this is complete and sufficient for proper 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 description coverage is 100%, so baseline is 3. The description adds extra meaning: explains defaults (size_usd=1000, side='auto' for basket), clamps (10-1,000,000), and mode-specific interpretations (settlement notional for basket). This enriches the schema but does not fundamentally transform it.

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

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

Description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It uses specific verbs ('check', 'fills') and resources ('market slug/URL', 'event slug/URL'), and contrasts with siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround is not capturable, partial fills create unhedged directional positions), providing clear context for 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, idempotentHint, and destructiveHint=false, so the description focuses on additional behavioral traits: safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and their exact meanings. It fully explains what happens when bet shapes mismatch or events are semantically unrelated, beyond the annotations.

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

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

The description is verbose but well-structured: purpose first, then modes, response, safety fields. It front-loads the essential statement. Some sentences are long and complex, but every sentence adds necessary information given the tool's complexity. Minor conciseness loss from detailed safety explanations, but appropriate for the domain.

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 covers return values: leg-by-leg prices and top_spreads_pp, plus safety fields. It explains compatibility_warning, temporal_alignment, skipped counters. It covers both success and warning scenarios, making the tool's behavior fully understandable without external documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the macro shortcut list (10 topics) and that explicit tickers override topic mapping. It also describes the response structure implicitly via parameter usage, but does not add syntax details beyond the schema. Still, it adds meaningful context for parameter selection.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and distinguishes from sibling tools like polymarket_arbitrage by specifying this computes a spread across two specific venues. It has a specific verb 'spread' and resource 'Kalshi-Polymarket cross-venue prices', and the two modes differentiate it from single-venue tools.

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

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

The description explicitly says when to use (when bet shapes are equivalent) and when not (compatibility_warning scenarios). It explains two modes: topic shortcuts and explicit tickers, and warns that most pre-mapped topics return warnings, guiding the agent to prefer explicit pairings for reliable spreads.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). Description adds scoping detail ('scoped to your identifier') which is valuable behavioral context beyond annotations. No contradictions.

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

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

Three sentences, each serving a distinct purpose: function, usage examples, scoping and pairing. No unnecessary words.

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

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

For a simple tool with 1 optional param, good annotations, and no output schema, the description covers purpose, usage, and scoping. Could mention return format (value or list) explicitly, but not essential.

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

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

Schema already describes the key parameter well (100% coverage). Description adds concrete use-case examples and reiterates the omission behavior, enhancing practical 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?

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb+resource pair. It also distinguishes from siblings by referencing '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 'Use to look up context the agent stored earlier' and provides concrete examples (ticker, address, notes). Also states pairing with remember/forget, guiding when to use this vs alternatives.

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

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

Annotations already indicate safety (readOnly, idempotent, not destructive). The description adds behavioral details beyond that: return fields, filter examples, mark_read semantics, and polling suitability. 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 about 5 sentences, front-loaded with the main purpose. Each sentence adds information without redundancy. Could be slightly more compact, but 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?

With no output schema, the description explains return values (source, citation_uri, payload). All 5 parameters are covered, and annotations handle safety. The alternative URL adds context. Minor gap: no mention of pagination beyond limit.

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

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

Schema coverage is 100% (baseline 3). The description adds value by providing concrete examples ('type (e.g. sec_8k)') and clarifying the behavior of mark_read, going beyond the schema descriptions.

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

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

The description states the action ('Pull fired events') and the resource ('subscription feed'), specifying return fields (source, citation_uri, payload). While clear, it does not explicitly distinguish from sibling tools like 'search' or 'recall', keeping it from a 5.

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 mentions polling works and provides an alternative URL for scripts/dashboards, but it does not offer explicit guidance on when to use this tool versus alternatives. Usage context is implied but not directive.

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

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

Description adds rich behavioral details beyond annotations: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail note, return structure with grouped changes and citation URIs. Annotations already indicate read-only and idempotent; description complements them.

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

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

Description is detailed but front-loaded with example queries. While long, every sentence adds value and it is well-structured: examples, behavior, alternative. Minor verbosity prevents a perfect score.

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?

Tool is complex with multiple data sources, fallback, and no output schema. Description covers return format, source grouping, citation URIs, and caveats (USPTO soft-fail). Completeness is excellent given the 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?

Even though schema coverage is 100%, the description adds significant value: explains relative date shorthand for 'since' (e.g., '7d', '3m'), suggests '30d' for typical monitoring, clarifies ticker vs. CIK for 'value', and notes 'company' is the only supported type.

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

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

The description clearly states the tool provides a change feed for a company in a recent time window, with example queries like "What's new with X". It distinguishes from sibling tool entity_profile by explicitly recommending it for static profiles.

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

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

Provides explicit guidance on when to use this tool (recent changes) vs. entity_profile (static profile), and explains fallback behavior between GDELT and GNews. No other tool covers this use case.

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 idempotent and non-destructive mutation. Description adds key behavioral details: scoping by identifier, persistence differences between authenticated and anonymous sessions (24hr vs persistent). Lacks explicit overwrite semantics but idempotentHint covers this somewhat.

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

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

Front-loaded with purpose, efficiently packed with guidance. Slightly verbose but every sentence adds value. Could be streamlined but remains readable.

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 and sibling tools for retrieval/deletion, description is complete: covers purpose, usage, persistence, and pairing. No gaps for an agent to misuse.

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

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

Schema has 100% coverage with minimal descriptions. Tool description adds semantic value by clarifying value can hold any text and listing examples (findings, addresses, preferences, notes), going beyond schema.

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

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

The description clearly states the tool saves data for later reuse, specifies the resource (key-value pair) and action (save). It distinguishes from siblings (recall, forget) explicitly.

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

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

Provides explicit when-to-use scenarios (discovering something worth carrying forward) and examples (ticker, address, preference). Mentions pairing with recall and forget, giving clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit labeling of identifier sources, handling of unresolved identifiers, and cascading internal lookups. No contradiction with annotations; the description enriches the behavioral model significantly.

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 value: examples lead off, then purpose, usage guidance, and detailed type breakdowns. It is well-structured and front-loaded, though slightly dense. It earns a 4 rather than a 5 because it could be trimmed slightly without losing information.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, cascading lookups) and absence of an output schema, the description is remarkably complete. It explains what each type returns, how failures are handled, input formats, and the value over manual lookups. It leaves little ambiguity for an AI agent about how to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The schema already describes both parameters thoroughly. The description reinforces parameter semantics by specifying accepted input forms (ticker, CIK, company name for company; brand/generic for drug), but it does not add new parameter details beyond the schema. It adds context about output behavior rather than parameter semantics, so a 3 is appropriate.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers required by other tools, with specific verb+resource ("resolve a user-spoken NAME to the canonical/official identifiers"). It differentiates from siblings like entity_profile and compare_entities by focusing on name-to-ID lookup. Examples of user queries and supported types clarify the purpose distinctly.

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 usage guidance: "Use FIRST whenever you have a name but need an ID." It also explains that it replaces 2-3 manual lookups. It does not explicitly mention when not to use or name alternatives, but the context is clear enough for an AI agent. This aligns with a 4: clear context without exclusions.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds that it probes with ai_visibility_check, ranks results, and returns per-entity fields (score, confidence, signal density). No contradictions; additional behavioral context is provided.

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

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

Three sentences with no wasted words. The core action ('compare AI visibility'), internal process (calls ai_visibility_check), output summary, and use case are all front-loaded and efficient.

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

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

Given no output schema, the description appropriately describes the return format (ranked list with score, confidence, signal density per entity). It explains the core process. Minor missing details like ranking algorithm or score interpretation, but overall sufficient for safe use.

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

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

Schema descriptions cover all 4 parameters. The description enriches meaning by stating the first entity is treated as the 'subject' for narrative, and that 'context' disambiguates common names. This adds value 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 verb 'compare' and the resource 'AI visibility across multiple entities'. It references the internal call to 'ai_visibility_check', distinguishing it from that single-entity sibling. Both purpose and differentiation are explicit.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example query. It implies when to use but does not explicitly state when not to use nor compare with siblings like 'compare_entities'. Still, the guidance is clear enough for most scenarios.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeout. 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?

Description is front-loaded with the core purpose and structured logically. While every sentence is valuable, it could be slightly more concise; still highly effective.

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

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

Despite lacking an output schema, description lists return fields (summary block, per-advisory detail, etc.) and covers performance caveats, error handling, and ecosystem limitations. Fully complete for a composite tool.

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

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

Schema covers both parameters with descriptions. Description adds acceptance of scoped packages and default behavior for version parameter, enhancing 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?

Description clearly states it's a composite check for npm packages, fanning out to deps.dev and bundlephobia. It specifies the purpose: deciding whether to add an npm package, and is distinct from sibling tools.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and notes NPM ecosystem only, with alternatives for PyPI, Maven, etc. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, establishing a safe, non-destructive profile. The description adds no further behavioral details (e.g., pagination, result limits), but does not contradict annotations.

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

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

The description is a single, concise sentence that front-loads the action and resource. It is appropriately short given the tool's simplicity and the thoroughness of other structured fields.

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

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

The tool has an output schema (not shown), reducing the need to describe return values. However, the description does not mention the scope or nature of results, leaving some ambiguity for a search operation.

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

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

Schema coverage is 100% with clear descriptions for both 'query' and 'limit'. The description adds contextual value by specifying 'name (common or scientific)', but does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the verb 'Search' and the resource 'EOL' with the specific domain of names (common or scientific). It avoids tautology and provides a concise purpose, though it does not differentiate from siblings like 'search_within' or 'pages_by_name'.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or context for choosing this over other search-related sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds rich behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, has a 200K char cap with truncation and flag. 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?

Three sentences: first defines purpose, second gives usage guidance, third adds technical details. Efficient and front-loaded, but could be slightly tighter. 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?

Despite no output schema, the description thoroughly explains return values (passages with offsets and similarity scores), embedding model, window size, character limit, and pairing with sibling tool. Complete for a search tool with 3 parameters.

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 clear descriptions. Description adds value by providing examples for the 'query' parameter and clarifying the truncation behavior for the 'text' parameter. Baseline 3 increased due to added practical guidance.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific verbs like 'semantic search INSIDE a fetched record'. It distinguishes from siblings by emphasizing it's for inside a record and pairing with ask_pipeworx_grounded, making its purpose unique and 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?

Explicitly says when to use: 'Use when the record is too big to cram into the prompt'. Provides concrete examples and pairs with ask_pipeworx_grounded. Does not explicitly list alternatives, but the usage scenario is well-defined.

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 OAuth requirement, delivery channels, SMS rate limit (10/day), and webhook signing secret returned once. Annotations indicate idempotent and non-destructive, which is consistent.

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

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

Front-loaded purpose, well-structured with types listed, but slightly lengthy. Still efficient for the 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?

Covers all aspects: types, required auth, delivery options, rate limits, and return value (subscription id). Complex tool fully explained.

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 significant meaning beyond schema with detailed type-specific examples (e.g., sec_8k items, polymarket_edge topic) and delivery channel specifics (email, SMS with verification, webhook with HMAC). Schema coverage is 100%, but description enriches 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 'Create a proactive monitoring subscription to a live-data event stream' with verb and resource, and distinguishes from sibling tools like unsubscribe 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?

Provides clear context for when to use (creating a subscription) and prerequisites (OAuth account). Does not explicitly exclude alternatives but enough guidance is given.

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. The description adds what the tool returns (example questions with tool+argument shape) and how calling with/without topic works. No contradictions.

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

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

The description is well-structured, starting with common queries, then stating purpose, listing categories, giving usage instructions, and ending with when to use. Every sentence adds value; it is appropriately sized.

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 return values (category-bucketed example questions with tool+argument shape). It covers the parameter, usage context, and addresses the sibling tools by mentioning meta-tools. 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% with a detailed description for 'topic'. The description adds context: omitting topic gives 'full spread', passing topic 'focuses' the results. This adds meaning beyond the schema.

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

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

The description clearly states the tool is the 'onboarding entry point' for a new agent, using specific verbs like 'Returns category-bucketed example questions'. It distinguishes from siblings by noting it teaches how to call meta-tools like ask_pipeworx, entity_profile, etc.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and lists alternatives (meta-tools). This provides clear when-to-use and when-not-to-use guidance.

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

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

Discloses behavioral traits beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events. No contradiction with annotations.

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

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

Two concise sentences with front-loaded action and no unnecessary words. Every sentence adds essential information.

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

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

Adequately covers all needed information: what it does, constraints (ownership), and outcome (deactivation). No output schema needed given clear explanation.

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

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

Schema has 100% coverage for the single parameter; description adds value by relating ownership enforcement to the id, providing functional context beyond the schema's basic description.

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

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

The description clearly states the action ('Cancel a subscription by id') with specific verb and resource, and naturally distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('only cancel your own subscriptions') and effect (deactivation not deletion), providing clear context. However, it does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds crucial semantics: the distinction between could_not_verify (check did not happen, must not be used as evidence) and unsupported (no source found). It also discloses the return structure (verdict, grounded value with citation, reasoning) and the routing behavior, going well beyond the annotations.

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

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

While the description is longer than average, it is dense and structured: trigger phrases lead, followed by usage, routing logic, return values, and critical caveats. Each sentence earns its place, especially the IMPORTANT warning about could_not_verify, and the 'Replaces 4–6 sequential calls' line justifies the tool's value without wasting words.

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

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

For a tool with 2 parameters and no output schema, the description fully covers what it returns (verdict categories, actual value with citation, reasoning) and handles edge cases like could_not_verify and unsupported. It also explains the fallback routing for any claim type, making it complete for the agent to understand invocation and interpretation without needing an output schema.

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

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

Schema coverage is 100% and both parameters (claim, tolerance_pct) are well-described in the schema. The description adds no additional parameter detail; however, it mentions tolerance implicitly through 'exact percent-delta math' and the caveat about could_not_verify, but these are not replacement for schema docs. The baseline 3 applies because the schema carries the full burden.

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

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

The description uses a specific verb+resource ('natural-language claim verification against authoritative sources') and distinguishes its scope with concrete trigger examples. It also clarifies the two distinct paths (SEC EDGAR fast path vs. grounded pipeline) and contrasts with the 4-6 sequential calls it replaces, making it clearly distinct from sibling tools like search or ask_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?

The description explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial claims (structured path) and all other claims (grounded pipeline), but does not explicitly name alternatives or state when NOT to use it. The guidance is clear and practical, just not exhaustive.

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