Tankerkoenig

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

Adds value beyond annotations by disclosing that probing multiple models is possible, returns per-model data with combined view, and that Anthropic calls require user API key. No contradiction with readOnlyHint or idempotentHint.

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

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

Four sentences, front-loaded with primary purpose, efficient and 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?

No output schema, but description sketches return structure (per-model score, confidence, signals, raw_response, combined view). Covers key usage cases. Missing details like rate limits or error handling, but acceptable for this 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 description coverage is 100%, so baseline is 3. Description adds minor context like default model name and that _apiKey is for Anthropic, but mostly restates schema info.

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

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

Description clearly states the tool probes LLMs for brand visibility and returns a score (0-100), with specific verb and resource. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on individual entity visibility across models.

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

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

Provides clear context for when to use (AI-marketing audits, brand checks) and explains default model vs. paid option. Lacks explicit exclusions or differentiation from overlapping sibling tools like 'entity_profile'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds useful context beyond that: the tool routes to one of 5,714 tools across 1,495 sources, fills arguments, and returns answers with stable pipeworx:// citation URIs. This gives the agent a clear model of what happens when the tool is invoked.

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 average but each section earns its place: preference warning, domain list, behavior description, trigger phrases, and examples. It is front-loaded with 'PREFER OVER WEB SEARCH' and remains readable despite the detail.

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

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

For a broad routing tool with no output schema, the description sufficiently explains what input should look like, what the tool does internally, and what the output will contain (structured answer with citation URIs). The examples and 'START HERE' guidance make it effectively complete for agent 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 already covers all six parameters at 100%, so the baseline is 3. The description enhances this by stressing that 'question' accepts natural language and that query, q, prompt, text, and input are aliases, while examples clarify the expected phrasing. This adds value beyond the schema field descriptions.

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

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

The description clearly states the tool's function: it routes factual questions to the appropriate source tools and returns structured answers with citation URIs. It explicitly lists supported domains and gives example queries, making the resource and scope unmistakable and distinguishing it from generic web 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 gives explicit guidance: 'PREFER OVER WEB SEARCH' and 'USE WHENEVER the user asks...' with trigger phrases and concrete examples. It does not explicitly contrast with sibling ask_pipeworx variants or deep_research, so it stops short of full when-not-to-use coverage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context: it's an experimental edge, currently has no active candidate, and matches ask_pipeworx exactly right now. It also clarifies it is a full working router with 'falls back to nothing', which goes beyond what annotations provide.

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

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

The description is a bit lengthy but well front-loaded with the core identity ('Beta version of ask_pipeworx') and then provides critical state details. Each sentence adds useful information—current no-candidate status, usage guidance, and comparison purpose. There is minor redundancy (e.g., 'experimental edge' repeated conceptually) but overall it is structured logically.

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 universal router with six parameters and no output schema, the description is complete: it states what the tool is, its current state, how to use it, and what to expect in terms of response shape ('same response shape' as ask_pipeworx). An agent has everything needed to invoke it correctly alongside its sibling tools.

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

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

Schema coverage is 100% with all parameters described, including aliases like q, text, input, and question. The description does not add parameter-specific semantics beyond the schema, instead deferring to ask_pipeworx's behavior. This meets the baseline expectation when the schema handles the documentation 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 clearly states it is the 'Beta version of ask_pipeworx' and an 'identical universal router' with the same scope and behavior, immediately distinguishing it from siblings. It specifies the resource (the routing tool) and the verb (ask). This is highly specific and leaves no ambiguity about what the tool does.

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

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

The description explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear condition for use. It also notes that results are compared against the stable router to decide merges, giving context on when this experimental variant is relevant. Though it doesn't explicitly say when not to use it, the guidance is strong and practical.

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?

Goes well beyond the readOnly/idempotent annotations by revealing the refusal behavior, the specific refusal_reason enumeration, the verbatim evidence requirement, and the extra LLM call cost. This gives the agent a precise model of what will and won't happen.

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

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

Dense but every sentence earns its place: purpose, routing mechanism, success/refusal output formats, when-to-use, and cost tradeoff. The critical scoping and usage information is front-loaded before the output 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?

With no output schema, the description fully compensates by specifying the success return fields and the exact refusal_reason values. It also covers routing, tool selection scale, sourcing, evidence format, and cost considerations, making it complete for an agent deciding whether and how to call it.

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

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

Schema coverage is 100% and the schema already documents the question parameter and its aliases. The description does not add substantial parameter-level semantics beyond establishing that the input is a natural-language question, matching the baseline for high schema coverage.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that extracts answers only from tool results, and explicitly names ask_pipeworx as the sibling it shares routing with. It specifies the resource, behavior, and output shape, making the tool's role unambiguous.

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

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

Provides explicit when-to-use guidance: quoted, cited, or acted-on answers where the agent must not invent facts, with concrete domains like financial verdicts and legal claims. Also states the alternative preference: prefer ask_pipeworx for casual lookups due to the extra LLM call cost.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds extensive behavioral details: resolver contract, market_match_confidence, cancellation rules, parent_event extraction, news fallbacks, and short-circuit paths for low-confidence or closed markets. 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the purpose but includes extensive detail that, while valuable, could be condensed for easier scanning. Still earns its place given tool 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?

Given no output schema and high complexity (multiple classifiers, fan-out patterns, response shapes, edge cases), the description is remarkably complete. It covers resolution-rule risk, illiquid spreads, parent_event extraction, news fallback, and safety blocking in detail. No critical 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. The description adds value by explaining the 'market' parameter can be slug, URL, or question text, and clarifies 'depth' and 'include_raw' semantics with examples. This goes beyond the schema's minimal descriptions.

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

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

Clearly states the tool researches a Polymarket bet using Pipeworx data. Specifies input types (slug, URL, question text) and provides example use cases that distinguish it from sibling polymarket tools. The description includes classifiers and fan-out examples, making purpose 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?

Provides explicit when-to-use examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and covers special cases like closed markets and low-confidence matches. Lacks explicit when-not-to-use guidance but implies usage context well.

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

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

Description adds value beyond annotations: explains sorting, citation URIs, handling of fiscal year offsets. No contradiction with annotations (all 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?

Slightly verbose but front-loaded with examples; every sentence is informative. Efficient given 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?

No output schema but description covers return format (paired data + URIs) and behavior (sorted). Sufficient for a comparison tool with simple inputs.

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

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

Schema coverage is 100% and description adds meaning: explains 'type' enum values and 'values' examples with constraints, enhancing 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 uses specific verbs like 'compare' and lists trigger phrases. Clearly states it performs side-by-side comparison of companies or drugs, distinguishing from sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides when-to-use examples. Also explains what data is pulled for each entity type.

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

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

Beyond the annotations (readOnly/openWorld/idempotent), the description discloses dense behavior: findings are 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', the tool 'never invented' answers and returns 'explicit gaps[]', standard/thorough return 'contradictions[]', large records are 'semantically excerpted to the passages relevant to each facet (not head-truncated)', and latency is bounded ('Expect 15-60s... up to ~90s'). None of this contradicts the annotations.

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

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

The description is long but every sentence earns its place: account gate, alternative routing, core mechanism, exclusion, output packet shape, depth semantics, citation resolvability, and timing. It is front-loaded with the most operationally critical fact (ACCOUNT REQUIRED; use ask_pipeworx if not signed in) before any marketing or mechanism detail.

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

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

With no output schema, the description carries the full burden of explaining the return shape and does so completely: findings packet fields, gaps[], contradictions[], the hop field, citation_uri resolvability ('a citation you get back is always fetchable'), auth tiers, and latency. An agent has everything needed to select depth, set expectations, and interpret results 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 the depth parameter's schema description already details hop counts, so the baseline is 3. The description adds genuine extras above that: the paid-plan gate on thorough, per-depth timing expectations, and worked examples of what makes a good question ('compare X and Y's regulatory + financial exposure'), which justify one point above baseline.

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

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

The description states a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1495 STRUCTURED data sources... in ONE call', and explicitly draws the boundary 'this is NOT open-web search'. It also distinguishes from siblings by naming the alternative directly ('For a single lookup use ask_pipeworx instead'), so an agent can separate this from ask_pipeworx, validate_claim, and compare_entities without opening their schemas.

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

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

The description gives explicit when/when-not guidance: 'Best for broad/multi-part questions over structured data' states the positive condition, while 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead' name the exact alternative and the conditions that trigger it. It also conditions depth selection on account tier: 'depth:"thorough" needs a paid plan'.

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 and idempotentHint; description adds that results are ready to call with full schemas, no second lookup needed. No contradictions.

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

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

Description is front-loaded with purpose and usage, but slightly verbose. Every sentence adds value, but could be more concise.

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

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

With strong annotations and full schema coverage, description fully explains return format (top-N tools with schemas) and when to use, making it complete for agent use.

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

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

Schema coverage is 100% so baseline 3; description adds aliases for query and limit info, with examples that enhance usability 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 'Find tools by describing the data or task' with specific verb+resource and lists many domains, distinguishing it from sibling tools which are more specialized.

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', providing clear when-to-use guidance and 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 idempotent, read-only, non-destructive. Description adds substantial behavioral context: fans across multiple sources, specific data returned, patent soft-fail note, and constraints on input. 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?

Description is dense and front-loaded with example queries, but the structure is a single paragraph with internal bullets. All information is useful, though slight restructuring could improve readability 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 2 parameters and no output schema, description fully explains tool's purpose, data sources, return structure, and limitations. Covers all needed context for correct invocation.

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

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

Schema coverage is 100%, and description adds value with examples ('AAPL', '0000320193'), reiterates constraints (only 'company', no names), and clarifies that names require resolve_entity first.

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 identifies specific action: 'full cross-source profile of a US public company in ONE parallel call.' Provides example queries and lists data sources and returned fields, clearly differentiating from sibling tools like chaining single-pack lookups.

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

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

Explicitly states preference: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides when-not-to-use: 'names not supported (use resolve_entity first if you only have a name).'

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' confirms mutation but doesn't add new behavioral details (e.g., permanence, undo capability). No contradiction, but value added is minimal beyond the structured 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: first defines action, second lists use cases. No unnecessary words; information is front-loaded and well-structured.

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

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

Given the tool's simplicity (single required param, no output schema), the description fully covers purpose, usage timing, and relationship to siblings. No gaps remain.

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

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

Schema has 100% description coverage for the sole parameter 'key' ('Memory key to delete'). The tool description does not add extra meaning or formatting guidance beyond the schema, so it meets the baseline without improvement.

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 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall', which serve complementary storage and retrieval functions.

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

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

Provides explicit scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also references sibling tools for pairing, offering clear guidance on when to invoke this tool.

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

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

Annotations declare it read-only and idempotent. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format. 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 with no wasted words. Front-loaded with main action. Every sentence serves a purpose.

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

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

Given the low complexity (2 params, no output schema), the description is complete. It explains what it does, how it works, output format, and use cases. 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 covers both parameters with descriptions. The description adds context about the output format and the purpose of max_links indirectly. However, no additional parameter meaning beyond schema.

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

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

Clearly states the tool generates a llms.txt file for a URL, targeting AI crawlers. The verb 'generate' and resource 'llms.txt file' are specific. Among sibling tools, this is unique, so no confusion.

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

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

Provides explicit use cases (indexing client's site, drafting for own project, auditing competitors). Does not explicitly state when not to use or mention alternatives, but context is strong.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description adds value by noting the default behavior (active only) and the parameter effect. No contradiction.

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

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

Two sentences: first defines purpose and output, second gives usage guidance. No filler.

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

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

For a simple list with one optional parameter and no output schema, the description is complete: covers return fields, default behavior, and practical use case.

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

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

Schema coverage is 100%; the description doesn't add meaning beyond the schema's existing parameter description. Baseline 3 applies.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields. Distinguishes from sibling tools like subscribe and unsubscribe through the usage context.

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: 'review what you're monitoring before adding more or to find an id to cancel.' No exclusions, but provides clear context and contrasts with subscribe/unsubscribe.

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

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

Annotations offer no safety hints (all false), so the description carries the full burden. It discloses rate limiting (5 per identifier per day), free usage, no quota impact, claim_token return for later lookup, and daily digest reading. 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 front-loaded and dense; every sentence serves a purpose, including usage boundaries, claim_token flow, and rate limits. It is longer than strictly necessary but free of filler, earning a high 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?

Even without an output schema, the description fully explains the return mechanism (claim_token) and post-filing behavior. It covers all parameters, usage boundaries, and exclusions comprehensively, leaving no significant gaps 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%, so baseline is 3. The description adds value by demonstrating claim_token round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying message expectations 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 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates feedback types (bug, feature, data_gap, praise). It distinguishes from sibling tools by explicitly restricting scope to tools served by this Pipeworx connection, making it a unique purpose.

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

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

Provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data (bug)...') and explicit when-not-to-use guidance for tools from other MCP servers, directing users to file elsewhere. It also offers a fallback for uncertainty: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides valuable context about data source, caching, and privacy beyond annotations.

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

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

The description is concise: two sentences for purpose and parameter, then three bullet points for use cases. Every sentence is informative. No wasted words or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return values (top tools, top packs, total call volume), caching behavior, data source, and privacy. It enables correct 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 only parameter 'window' has its description in the schema matching the description in the text ('Shorter windows surface what's hot right now; longer windows show steady-state demand.'). Schema coverage is 100%, so no additional meaning is added 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 that the tool returns 'top tools, top packs, and total call volume' over a specified window. It specifies the verb ('returns'), resource, and scope. It distinguishes from siblings like 'discover_tools' by focusing on real-time popularity of tools among AI agents.

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

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

Three use cases are explicitly listed: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent demand. Window behavior is explained (shorter vs longer windows). However, no direct exclusions or alternatives are mentioned, though 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive context: scanning process, semantic anchor threshold (0.30 Jaccard), partition filter (placeholder drops >20%), fill check logic, 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 well-structured, with front-loaded purpose and mode explanations. Every sentence adds value, covering scanning behavior, edge cases, and fill check. Could be slightly more concise, but it earns its length.

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

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

Given the complexity (arbitrage detection, multiple modes, fill check) and lack of output schema, the description is remarkably complete. It explains return fields, edge cases (skipped_low_similarity, placeholder rejection), and references polymarket_fill_risk for custom sizing.

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% (both parameters documented). The description adds substantial meaning: explains what values to pass (event slugs, topic seed questions), how they work, and the differences between modes. The description 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's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between trending scan, event mode, and topic mode, and is specific about the methods used.

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 explains when to use each argument (no args for trending scan, `event` for a specific market, `topic` for cross-event scanning) and provides examples. It also warns against trading when fill check shows unrealizable edge. However, it does not explicitly contrast with sibling tools like polymarket_edges.

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

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

The description extensively discloses behavioral traits: it details the five model families, response structure, caching (1h KV-level), edge calculation (including slippage), and diagnostics when segments are empty. This goes well beyond annotations (which indicate readOnly, openWorld, idempotent) by explaining internal logic, limitations, and tradeable-edge filters. 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 front-loaded with purpose and model explanations, but it is quite long (4 paragraphs) and dense. Every sentence adds value, but the level of detail could be streamlined without losing clarity. It balances comprehensiveness with some verbosity.

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

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

Given the tool's complexity (9 parameters, nested response, no output schema), the description is remarkably complete. It explains the response structure (by_segment segments, diagnostics), caching behavior, and parameter interactions. Without an output schema, the description fully compensates by detailing the return fields, making it sufficient for an agent to understand the tool's behavior.

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

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

All 9 parameters have explicit descriptions in the input schema (100% coverage), so the baseline is 3. The tool description adds minor context (e.g., tradeable-edge filters for min_liquidity and max_spread_pp, explanation of min_partition_leg_kelly) but does not significantly extend the meaning provided by the schema itself.

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, explicitly targeting the 'what should I bet on today' use case. However, it does not differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about when to prefer this over alternatives.

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

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

The description provides clear context for use, including the intended purpose, an overview of the three output segments, and guidance on knobs like min_liquidity and max_spread_pp. It explains why Fed bets are excluded but does not explicitly state when NOT to use this tool or recommend alternative tools for different scenarios.

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

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

The description adds substantial behavioral context beyond annotations, including data source (daily snapshots), response structure (tracked[], expired[], snapshot_dates[]), and limitations (60-day TTL, decay computation). Annotations already indicate read-only and idempotent behavior, and the description does not contradict them.

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

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

The description is detailed but efficient, front-loading the purpose and then covering args and response. It could be slightly more structured, but every sentence adds value.

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

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

Despite having no output schema, the description thoroughly covers the return values, including field meanings and limitations. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining defaults and clamping for 'days' and the meaning of 'window' as snapshot family. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question of how long an edge has existed and whether it is shrinking, distinguishing it from sibling tools that likely provide raw edge data.

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

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

The description provides context on when to use this tool, emphasizing the difference between fresh and old edges. However, it does not explicitly list when not to use it or name alternatives among sibling tools, leaving some ambiguity.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral detail beyond that: it walks the order book ladder, returns fill quality verdicts (clean|degraded|cannot_fill), identifies thin legs, and warns about forced directional risk. No contradiction with annotations.

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

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

The description is long but dense with useful information. It is structured with clear sections for single-market and basket modes, and a usage note at the end. Every sentence adds value, but minor condensation could improve readability without losing content.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is exhaustive. It details all return fields, edge cases (thin_legs, forced_directional_risk), and the behavioral impact of partial fills. No output schema is needed because the description covers the return structure completely.

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

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

Schema description coverage is 100%, but the description adds substantial meaning: it explains the dual-mode parameter interaction (market vs event), the default side logic for baskets (auto from partition sum), and the nuanced interpretation of size_usd (max spend on buys, target proceeds on sells in single-market; settlement notional shares per leg in basket). This goes well beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose: a realizable-vs-theoretical edge check against live order-book depth. It clearly distinguishes single-market and basket modes, and specifies the output elements (top_of_book, vwap_fill_price, slippage_pp, etc.), making it distinct 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?

The description gives explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial basket fills create unhedged positions), providing clear when-to-use and implied when-not-to-use context.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description goes well beyond that by disclosing that compatibility_warning/compatibility_codes can be non-empty even when pairs exist, that unknown metric_type/match_subtype legs are never paired, and that skipped counters reveal how many comparisons were dropped. It also warns that pre-mapped does not mean tradeable, providing critical behavioral context.

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

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

The description is long but highly structured, front-loading purpose and modes before diving into response fields, safety fields, codes, and reliability caveats. It is dense but every section carries important operational warnings; the only minor inefficiency is repeating the topic list that already exists in the schema.

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

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

With no output schema, the description fully explains the response structure, including leg-by-leg prices, top_spreads_pp, compatibility codes, temporal_alignment, and skipped counters. It covers edge cases, warns about unverified pairings, and tells the agent exactly what to look for—making the tool callable correctly without needing additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful nuance: it explains how the two explicit parameters override the topic-mapped side and clarifies that topic is a shortcut that auto-fetches matching events on both venues. This helps the agent understand parameter interplay beyond the schema's individual 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 plainly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific function with a clear resource. It differentiates itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons, and it details the two operating modes, leaving no ambiguity about what the tool does.

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

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

The description clearly explains when to use each mode—topic shortcuts for pre-mapped macros and explicit tickers/slugs for custom pairings—and cautions that most pre-mapped topics are not tradeable and may return compatibility warnings. It does not explicitly name sibling tools as alternatives or give 'when not to use' conditions, but the context is strong enough for an agent to decide correctly.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping to identifier and pairing hints, which enriches 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?

Three sentences, each essential: function, usage, scope/pairing. No redundant 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?

Covers purpose, usage, scoping, and tool relationships. Adequate for a retrieval tool with good annotations and no output schema.

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

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

Schema already fully describes the single parameter. Description restates but adds 'previously saved via remember' context, which is minor.

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

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

Clearly states the tool retrieves a value by key or lists all keys. Differentiates from sibling tools remember and forget by explicitly mentioning pairing.

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?

Specifies when to use (look up stored context to avoid re-derivation) and mentions scoping. Lacks explicit when-not-to-use, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds beyond that: details on returned fields (source, citation_uri, raw payload), the mark_read side effect (flagging events read for subsequent calls), and the existence of an alternative access method. 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 concise at moderate length, front-loading the main purpose. However, the last sentence about the alternative URL could be moved to a note. Overall, it is clear and efficient.

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

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

Given no output schema, the description explains key return fields. It covers all parameters, their effects, and behavioral nuances (mark_read, polling). The alternative access method is an extra bonus. Highly complete.

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

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

Schema coverage is 100%, but the description adds significant context: examples of filter values ('sec_8k'), explanation that 'since' is an ISO timestamp, and the behavioral effect of mark_read. This goes beyond the schema descriptions and aids 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 it pulls fired events from the subscription feed, returning recent alerts with specific fields (source, citation_uri, raw payload). This distinguishes it from sibling tools like list_subscriptions or subscribe, making its purpose unambiguous.

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

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

The description provides context for use (e.g., polling works fine, alternative URL for scripts/dashboards) and explains filtering options (type, since, mark_read). However, it does not explicitly state when not to use this tool versus alternatives, or contrast with siblings.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint false. Description adds significant detail: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return structure. No contradictions.

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

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

Description is thorough but front-loaded with query examples. Each sentence adds value: sources, fallback, return format, alternative. Slightly long but justified by 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?

Given 3 required params, no output schema, and complex multi-source behavior, the description covers all needed aspects: time window usage, source details, failure modes, return format, and sibling differentiation.

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

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

Schema coverage is 100% with good descriptions. Description adds practical guidance for 'since' (examples, recommended values like '30d'), and clarifies 'type' is restricted to company. Exceeds 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?

Description uses explicit verb-resource pairs ('change feed for a company') and multiple example queries. It clearly distinguishes from sibling 'entity_profile', which provides static profile vs. temporal changes.

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

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

Provides explicit use cases ('What's new with X', etc.) and a clear alternative ('Use entity_profile instead for static profile'). Also mentions internal fan-out and fallback behavior.

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

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

Annotations indicate idempotent and non-destructive, but the description adds useful behavior: scoped by identifier, 24-hour retention for anonymous sessions, authentication for persistent memory. Could mention overwrite behavior explicitly, but idempotent hint covers it.

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

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

Concise, front-loaded with purpose, then usage, then behavioral details. No wasted words; every sentence adds value.

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

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

Given simple schema (2 required string params) and no output schema, the description fully covers purpose, usage, behavior, and parameter semantics. Perfectly adequate for an agent.

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

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

Schema coverage is 100%, and description provides meaningful examples for key (e.g., 'subject_property') and value as 'any text'. Adds context beyond the schema's property 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 saves data for later reuse across conversations, using the verb 'Save' and specifying the resource as key-value pairs. It distinguishes from sibling tools like recall and forget.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. Names companion tools recall and forget, providing clear context for 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds significant behavioral nuance beyond annotations: it cascades through multiple lookup endpoints internally, LEI/FIGI enrichment degrades gracefully, and unresolved identifiers are stated under 'unresolved' rather than omitted. It also clarifies that an ISIN resolves to the legal entity via a GLEIF ISIN-to-LEI mapping, which is non-obvious behavior an agent would otherwise not know.

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

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

The description is long but information-dense: every clause adds a distinct fact, from input formats to degradation behavior to the internal cascade. The opening example list front-loads the purpose, and the supported types are clearly organized. The only deduction is that the parenthetical about non-equity instruments is somewhat sprawling and 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 tool with no output schema, the description compensates thoroughly: it states what identifiers each type returns, what unresolved values look like, how enrichment degrades, and what input forms are accepted. The description covers the agent's decision needs for calling this tool and interpreting the result, with no obvious missing piece.

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 both parameters are already explained in the schema. The description adds meaning by enumerating accepted input forms for company (ticker, CIK, name) and drug (brand or generic), and by giving the crucial negative instruction for bond issuer names: pass the issuer exactly as printed, not the full noun phrase. It also clarifies that an ISIN-like input is accepted for company type, which the schema doesn't state. This is meaningful value beyond the schema, though the schema already carries most of the semantic weight.

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

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

The description opens with concrete user-phrase examples and a precise mission: resolve a user-spoken NAME to the canonical/official identifiers other tools require. It names specific identifier types (CIK, ticker, LEI, FIGI, RxCUI) and supported entity kinds (company, drug), and it distinguishes itself from sibling tools like entity_profile and compare_entities by positioning resolve_entity as the ID-lookup step. The verb 'resolve' plus the explicit output objects make the purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use directive. It also explains what to pass for each supported type and warns against passing the full noun phrase for bond issuers, with a concrete negative example. It further explains when non-equity instruments resolve here and how enrichment degrades, which guides an agent to expect success/failure modes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it probes each entity with ai_visibility_check and returns a ranked list, which supplements the annotation context. No contradiction.

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

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

Two clear, front-loaded sentences with no wasted words. Every sentence adds purpose, usage guidance, or return value 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?

Despite no output schema, the description succinctly covers the return structure: 'ranked list with score, confidence, signal density per entity.' This is sufficient for a comparison tool with moderate 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 good parameter descriptions. The description adds meaning beyond schema by noting that the first entity is treated as the 'subject' for narrative and that context disambiguates common names.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities.

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

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

The description explicitly frames the usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It provides clear intent without needing to mention when not to use or alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses partial failure behavior, bundlephobia's 5-30s first measurement delay, and that sources_failed lists timed-out sources. This adds significant value.

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

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

The description is detailed but every sentence adds value. It is front-loaded with the composite purpose and structured to cover key aspects. While somewhat long, it is not overly verbose.

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

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

Given the tool's complexity (multiple sources, partial failures, ecosystem restriction, output details), the description covers all essential aspects. Despite no output schema, it lists return fields in parentheses, making it complete.

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

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

Schema description coverage is 100% (both package and version have descriptions). The description does not add extra meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, and tree-shakability. It distinguishes from other tools by specifying the npm ecosystem limitation and mentioning alternatives like deps.dev:version for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also notes that PyPI/Maven/Cargo/Go fall under deps.dev:version, providing 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 embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), and truncation behavior. Annotations already show readOnly/openWorld/idempotent; description adds rich behavioral details.

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

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

Two sentences pack purpose, usage, behavioral details, and pairing advice. No unnecessary words, structure is front-loaded.

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

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

Given no output schema, description thoroughly explains return values (top-N passages with offsets and scores). Annotations and schema are fully complemented; 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?

All 3 parameters are described in schema (100% coverage) and description adds meaningful context: max length for 'text', valid range and default for 'limit', and examples for 'query'. Adds value beyond schema.

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

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

States clearly 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling tools like ask_pipeworx_grounded by focusing on searching within already-fetched text.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Provides alternative: 'Pairs with ask_pipeworx_grounded' and explains the workflow.

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

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

The description adds substantial behavioral context beyond annotations, including authentication requirements, delivery channel limitations (SMS cap, phone verification), webhook auto-disable after 10 failures, and return of subscription id (and secret for webhook). These details are not in annotations and provide critical transparency.

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

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

The description is structured with bullet points for types and delivery channels, making it scannable. It is front-loaded with the main purpose and return value. Some redundancy with schema descriptions, but overall efficient for the complexity of the tool.

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

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

Given the tool has no output schema and 3 parameters (one with enum, one nested), the description covers prerequisites, supported types with examples, delivery options with constraints, and the return value (subscription id). It is complete enough for an agent to understand how to invoke the tool correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description enriches parameter semantics with type-specific examples (e.g., sec_8k items codes, polymarket_edge topics) and detailed delivery options (phone verification, webhook signing). This adds significant value 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 explicitly states 'Create a proactive monitoring subscription' with a clear verb and resource. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation. The supported types and return value (subscription id) further clarify its purpose.

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

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

The description provides explicit context about when to use the tool: requires a Pipeworx OAuth account, notes that anonymous/BYO cannot persist, and lists supported types with examples. While it doesn't explicitly name alternative tools, it clearly sets expectations and prerequisites, making it easy for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds value by detailing the output structure (category-bucketed examples with tool shapes) and that it draws from the live catalog, without contradicting annotations.

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

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

The description is dense and packs all necessary information into one paragraph, with front-loading of common queries. It lacks structural breaks (e.g., bullet points) but remains efficiently concise.

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

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

Given the tool's simple purpose and rich annotations, the description covers purpose, usage, output, and context fully. Despite no output schema, it gives a clear mental model of what is returned.

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

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

The schema already covers the parameter (100% coverage). The description adds context by listing example topic values and explaining behavior with/without topic, going slightly beyond the schema's description.

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

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

The description clearly states the tool is the onboarding entry point for connecting agents, specifying it returns category-bucketed example questions with tool+argument shapes, and uses a title that matches common queries. It distinguishes itself from siblings like ask_pipeworx or discover_tools.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic versus call with no arguments, providing clear context for usage decisions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns prices in EUR per liter for specific fuel types (E5, E10, diesel), is limited to Germany, and is efficient for refresh. 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?

Extremely concise: two sentences plus an example. Every sentence serves a purpose: first states what it does, second explains usage context, third shows example. Front-loaded with the most critical 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?

Despite no output schema, the description adequately describes return values (prices per fuel type in EUR/liter). It covers input constraints (up to 10 stations, Germany only), usage context (efficient refresh), and provides an example. No gaps remain given the tool's simplicity.

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

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

Schema covers 100% of parameters with descriptions. Description provides a concrete example showing the exact format for station_ids (UUIDs) and optional apiKey. The example adds clarity beyond the schema's property 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?

Clearly states it retrieves bulk current fuel prices for up to 10 German gas stations by station ID. Distinguishes from sibling tools like tankerkoenig_stations_nearby (which gets IDs) and tankerkoenig_station_details (which might get details for one). The phrase 'efficient refresh call' reinforces its specific role in price-watch flows.

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

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

Explicitly states when to use: 'once station ids are known' and for 'price-watch and price-alert flows'. Implies you should first use tankerkoenig_stations_nearby to get IDs. Does not explicitly list alternatives or when not to use, but the context is clear enough for an agent.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds behavioral context by listing the specific data returned (prices in EUR per liter, opening times, brand, etc.) and noting real-time MTS-K data and regional restriction. It could mention behavior for invalid station IDs.

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 brief—two sentences plus an example—without redundancy. It front-loads the purpose and key deliverables. Every sentence adds value, and the example clarifies usage.

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 simple parameter set (2 params, 100% schema coverage), rich annotations, and no output schema, the description is largely complete. It covers what data is returned and context (Germany-only, real-time). Missing error handling details but adequate 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 descriptions for both parameters. The description reinforces the station_id as a UUID and provides an example, but adds no new semantic detail beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves full details for one German gas station by its Tankerkoenig station ID, including specific fields like opening times, prices, brand, address, state, and open status. It distinguishes itself from siblings by focusing on a single station's comprehensive data, unlike 'tankerkoenig_stations_nearby' which lists stations.

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 indicates the tool should be used with a station UUID obtained from 'tankerkoenig_stations_nearby' and restricts usage to Germany. It implicitly guides the workflow, but does not explicitly state when to avoid using this tool in favor of alternatives like 'tankerkoenig_prices'.

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, open-world, idempotent, and non-destructive. The description adds that data is real-time from the MTS-K feed and mentions output fields like open status. It does not disclose potential rate limits, authentication requirements (beyond the optional _apiKey in schema), or any side effects. The description adds some but not extensive behavioral context beyond annotations.

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

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

The description is efficient: four sentences that front-load the core purpose, then provide essential context (geocode first, Germany only), and end with a concrete example. Every sentence adds value; there is 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 moderate complexity (7 parameters, 2 required, enums, no output schema), the description adequately covers the purpose, prerequisite (geocode), geographic scope, and an example. It mentions output fields and open status. It does not describe the exact output structure (though no output schema exists), and it omits information about the _apiKey parameter in the description (though it's in the schema). Overall, it is sufficiently complete for a read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds an example with concrete values and mentions that radius_km has a default of 5 and maximum of 25 (already in schema). It also implies sort constraints ('sort by price requires a single fuel type'), which is already detailed in the schema. The description does not substantially augment 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 clearly states the tool's purpose: finding German gas station fuel prices near a location. It specifies the exact resources (diesel, E5, E10) and output fields (price, brand, address, distance, open status). The purpose is fully distinguished from sibling tools through its focus on nearby stations.

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 important usage context: it mentions that coordinates are required, advises geocoding first, and states data covers only Germany. However, it does not explicitly guide when to use this tool versus alternative tankerkoenig tools like tankerkoenig_prices or tankerkoenig_station_details, nor does it specify any exclusion criteria.

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=false, destructiveHint=false, idempotentHint=true), the description explains that rows are deactivated, not deleted, preserving historical events via recent_alerts. No contradiction with annotations.

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

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

Two concise sentences: first states the core action, then adds ownership constraint and behavioral detail. No wasted words.

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

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

For a simple tool with one required parameter and no output schema, the description sufficiently explains the effect (deactivation) and how to access historical data, meeting completeness needs.

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

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

Schema coverage is 100% and the description does not add information beyond the schema's parameter description ('Subscription id (uuid) returned by subscribe'). Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription'), clearly distinguishing it 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?

Explicitly states ownership enforcement—only the owner can cancel their own subscriptions—providing clear context for when to use. No mention of when not to use, but the constraint is sufficient for typical usage.

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

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

Annotations already indicate read-only, idempotent, open-world behavior, and the description adds valuable non-obvious semantics: `could_not_verify` means the check failed and must not be treated as evidence, while `unsupported` means no source was found. It also discloses the use of verbatim evidence with pipeworx:// citations and the internal routing logic, 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?

The description is fairly long but well-structured: trigger phrases lead, followed by purpose, routing, return format, and important caller caveats labeled with 'IMPORTANT for callers'. Each sentence adds value, though it could be slightly trimmed without losing critical 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 there is no output schema, the description thoroughly explains the return values (verdict, actual value, citation, reasoning) and defines all possible verdict states. It also covers error handling and the difference between `could_not_verify` and `unsupported`, making it fully complete for callers to interpret results correctly.

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

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

The schema already documents both parameters with examples, and coverage is 100%. The description adds meaningful nuance beyond the schema, particularly for `tolerance_pct` (overrides claim-wording default, recommended 1–2 for hallucination detection, default capped at 5), which enriches parameter understanding without being redundant.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with trigger phrases like 'fact check' and 'verify'. It distinguishes itself from sibling research tools by focusing on confirm/refute verdicts and consolidating multiple lookup steps, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing between the SEC EDGAR fast path and the general grounded pipeline. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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