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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds behavioral context beyond that: it routes to one of 5,708 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also notes speed ('one fast call') and default behavior, with no contradiction to annotations.

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

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

The description is long but front-loaded with the most important directive and organized into scope, mechanics, triggers, examples, and step-up guidance. A few phrases ('5,708 tools across 1494 verified sources', 'works on every tier') are promotional but still informative; overall it earns its length.

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

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

For a single-required-parameter tool with no output schema, the description tells an agent everything needed to select and call it: what it does, when to prefer it, how it returns results (structured answer with citation URIs), and when a sibling is better. Nothing crucial is missing.

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

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

Schema coverage is 100% and the schema already documents the question parameter, aliases, and natural-language expectation. The description's examples and trigger phrases add some context, but no parameter-specific semantics beyond what the input schema already provides, 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 names the tool's action ('routes the question', 'returns the structured answer') and scope (SEC filings, FDA data, FRED/BLS, etc.), and explicitly differentiates it from siblings ask_pipeworx_grounded and deep_research. It leaves no doubt that this is the general-purpose factual-query entry point.

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 gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH... START HERE for most questions'), trigger phrases, and concrete examples, and states when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for broad/multi-part... use deep_research'). This is model routing guidance.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond those: candidate routing improvements may be enabled live, none is currently active as of 2026-07-26, so it currently matches ask_pipeworx exactly, and it is a fully working router rather than a stub. This informs the agent that behavior is potentially variable over time and that the tool is genuinely functional. No contradiction with annotations.

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

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

Four sentences, each carrying distinct information: beta status, current candidate state, usage instruction, and fallback clarification. The key fact that it is identical to ask_pipeworx is front-loaded. The 'falls back to nothing' sentence is slightly verbose but serves to prevent a misunderstanding about beta being non-functional, so it 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 tool that is explicitly a beta twin of a known sibling, the description covers the operational state, usage guidance, and the experimental nature without needing to restate the entire ask_pipeworx contract. It does not describe the response shape, but it explicitly points to ask_pipeworx for that. Given no output schema, this is sufficient for an agent to decide and call the tool correctly.

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

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

Schema description coverage is 100%, with the question parameter and its five aliases fully documented in the schema. The description adds no new parameter-level meaning beyond stating that arguments are identical to ask_pipeworx, which is somewhat redundant but consistent. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with 5,708 tools, and explicitly distinguishes it from the stable sibling by framing it as the experimental candidate-testing variant. The verb 'ask' and resource 'router' are implied through the title and confirmed by the description, and the differentiation from ask_pipeworx is exact.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains how results are compared against the stable router. This gives clear context for when to choose this tool. It stops short of explicitly stating 'do not use when you need guaranteed stable behavior,' but the conditional 'when you want the newest routing' makes the intent reasonably clear.

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

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

Annotations already declare readOnly/openWorld/idempotent; description adds the exact success response shape, refusal contract with enumerated refusal_reason values, and guarantee against hallucination. This significantly exceeds annotation coverage.

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

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

Dense and front-loaded: the core value proposition appears first, followed by the routing mechanism, output contract, use cases, and cost tradeoff. No sentence is wasted despite 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?

With no output schema, the description fully specifies the return shape and refusal reasons, names the sibling alternative, quantifies cost, and gives concrete high-stakes examples. Everything needed to invoke and interpret the tool is present.

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 six parameters are documented in the schema with 100% coverage, including the fact that they are aliases for the question. The description does not add parameter-level detail, so the baseline 3 applies.

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

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

States a precise function: hallucination-resistant, grounded answer extraction from Pipeworx tool results, and explicitly contrasts with ask_pipeworx. The verb 'extracts' plus 'using ONLY what the tool result contains' distinguishes it from sibling tools clearly.

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 criteria: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with examples. Also provides an exclusion and alternative preference: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: account/paid-tier requirements, 15-90s latency, gaps[] for unanswered facets with no invention, contradictions[] in standard/thorough, resolvable citation_uri only when fetchable, and semantic excerpting. This goes far beyond the annotations and gives the agent accurate expectations.

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

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

The description is very long and dense, but it is front-loaded with auth requirements and core purpose, then moves through alternatives, hop behavior, citation behavior, and latency in a logical order. Every sentence adds a distinct operational fact, though some details could be combined without loss. It earns a 4 rather than a 5 because of its sheer 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?

There is no output schema, so the description carries the full burden of explaining return values and behavior. It covers the findings packet (verbatim evidence, confidence, source, fetched_at), gaps[], contradictions[], hop field, citation_uri semantics, excerpting behavior, and expected latency. An agent has everything needed to invoke and interpret the result 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 the baseline is 3, but the description adds significant meaning beyond the schema. It unpacks the depth enum into exact facet counts and hop behavior: quick=3 single hop, standard=3 adds gap recovery + contradictions, thorough=6 paid adds iterative follow-up. It also clarifies that question should be natural language and that broad/multi-part questions are acceptable.

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 1494 STRUCTURED data sources' and explicitly differentiates itself from sibling tools by saying 'this is NOT open-web search' and naming ask_pipeworx as the single-lookup alternative. An agent can tell exactly what this tool does and how it differs from closely related 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 gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part questions over structured data, while single lookups and breaking/colloquial current-news topics should go to ask_pipeworx. It also covers the auth-related alternative ('If you are not signed in, use ask_pipeworx instead'). No ambiguity remains.

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?

Beyond the all-false annotations, the description discloses the claim-token return mechanism, the ability to later query resolution status, daily rate limiting, and that filing is free and does not count against quota. It also notes the team's triage cadence and roadmap influence, which is useful behavioral context without contradicting annotations.

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

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

The description is longer than average but every sentence earns its place: scope, exclusions, claim-token flow, rate limits, and quota impact. It is front-loaded with the core purpose and structured into a coherent, readable flow.

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

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

With no output schema, the description adequately covers return behavior via claim_token and later reads. It provides enough context for correct invocation despite the nested context object and zero required parameters, and clarifies relationship to the Pipeworx catalog and other MCP servers.

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 description need not repeat parameter details. It adds valuable usage nuance for claim_token (how to pass it back, no other args) and message (be specific, don't paste end-user prompt), going beyond the bare 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by framing it as a feedback channel for Pipeworx tools, not a data-access tool.

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

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

Provides explicit when-to-use guidance for bug, feature, data_gap, and praise, plus a critical exclusion: do not report issues for tools from other MCP servers. It also gives filing guidance and a fallback for uncertain cases, making alternatives and boundaries unmistakable.

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?

Annotations already mark this as readOnly, idempotent, and non-destructive, so the bar for additional behavioral context is met emphatically. The description discloses response shape, compatibility_warning and compatibility_codes semantics, per-entry flags, skipped_unclassified/low_confidence_pairs, temporal_alignment fields, and skipped_cross_type/subtype counters. It also reveals a non-obvious behavioral trait: pairs can be returned even when compatibility warnings are non-empty, and pre-mapped pairings are not inherently tradeable.

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 it is dense with necessary operational detail and uses clear visual structure (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and uppercase labels to aid scanning. The opening sentence front-loads the core purpose before enumerating details. Some sentences could be tightened, but the length is justified by the tool's complexity.

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

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

Given there is no output schema, the description carries the full burden of explaining return values and edge cases, and it does so thoroughly: leg-by-leg prices, raw probabilities, top_spreads_pp, compatibility fields, skipped-unclassified handling, low-confidence pairs, temporal alignment, and skipped counters. It even warns about the real-world rarity of valid cross-venue spreads and the reliability of pre-mapped pairings. No critical calling or interpretation guidance appears missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema. It explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, enumerates the ten topic values, provides concrete examples for both explicit parameters, and explains the two-parameter interaction (topic vs explicit mode).

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 precise verb-plus-resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes this tool from likely siblings by focusing on cross-venue comparison of equivalent bet shapes, and it explicitly names the two venues and the core output (spread in percent points).

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

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

The description clearly lays out TWO MODES and when each is appropriate: use topic shortcuts for pre-mapped macro topics, or explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also gives important usage caution: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not name alternative sibling tools, but the in-tool mode selection and caveats provide clear context without exclusions.

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

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

Annotations 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?

Goes well beyond annotations by disclosing graceful degradation (GLEIF/OpenFIGI unavailable), explicit `unresolved` field, source labelling, internal cascade of lookups, and citation format for drugs. This provides rich context not visible in structured data.

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

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

The description is lengthy but well-structured with bolded sections and front-loaded examples. Every sentence adds useful detail, though some trimming is possible. It remains focused and organized.

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

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

Given no output schema, the description comprehensively covers expected returns (CIK, ticker, LEI, FIGI, RxCUI), failure behavior, and internal complexity. It fully equips an agent to decide when to use the tool and understand its output.

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

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

Schema already covers 100% of parameters, but the description adds significant value by explaining accepted values with examples (ticker, CIK, ISIN, name) and describing the ISIN-to-LEI mapping nuance. This enhances 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 explicitly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides concrete examples ("What's the ticker for…"), supported types (company, drug), and distinguishes itself from siblings by being the go-to for name-to-ID lookup.

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

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

Offers explicit guidance: "Use FIRST whenever you have a name but need an ID," supported by input format examples and edge-case handling (e.g., ISINs). However, it does not explicitly mention alternatives or when not to use, so it falls short of a 5.

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

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 declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: could_not_verify means the check did not happen (with verification_error) and must not be treated as evidence; unsupported means no source covers it; it returns verbatim evidence with a pipeworx:// citation. This is far beyond what annotations provide and gives critical operational safety.

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 each sentence earns its place: trigger phrases, routing logic, verdict list, and an important caller caveat are all included. It is front-loaded with usage examples and structured into a coherent paragraph. It could be slightly trimmed, but the density is warranted for a complex tool.

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

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

With no output schema, the description fully covers return values: verdict kinds, grounded/structured actual value with citation, reasoning, and the distinction between could_not_verify and unsupported. It also explains the internal paths and how the tool replaces multiple sequential calls. This gives a complete mental model, sufficient for effective invocation and interpretation.

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 guidance on tolerance_pct: recommending 1–2% for hallucination detection and explaining the default (implied by wording, capped at 5). This extra context helps the agent choose and adjust parameters, so a 4 is justified.

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 natural-language claim verification and trigger phrases like 'fact check' and 'confirm or refute,' making the verb/resource explicit. It distinguishes this tool from generic search/research siblings by focusing on issuing a verdict with evidence, and it explains the two-tier pipeline (structured SEC fast path vs grounded pipeline) that is unique to this tool.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies when the structured path applies (company-financial claims) vs the grounded path (all other claims). However, it does not explicitly name alternative tools for non-claim tasks, nor does it provide exclusions, so it falls short of a 5.

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