Hilma

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

The description discloses that the tool is read-only, probes multiple LLMs, requires a BYO key for Anthropic with direct payment, and returns structured data. It aligns with annotations (readOnlyHint, idempotentHint, openWorldHint) and adds context like the default model and cost implications.

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

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

The description is two sentences plus a return structure list, front-loading the core action. Every sentence provides essential information without redundancy, making it highly efficient.

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

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

Given the tool's complexity (4 parameters, no output schema, no enums), the description covers purpose, parameters, usage guidelines, and return format. It is self-contained and answers likely agent questions about when and how to use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model, indicating that _apiKey is only needed for anthropic, and clarifying that context helps disambiguate. This justifies a 4.

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

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

The description uses a specific verb ('probe'), specifies the resource ('LLMs'), and defines the output ('score visibility 0-100 per model'). It clearly distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring for businesses/brands.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. However, it does not explicitly state when not to use the tool or suggest alternatives, which would raise the score to 5.

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

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

Beyond annotations, the description reveals the tool is a router that fills arguments, returns stable citation URIs, works on every tier, and is a single fast call. It does not contradict annotations, but omits details about failure modes or behavior when no matching tool exists.

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, with clear opening directive and structured examples and alternatives. Front-loaded with the key 'PREFER OVER WEB SEARCH' message. Some repetition exists (domain lists, trigger phrases) 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?

For a complex routing tool with no output schema, the description adequately explains return format (structured answer with citations), input triggers, and when to use alternatives. It misses explicit error-handling or unsupported-question details, but is largely complete for an aggregator tool.

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

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

Schema coverage is 100% and all six parameters are aliases for the natural-language question. The description adds example queries and usage context but does not expand on parameter constraints or formats beyond what the schema already documents, so baseline 3 is appropriate.

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

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

Description clearly states the tool routes questions to 5,462 tools across 1,419 verified sources and returns structured answers with citations. It explicitly positions itself as preferred over web search for factual queries, and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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 ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...'), when-not-to-use (step up to grounded or deep_research for specific needs), and names alternative tools. Also includes concrete example queries and mentions breaking-news handling.

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

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

Annotations already cover safety (read-only, idempotent). Description adds valuable context: it's a full working router, experimental edge, current state (no active candidate matches stable), and that results are compared for merging. This goes 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?

Four dense sentences that each earn their place: identity, current state, usage directive, and assurance of functionality. No fluff, front-loaded with the core purpose.

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

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

Given the tool is a beta variant of a universal router, the description completely covers purpose, usage, current behavior, and relationship to the stable router. No output schema exists, but the description notes identical response shape, compensating for that gap.

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

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

Input schema covers all 6 parameters with 100% description coverage, including aliases. Description only says 'same arguments,' which adds no new meaning beyond the schema; baseline 3 is appropriate.

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

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

Description clearly states it is a beta universal router with the same 5,462 tools and arguments as ask_pipeworx, and explicitly distinguishes itself from the stable version by describing its experimental routing edge.

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

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

Explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' Also clarifies current behavior when no candidate is active, making the choice between beta and stable explicit.

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 detailed behavioral traits beyond annotations: returns structured evidence and confidence, gives explicit refusal reasons, and only uses tool result content. No contradictions with readOnlyHint/openWorldHint.

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

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

The description is information-dense yet well-structured, front-loading the core purpose and then covering return format, use cases, and tradeoffs efficiently. 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?

Without an output schema, the description fully explains return fields and refusal reasons. It also covers routing, extraction logic, cost tradeoff, and examples of high-stakes use cases, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with all 6 parameters documented as aliases for 'question'. The description adds no parameter-specific value, but the schema fully handles it, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded extraction and refusal behavior.

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

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

Explicit guidance is given: use when answers will be quoted/cited/acted on, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This directly addresses when-to-use and when-not-to.

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

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

The description provides extensive behavioral details beyond annotations. It covers response shapes (market, analysis, evidence), resolver contract (market_match_confidence, alternatives), parent event extraction, news fields with fallback info, safety mechanisms (low-confidence short-circuit, closed markets, wide spread), and resolution-rule risk (cancellation_rule). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 very long (multiple paragraphs) and contains extensive detail. While comprehensive, it could be more concise. However, it is front-loaded with the core purpose and then proceeds to details, which helps scanning. For a complex tool, this length is somewhat justified but still not optimally 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 complexity (3 parameters, no output schema), the description is remarkably complete. It covers response structure, resolver contract, parent event extraction, news fields, error conditions (low-confidence, closed markets, wide spread), and resolution-rule risk. It compensates fully for the lack of output schema.

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

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

Schema coverage is 100% with each parameter described. The description adds value by providing examples for 'market', enum explanation for 'depth' (quick vs thorough), and context for 'include_raw' (when to use true/false). It clarifies usage beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the target (Polymarket bet), action (research), and data source (Pipeworx). The verb 'Research' and resource 'bet' are specific. It differentiates from sibling tools like polymarket_edges or polymarket_arbitrage which are more narrow.

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

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

The description explicitly lists use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It also describes classifiers and fan-out examples, helping agents decide when to use this tool. However, it does not explicitly state when not to use it or name alternatives, though siblings are available.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: the tool makes a single parallel call, handles off-calendar fiscal years correctly, sorts results, and returns citation URIs. No contradiction with annotations, and the description enriches the behavioral profile.

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 seven sentences long, front-loaded with example triggers. Every sentence contributes unique information (data sources, sorting, replacement of sequential lookups). While not extremely concise, it is efficient 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?

With no output schema, the description carries the full burden of explaining return values. It mentions paired data, citation URIs, and sorting by primary metric. It doesn't detail the exact response structure, but for a comparison tool with known domains (company/drug), the provided context is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes beyond by explaining what data each 'type' pulls (company: financial metrics from SEC; drug: FAERS counts) and provides examples for 'values'. This adds meaningful context that helps the agent understand the parameter's impact.

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

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

The description uses specific verbs ('Compare', 'side-by-side comparison') and clearly identifies the tool's resource (companies or drugs) and scope (2-5 entities in one call). It distinguishes from siblings by explicitly stating it replaces sequential single-pack lookups and by listing sibling tools like 'entity_profile'.

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

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

The description provides explicit trigger phrases ('Compare X and Y', 'which is bigger') and a strong preference recommendation ('ALWAYS PREFER over sequential single-pack lookups'). It lacks explicit exclusions (e.g., when more than 5 entities are needed or when other metrics are required), but the guidance is clear and actionable.

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

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

The description discloses behavior well beyond the annotations: account/payment requirements, latency expectations (15-90s), the never-invented gaps[] mechanism, fetchable citation_uri, second-hop iteration, and contradictions[] for standard/thorough. This adds substantial context about what the user should expect, and nothing contradicts the readOnly/openWorld/idempotent hints.

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

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

The description is lengthy but each sentence contributes unique operational or usage detail. It is front-loaded with the critical account requirement and use-case fit, then systematically explains depth, output format, and limitations. Though not heavily structured, it avoids fluff and is reasonably scannable for a complex research 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?

In the absence of an output schema, the description fully specifies the return format (findings packet with evidence, confidence, source, fetched_at, citation) and the gaps[]/contradictions[] fields. It covers latency, account tiers, and alternative tools, making the tool's behavior and expectations complete for an AI agent to decide and execute.

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

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

The input schema already covers both parameters at 100% (question and depth), so the baseline is 3. The description adds value by elaborating on the depth parameter's exact facet counts and hop behavior ('quick=3', 'standard=5... adds a gap-recovery hop', 'thorough=8... adds a full iterative hop'), which enriches the schema's enum descriptions without redundancy.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' and clearly differentiates from siblings by naming ask_pipeworx as the alternative for single lookups and breaking news. It also highlights the tool's decomposition-and-parallel-routing behavior, making its 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?

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also explains depth tiers and when each is appropriate, offering clear exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the key behavioral trait that the tool 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and provides valuable context about the return format and readiness for use. No contradictions with annotations.

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

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

The description is well-structured and front-loaded: it states the main action, then when to use, then examples, then return value. It is slightly verbose but every sentence adds value. Could be slightly shorter, but overall efficient for the complexity.

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

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

Given no output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' It also mentions default limit (20) and max (50). The description provides all necessary context for a discovery tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema: it mentions that query accepts natural language and aliases (task, q, description, search), but those are already documented in the schema. The description adds no new parameter semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains (SEC filings, financials, FDA drugs, etc.), making the scope explicit. It implicitly distinguishes from sibling tools because it is the only discovery tool in the list, and its name 'discover_tools' is self-explanatory.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and lists many use cases. No exclusions or alternatives are needed because this is the only discovery tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context: it fans out across multiple APIs, soft-fails on patents until May 2025, and returns specific fields. No contradiction with annotations; the disclosure is thorough.

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 moderately long but dense with useful information. It is front-loaded with example queries, then details behavior and outputs. Every sentence adds value, though a slightly leaner version could be possible. It avoids redundancy and is well-structured.

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

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

Despite the lack of an output schema, the description fully enumerates return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and explains data sourcing and fallback behavior. For a complex tool, this is remarkably complete and leaves no gaps in understanding.

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

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

Schema coverage is 100% with clear descriptions. The description adds extra meaning by explaining that value can be a ticker or zero-padded CIK, and that names are not supported. This goes beyond the schema, providing actionable context for parameter use.

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

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

The description is highly specific: 'full cross-source profile of a US public company in ONE parallel call.' It lists concrete example queries (e.g., 'Tell me about X', 'research Acme') and enumerates exactly what data sources and fields are returned, leaving no ambiguity about the tool's function. This clearly distinguishes it from sibling tools like resolve_entity or individual lookup tools.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states clearly what NOT to use (names) and directs to resolve_entity as an alternative. This is excellent for correct tool selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and states the action is deletion, but does not explain behavior when key does not exist or any side effects. The additional value is minimal.

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

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

The description is extremely concise (two sentences) with no wasted words. The first sentence states the core purpose, and the second provides usage guidance. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description is complete. It covers purpose, usage scenarios, and sibling relationships, leaving no significant 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 3. The description mentions 'by key' which matches the schema's parameter. No additional semantics or format details are provided beyond the schema.

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

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

The description uses a specific verb and resource: 'Delete a previously stored memory by key'. It clearly distinguishes from sibling tools 'remember' and 'recall' by explicitly pairing with them, implying they serve different purposes.

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

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

The description provides explicit guidance on when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's added detail about fetching the page, extracting title/description/key links, and emitting standard markdown format enriches the behavioral model without contradiction. It could further mention rate-limiting or auth requirements, but the current detail is strong.

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

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

The description is two sentences plus a bulleted list of use cases. It is front-loaded with the primary action and output, every sentence adds value, and there is no extraneous text. Optimal length for an LLM to parse quickly.

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

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

Given the tool's simplicity (2 params, no output schema, no nested objects), the description fully covers input (URL, optional max_links), process (fetch, extract, format), and output (standard llms.txt markdown blob). No missing detail for an AI agent to correctly invoke this tool.

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

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

Schema description coverage is 100% (both url and max_links documented). The description does not add new parameter-specific meaning beyond the schema, but it provides context on what the output contains (title, description, key links). Baseline 3 is appropriate; no extra depth for params is needed since schema is clear.

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

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

The description states a specific verb ('Generate'), a clear resource ('production-ready llms.txt file'), and the scope ('for any URL'). It distinguishes from sibling tools by specifying the exact output format and use cases ('get a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). No sibling tool duplicates this functionality.

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

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

The description explicitly lists three concrete use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to use. It does not explicitly state when not to use or name alternatives, but the sibling list contains no obvious alternative for this specific task, so the guidance 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, idempotentHint, and openWorldHint, so the description's burden is lower. It adds value by detailing the return fields (buyer, dates, CPV codes, flags). There is no contradiction with annotations.

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

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

Two sentences, front-loaded with the core action, followed by return details. Every sentence earns its place; 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?

For a simple lookup tool with 3 optional params, the description covers the operation and return metadata adequately. No output schema exists, so the return description is helpful. Could mention idempotency or that it's a single result, but annotations cover safety.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the param descriptions provide; it merely reiterates that notice_number is an example and that id comes from a search. No extra guidance on format or usage.

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

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

The description clearly states the tool's purpose: 'Look up a single Finnish public procurement notice on Hilma' by either a notice number or index document id. It specifies the resource (Hilma notice), the action (look up), and distinguishes from siblings like hilma_search which is for multiple results.

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

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

The description implies usage (single notice lookup) but does not explicitly state when to use this tool over siblings like hilma_search or hilma_recent. No exclusions or alternative recommendations are provided, leaving it to inference.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral context: defaults (7 days, 20 results), source (Hilma), and optional API key requirement. No contradictions. Could mention rate limits or pagination, but adequate.

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

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

Two sentences: first states purpose, second gives use case and features. No waste, front-loaded, easy to parse. Ideal conciseness.

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 covers source, default behavior, supported views, and comparison to sibling. Could hint at return format (similar to hilma_search) but still quite complete for a list tool with rich annotations.

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

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

Schema has 5 params with 100% description coverage, so baseline is 3. Description goes beyond by explaining defaults (top=20, days=7) and mapping to views (national-only, plans-excluded). Adds value over plain schema.

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

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

The description uses specific verb 'List' and resource 'most recent Finnish public procurement notices from Hilma', and distinguishes from sibling 'hilma_search' by calling itself a convenience wrapper for time-bound queries. It also mentions supported views (national-only, plans-excluded) that are clear from the description.

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 'Convenience wrapper over hilma_search for what new Finnish tenders were published this week style questions', telling when to use this tool (time-bound recency) versus the alternative hilma_search for more complex queries. Also describes supported views.

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 readOnly, openWorld, idempotent, non-destructive. Description adds context: returns newest-first index docs with specific fields, notes Finnish terms match best, and mentions optional API key signup. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph of about 100 words. It front-loads the purpose and usage guidance, then lists filters concisely. No redundancy or unnecessary details.

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

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

Given 13 parameters and no output schema, the description covers input summary and output fields (notice number, buyer, dates, CPV, flags). It also mentions pagination (newest-first) and language preferences. Adequate for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by summarizing key filters (buyer, CPV, date range, etc.) and providing a quick overview that complements the schema. The examples in the schema further aid understanding.

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

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

The description clearly states the tool searches Finnish government procurement notices on Hilma, specifying the resource and verb. It distinguishes itself from web search by explicitly saying 'PREFER OVER WEB SEARCH for Finnish public tenders'.

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

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

It explicitly states when to use this tool over alternatives (prefer over web search) and lists specific use cases like Finnish public tenders, julkiset hankinnat, etc. No need for when-not-to-use as it's a specialized search 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds details on returned fields and default filtering, but annotations carry most burden.

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

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

Two concise sentences, front-loaded with purpose, 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?

Simple tool with one optional parameter, no output schema. Description fully covers what it returns and when to use it.

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

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

Schema coverage is 100% and describes include_inactive. Description mentions 'active subscriptions' implying default filtering, but adds limited 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?

Description states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving clear when-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 are all false, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('Free; doesn't count against your tool-call quota'), and asynchronous processing ('The team reads digests daily'). It also sets content boundaries ('don't paste the end-user's prompt'), adding behavioral context beyond structured fields.

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 150-word paragraph, but every sentence earns its place: scope, use cases, exclusions, content rules, rate limits, and quota. It is front-loaded with the main purpose and does not contain fluff. While longer than ideal, the density of information justifies the length.

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

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

For a 3-parameter feedback tool with no output schema and all false annotations, the description is remarkably complete. It covers what, when, scope, constraints, rate limits, and expected behavior ('digests daily'), leaving no significant ambiguity. The only minor gap is lack of explicit post-submission behavior, but 'digests daily' implies that.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it maps enum values to real triggers (bug = wrong/stale data), advises on message content ('Describe the issue in terms of Pipeworx tools/packs'), and clarifies scope for context ('Not sure? Pipeworx tool names are the ones this connection lists'). This goes beyond simple restating of parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature/data_gap, praise) and is clearly distinct from all sibling tools, none of which are feedback-related. The title and name reinforce the purpose.

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

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

The description gives explicit when-to-use guidance with examples ('Use when a tool returns wrong/stale data...'), and a strong exclusion for tools from other MCP servers ('file it with that server instead'). It also clarifies ambiguity with 'Not sure? Pipeworx tool names are the ones this connection lists.' This is model-level usage guidance with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety is clear. Description adds valuable context: self-aggregating from CF analytics, no PII, and caching durations (5min-1h). These details go beyond annotations and help the agent understand behavior.

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

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

Description is concise (4 sentences) with a clear structure: first sentence states purpose, then bullet-pointed use cases, then data provenance and caching. Every sentence adds value without redundancy.

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

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

No output schema is provided, and the description only vaguely says 'Returns the top tools, top packs, and total call volume' without specifying the response structure (e.g., JSON fields, ordering, or pagination). For a tool with no output schema, the description should compensate with format details to help the agent parse results.

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

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

The sole parameter 'window' has 100% schema description coverage already explaining the enum options. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides extra semantic value beyond the schema.

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

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

Clearly states it returns 'top tools, top packs, and total call volume over a recent window'. The verb 'returns' combined with specific resources (tools, packs) and scope (call volume) makes the purpose unambiguous, and it distinguishes itself from sibling tools by focusing on trending data from Pipeworx calls.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Mentions caching behavior and window selection guidance. However, does not explicitly state when NOT to use this tool or contrast with alternatives, 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 declare readOnlyHint, idempotentHint, openWorldHint as true, indicating safe, non-mutating behavior. The description adds behavioral context: scan modes, fill check, partition filters, semantic anchor, and conditions for null signals. 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 clear sections for each mode. It front-loads key information, though some technical details (e.g., 'slip_low_similarity surfaces the rejected pair count') are slightly 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 complexity of multiple modes and no output schema, the description is thorough. It explains the response structure, fill check behavior, and conditions to avoid trading. All relevant behavioral details are covered.

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

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

Schema descriptions already cover both parameters (100% coverage). The description adds significant nuance: for event mode it details partition checks and date-axis/threshold-axis ordering; for topic mode it explains cross-event matching with Jaccard similarity and missed patterns.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three distinct modes (trending_scan, event, topic) and explains their use cases, differentiating from siblings like polymarket_edges.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Warns about fill check conditions and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds significant detail beyond annotations: caching policy (1h KV), response segmentation, model family logic, edge calculation, and diagnostics for empty segments. No contradiction with annotations.

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

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

The description is comprehensive but somewhat verbose. It effectively front-loads the purpose and uses structured segments (model families, response fields). While every sentence adds value, the length could be reduced slightly for faster parsing.

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

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

Despite no output schema, the description thoroughly explains return structure: by_segment segments, fed_candidates, and _diagnostics. It details per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.) and caching. This is complete for a complex tool with 9 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning for each parameter: explains default values, how filters affect behavior, and context like slippage assumptions. For example, 'min_kelly' is explained as 'half-Kelly fraction... filter out opportunities too small to bet sensibly'.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on disagreement-based opportunities and providing a specific use case ('what should I bet on today').

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 tool as for discovering opportunities without paging hundreds of markets. It explains tradeable-edge knobs and their usage. However, it does not explicitly state when to use alternatives or conditions where this tool is not appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: 60-day snapshot TTL, data gaps when scans don't run, decay computed from daily closes (not intraday), and response structure. This enriches transparency beyond annotations.

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

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

The description is dense and well-structured, front-loading purpose then detailing args and response. It is not overly verbose but every sentence adds value. Slightly long but appropriate for the complexity.

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

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

With no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, enablement start). It compensates well for the lack of a formal output schema. Minor gap: no example values.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context (days default 14 max 30, window snapshot family), but does not add substantial meaning beyond what the schema provides. 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series decay rather than just listing 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 implies use for understanding edge history and decay by saying 'a fresh wide edge and a 3-week-old wide edge are different trades', but it does not explicitly state when to use this vs alternatives like polymarket_edges. No when-not scenarios are given.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint false. The description reinforces these by detailing it 'walks the ladder' and returns verdicts like clean/degraded/cannot_fill, without contradicting annotations. It adds behavioral context about basket mode risks (forced_directional_risk, thin_legs) beyond what annotations express.

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

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

The description is lengthy but efficiently front-loads the core purpose and mode distinction. Every sentence is informative, covering inputs, outputs, and usage guidance. Minor redundancy could be trimmed, but overall structure is logical and dense.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It enumerates all return values (top_of_book, vwap_fill_price, slippage_pp, etc.), explains basket-specific outputs (thin_legs, forced_directional_risk), and justifies usage context with concrete risk scenarios.

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

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

Schema coverage is 100%, but the description adds value by explaining default behaviors (e.g., size_usd default 1000, interpretation for buys vs sells, basket mode auto side detection). It clarifies parameter interactions (market vs event exclusivity) and provides context not in schema fields.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It specifies two modes (single-market and basket) with distinct parameters and returns. This distinguishes it 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 explicitly advises using this tool 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 fills convert arb to unhedged directional position), 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?

Adds extensive behavior details beyond annotations: compatibility warning conditions, temporal alignment, skipped cross types, and real-world rarity of tradeable spreads. No contradiction with annotations.

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

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

Dense with information and well-structured, but slightly verbose. Every sentence adds value, so still highly effective.

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

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

Very complete for a complex tool with no output schema. Covers response structure, safety fields, compatibility edge cases, and temporal alignment.

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?

Though schema coverage is 100%, description adds context on how parameters interact (overrides) and provides examples, enhancing understanding beyond schema descriptions.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket, with two modes and output details. Distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explains when to use topic vs explicit mode, warns that most pre-mapped topics return compatibility warnings, and describes safety fields that indicate when spreads are invalid.

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

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

Annotations provide readOnlyHint, idempotentHint, destructiveHint. The description adds detail about listing behavior when key is omitted and scoping to identifier, supplementing the annotations effectively.

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

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

Three concise sentences that pack essential information. The purpose is front-loaded, and every sentence adds value without redundancy.

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

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

No output schema, but the description covers primary behaviors (retrieve and list). Lacks details on return format or size limits, but given the tool's simplicity, it is adequately complete.

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

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

Schema coverage is 100%, with a clear description for the 'key' parameter. The description adds context by giving examples of typical keys (ticker, address, notes), enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted. It specifies 'retrieve' and 'list' as verbs and the resource as saved memories. It distinguishes itself from 'remember' and 'forget' by naming them.

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

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

Explicitly states when to use ('look up context stored earlier') and provides examples (ticker, address, research notes). It mentions scoping to an identifier and pairs with 'remember' and 'forget' as alternatives.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: each alert carries source, citation_uri, raw payload; mark_read flags events as read. 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 sentences pack purpose, return contents, filtering, mark_read behavior, and alternative endpoint. Front-loaded with core function. 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?

Covers return fields, filtering, mark_read, and alternative access method. With 5 parameters and no output schema, it provides adequate context for an AI agent. Minor gap: does not specify ordering (most recent presumably descending).

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

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

Schema coverage is 100%, but description adds meaning: gives example filter type 'sec_8k', explains ISO timestamp usage, and clarifies mark_read effect. This goes beyond the schema descriptions.

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

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

Clearly states the verb 'Pull' and resource 'events from your subscription feed.' Distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieving the actual alerts. Also notes alternative HTTP endpoint for scripts/dashboards.

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

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

Explicitly mentions that polling works and provides an alternative endpoint for scripts/dashboards, giving context on when to use this tool vs. other methods. Also explains mark_read behavior for incremental reads. Lacks explicit when-not-to-use scenarios.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds: parallel call, fan-out to multiple sources, fallback logic, relative date parsing, and soft-fail for USPTO. 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?

Well-structured: starts with purpose via example queries, then details sources, accepted formats, return structure, and ends with alternative tool. Every sentence adds value, 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 complexity (multi-source, fallback, multiple date formats), description covers all aspects: sources, error handling, input formats, output structure. No output schema, but description sufficiently states return type (changes[] grouped by source, total count, URIs).

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 three parameters have schema descriptions (100% coverage). Description adds: 'type' only supports 'company', 'since' examples and relative formats ('7d', '30d', '3m', '1y'), 'value' accepts ticker or CIK. Adds meaningful usage context.

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

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

The description clearly states the tool retrieves 'what's new' for a company, listing sources (SEC, GDELT/GNews, USPTO) and return format. It distinguishes from sibling entity_profile by contrasting change feed vs static profile.

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

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

Explicit guidance: 'Use entity_profile instead when you want the static profile'. Also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO. Recommends typical 'since' values ('30d' or '1m').

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description adds essential context: key-value storage scoped by agent identifier, with explicit lifetime details (persistent for authenticated, 24 hours for anonymous). No contradictions.

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

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

The description is concise (~100 words), well-structured with a logical flow: purpose, usage, behavioral details, sibling pairing. Every sentence adds value with 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?

For a simple write tool with no output schema, the description adequately covers purpose, usage, and behavioral constraints. It could optionally mention overwrite behavior, but the idempotent hint and 'save' wording make it clear. Slightly incomplete regarding return or error handling, but acceptable.

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 key and value descriptions already well-defined. The description enhances meaning by tying parameters to use-case examples (e.g., 'resolved ticker' for key, 'findings' for value), helping the agent choose appropriate content.

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

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

The description starts with a clear verb+resource: 'Save data the agent will need to reuse later.' It explicitly distinguishes from sibling tools 'recall' and 'forget' by stating they are paired for retrieval and deletion.

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

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

The description specifies when to use: 'Use when you discover something worth carrying forward...' and provides concrete examples (resolved ticker, target address, user preference, research subject). It also clarifies scoping and persistence differences for authenticated vs. anonymous sessions.

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

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

Annotations already cover readOnly and idempotent safety. The description adds valuable behavioral context: returns specific identifiers from SEC EDGAR/RxNorm, accepts multiple input formats, auto-disambiguates, and cascades through several internal endpoints. This goes beyond the annotations and helps the agent understand the tool's operation.

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

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

The description is well-structured and front-loaded with natural-language examples. Each sentence serves a purpose: examples, when-to-use, supported types, and internal behavior. It avoids fluff and is easy to parse despite covering two entity types.

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 lookup tool with no output schema, the description is quite complete. It documents return values for both entity types, accepted input formats, and internal cascading behavior. Minor gaps exist around error cases or disambiguation failures, but these are not critical for typical usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics: it explains what the 'value' parameter means per type (ticker/CIK/name vs. brand/generic), indicates auto-disambiguation, and details the output identifiers associated with each type. This is valuable context beyond the schema.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific verbs and resources ('resolve a user-spoken NAME to the canonical/official identifier'). It distinguishes itself from sibling tools by emphasizing that it produces the IDs other tools require, and lists two concrete entity types (company, drug) with expected outputs.

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 strong when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when not to use this tool, which would elevate it to a 5.

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

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

The description adds behavioral context beyond the annotations, such as treating the first entity as the subject, probing with ai_visibility_check, ranking by score, and returning score, confidence, and signal density. The annotations already indicate read-only, idempotent, and non-destructive nature, 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 concise with four sentences, front-loading the main action, then explaining the process, use case, and output. Every sentence adds value with no fluff.

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

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

Given no output schema, the description describes the return format (ranked list with score, confidence, signal density). It also explains the composite nature (calls ai_visibility_check), the first-entity-as-subject convention, and the optional models parameter with the API key. It is fairly complete, though the number of entities constraint is only in the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the order significance of the entities array (first is subject), the default model and API key requirement for the models parameter, and the disambiguation role of the context parameter, going beyond the schema details.

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: comparing AI visibility of multiple entities side-by-side by probing each with ai_visibility_check and ranking results. It distinguishes itself from its sibling ai_visibility_check by being a batch comparison tool, and explicitly mentions the use case of competitive AI-marketing audits.

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

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

The description indicates when to use this tool: for competitive audits comparing multiple brands. It implies that for single-entity checks, one should use ai_visibility_check. However, it does not explicitly state when not to use it or provide complete alternatives, but the context is clear enough.

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

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

The description adds significant behavioral context beyond the annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description harmonizes with 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 lengthy but every sentence provides necessary information. It uses bold for key terms and is well-structured, though slightly dense. Could be more concise, but the complexity of the tool justifies the length.

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

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

Without an output schema, the description fully explains the return structure (summary block, per-advisory detail, links, alternative versions) and handles edge cases (partial failures, timeout). It is complete for a composite API call tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages are accepted and that version defaults to latest when omitted. It also restricts to NPM ecosystem, which is not in the schema but is crucial for correct usage.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and resources ('npm package', 'deps.dev', 'bundlephobia'), and distinguishes from sibling tools by specifying ecosystem scope and alternatives for other package managers.

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

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

The description explicitly states when to use the tool: when an agent asks about safety, popularity, or cost of an npm package. It also provides exclusions: for PyPI/Maven/Cargo/Go, use deps.dev:version directly. This gives clear guidance on alternatives.

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

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

Annotations already indicate readOnlyHint, etc., but the description adds significant behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows. 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 usage, but includes some technical details (embedding model, window size) that could be considered slightly verbose. Still, 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 no output schema, the description explains return type (top-N passages with character offsets and similarity scores), covers limitations (200K cap, truncation flag), and mentions pairing with sibling tool. It is complete for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains each parameter's purpose (e.g., 'text' is the document to search, 'query' is natural-language query with examples) and clarifies limits (max 200K chars, default limit).

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

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

The description states a specific verb ('search') and resource ('inside a fetched record'), and distinguishes from siblings by contrasting with fetching whole documents and pairing with ask_pipeworx_grounded. It clearly explains what the tool does.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt'), what it saves (context), and mentions an alternative or complementary tool (ask_pipeworx_grounded). Also describes the return value (passages with offsets).

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 SMS cap and webhook auto-disable, but contradicts the idempotentHint=true annotation: creating a subscription is not idempotent (multiple calls create multiple subscriptions). Description does not address idempotency or explain side effects beyond the return 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?

Well-structured with bullet points for types and delivery channels; all sentences add value. Slightly lengthy but justified due to complexity.

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

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

Covers usage, requirements, limitations (SMS cap, account requirement, webhook auto-disable), and return value (subscription id). No output schema, but description compensates sufficiently for agent decision-making.

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

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

Adds significant value beyond the input schema by detailing type-specific parameters (e.g., sec_8k items codes, polymarket topics) and delivery channel constraints (phone verification, webhook signing). Schema coverage is 100% and description enriches every parameter.

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

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

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, recent_alerts by specifying the creation action and supported types.

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 prerequisites (Pipeworx OAuth account, phone verification for SMS) and explains when to use (to subscribe to alerts). Implicitly compares to siblings via context, but lacks explicit when-not-to-use guidance.

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

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

Description adds value beyond annotations by explaining output structure (category-bucketed examples with tool+argument shapes) and behavior (call with no arguments for full spread or with topic to focus). No contradictions with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is comprehensive yet efficient, starting with example intents, then explaining output and usage. Every sentence serves a purpose, and the structure guides the agent from general purpose to specific usage 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?

Despite no output schema, the description fully explains what the tool returns (categories and examples with tool+argument shapes) and when to use it (first time or learning meta-tools). It covers the tool's role in onboarding without missing critical details.

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

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

Schema coverage is 100% with a clear description of the optional topic parameter. The description adds context on how to use the parameter ('focus') and lists possible values, which complements the schema's enumeration. It also explains default behavior (cross-category spread).

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

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

The description clearly states the tool returns category-bucketed example questions for various topics, acting as an onboarding entry point. It specifies the verb (returns) and resource (example questions), and distinguishes from sibling tools by being the first tool to call when unsure about Pipeworx's capabilities.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides example user intents ('what can I ask?') and explains how to focus with the topic parameter.

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 reveals that the row is 'deactivated (not deleted)' and historical events remain available via recent_alerts. This adds value beyond annotations (destructiveHint=false, readOnlyHint=false), fully disclosing the behavioral traits.

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

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

Three concise sentences, each adding essential information: action, constraint, and side effect. No redundant words.

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

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

For a single-parameter write operation with destructiveHint=false, the description fully covers purpose, ownership constraint, and behavioral outcome. No output schema needed as side effect is clear.

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

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

Schema coverage is 100%, and description repeats the schema's parameter description ('Subscription id (uuid) returned by subscribe.'). No additional meaning beyond schema is provided, meeting the baseline.

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

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

Description clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes 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: 'you can only cancel your own subscriptions.' This implicitly tells when not to use it. Could be improved by naming an alternative for canceling others' subscriptions, but still clear.

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

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

Annotations already provide readOnly, openWorld, idempotent, non-destructive hints. Description adds the dual processing paths, verdict types, and return structure (verdict + evidence + reasoning) 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?

Well-structured with examples, path explanations, and return values. Slightly verbose but every sentence adds value; could be trimmed slightly for conciseness.

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, yet description fully covers return values: verdict types, actual value with citation, and reasoning. Also explains fallback handling for unsupported claims, 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 coverage is 100% (both parameters described). Description adds value by explaining default tolerance and use cases for tolerance_pct, and clarifying that claim is natural-language.

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

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

The description starts with natural-language examples and states it performs 'natural-language claim verification against authoritative sources'. It clearly distinguishes from siblings by explaining its unique dual-path processing for financial vs. other claims.

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 the agent needs to check whether something a user said is factually correct' and describes fallback behavior. Lacks explicit 'when not to use' but context is clear.

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