Opendosm My

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

Annotations already declare readOnlyHint, idempotentHint, not destructive. The description adds that probing is free for default model and BYO key for Anthropic, with no hidden costs or side effects. No contradictions.

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

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

The description is two sentences plus a brief use-case list, front-loaded with purpose and key details. Every word adds value; no redundancy.

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

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

Given 4 parameters and no output schema, the description covers return structure (per-model fields + combined view) and all param behaviors. No gaps.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value beyond schema: explains default model behavior, API key passthrough, and context disambiguation. No param info missing.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it (0-100). It specifies the verb 'probe' and resource 'LLMs about a business/brand/product/topic', and distinguishes from siblings by mentioning specific models and scoring.

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. It explains default model and API key requirement for Anthropic. However, it does not explicitly say when not to use this tool or compare with siblings like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it fills arguments automatically, routes across many sources, and emits stable pipeworx:// citation URIs. 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 the most important guidance and uses examples effectively. However, the final routing sentence is dense and slightly convoluted with phrases like 'ask_pipeworx_grounded' and '*-news-feeds packs,' which reduces clarity slightly.

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

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

The description covers what the tool does, when to prefer it, which sibling tools to use instead, and what output to expect (structured answer with citations), compensating for the missing output schema. It does not discuss failure behavior, but that is not a critical gap for this read-only routing tool.

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

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

Schema coverage is 100%, so the schema already documents the 'question' parameter and aliases. The description adds many examples and question types, but it does not meaningfully extend the per-parameter semantics beyond what the schema states.

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

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

The description clearly states a specific verb and resource: 'Routes the question to the right one of 5,798 tools across 1517 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also names concrete domains and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') plus examples. It also names alternatives: use ask_pipeworx_grounded for a single grounded answer and deep_research for broad/multi-part questions.

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 convey readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable live-context: candidate routing improvements are enabled only when under test, no candidate is active right now, and current behavior exactly matches ask_pipeworx. This goes beyond the schema and helps the agent set 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 moderately sized and front-loads the core identity as a beta version of ask_pipeworx. The remaining sentences provide necessary usage context and current experimental status. The specific retirement date is arguably extra, but it supports the claim that no candidate is active.

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

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

For a universal router with no output schema, the description supplies enough context: it points to ask_pipeworx for exact usage, states the response shape is identical, and explains the experimental nature. There is no example or elaboration on output, but the reference to ask_pipeworx fills the main gap for tool selection and invocation.

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

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

Schema description coverage is 100%, with each of the six parameters documented as aliases for question. The description only repeats that this tool takes the same arguments as ask_pipeworx, adding no new parameter-level meaning. The baseline of 3 is appropriate because the schema already fully carries the 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 identifies this as the beta version of ask_pipeworx, an identical universal router over 5,798 tools with the same arguments and response shape. It distinguishes itself from ask_pipeworx by being the experimental edge where candidate routing improvements are live-tested.

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 tells the agent to use this tool exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It also clarifies that this is a full working router with no fallback, so the agent understands it can be used standalone.

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

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

The description goes well beyond the annotations by disclosing the refusal behavior, explicit refusal_reason enum, evidence extraction with verbatim quotes, and the extra LLM call cost. It clearly explains that the tool will refuse rather than fabricate when data does not directly answer, which is critical behavioral context for an agent. The description is consistent with the annotations, which already indicate read-only, idempotent, non-destructive 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?

The description is information-dense but well-structured: it opens with the core purpose, then explains the mechanism, output/refusal shape, ideal use cases, and tradeoff versus the sibling tool. Every sentence adds operational value, and the most important differentiator — hallucination resistance — is front-loaded.

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

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

For a tool with a single required parameter, high schema coverage, and rich annotations, the description covers everything an agent needs to invoke it correctly: when to use it, what it returns, how it refuses, and why it differs from the casual alternative. The explicit refusal_reason set and the cost tradeoff make the tool's behavior predictable in edge cases, and no output schema is needed because the return shape is fully described.

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

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

The input schema already covers 100% of parameter semantics, including the primary 'question' parameter and all five aliases, so the description does not need to add parameter-level detail. The description focuses on tool behavior and use cases rather than parameter meanings, which is acceptable given the high schema coverage. Per the baseline for high schema coverage, a 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads, with a specific verb, resource, and behavior. It explicitly distinguishes itself from the sibling ask_pipeworx by noting the same routing but stricter evidence-based extraction, so an agent can differentiate them without opening the schema.

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 states exactly when to use this tool: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, giving concrete examples like financial verdicts and legal claims. It also explicitly says to prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call, providing clear when-to-use versus 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?

The description extensively covers behavioral traits beyond annotations, including resolution contracts, market match confidence (high/medium/low/none), cancellation rules, blocking on low-confidence matches, response shapes, and safety mechanisms. It adds significant value even though annotations already indicate read-only and non-destructive 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?

The description is long but densely packed with useful information. It front-loads the purpose and then covers details in a logical order. However, some sections use all-caps headings (CLASSIFIERS, FAN-OUT EXAMPLES) which slightly disrupt readability but are acceptable given the complexity.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers input formats, behavior for various scenarios (e.g., low-confidence matches, closed markets), response structure (market, analysis, evidence), and safety notes. Nothing critical 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 coverage is 100% with descriptions for all parameters. The description adds further meaning: explaining that 'market' can be a slug, URL, or question text; 'depth' defaults to 'thorough'; and 'include_raw' defaults to false with guidance on when to use true. This supplements the schema well.

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 identifies the resource (Polymarket bet) and the action (research/pull data). This differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges, which have more specific focuses.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear guidance on when to use the tool. However, it does not mention when not to use it or explicitly reference alternative sibling tools, leaving room for improvement.

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

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

Adds valuable context beyond annotations: results sorted by primary metric, citation URIs, fiscal year handling, replaces multiple lookups. No contradiction with annotations.

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

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

Dense single paragraph front-loaded with examples, no fluff. Could be slightly better structured, but effectively conveys all necessary info.

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, description fully explains return data (paired data, citation URIs, sorted by metric). Covers both entity types and data sources. Complete for intended use.

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

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

Schema coverage is 100%, but description adds meaning with examples, explains data sources (SEC, FAERS), and clarifies array constraints. Exceeds baseline 3.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with explicit trigger phrases and distinguishes from siblings like entity_profile. It specifies data sources per entity type.

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 'ALWAYS PREFER over sequential single-pack lookups', giving clear when-to-use guidance. Lacks explicit when-not-to-use beyond schema constraints (max 5 entities).

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 substantially exceeds annotation coverage: it discloses anti-hallucination behavior ('explicit gaps[] for facets the data couldn't answer (never invented)'), citation resolvability guarantees ('present only when the source emits one that resources/read can actually serve'), latency expectations (15-60s, up to ~90s for thorough), semantic excerpting rather than head-truncation, and the paid-tier gate for thorough. Annotations already mark this as read-only/idempotent, and the description adds rich operational context without contradicting 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 a dense, single wall-of-text paragraph with nested parentheticals (e.g., '(free — sign in via GitHub ... depth:"thorough" needs a paid plan)'), which hurts scannability. However, nearly every sentence earns its place: auth gate is front-loaded, timing, gap behavior, citation semantics, and depth differences all carry unique information. The length is justified by the tool's complexity, though formatting could be improved.

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

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

With no output schema present, the description fully carries the burden of explaining return behavior — and it delivers: findings packet composition (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, citation_uri resolvability, timing, auth requirements, and depth semantics. For a high-complexity tool with dangling-chunk async behavior, nothing operationally necessary to call it correctly 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%, so the schema fully documents both `question` and `depth`; the description's added value is modest but real — it flags that thorough is paid (absent from the schema) and reinforces that multi-part questions are expected. These are useful operational supplements, but the schema already carries the descriptive burden, so 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?

The description opens with a precise statement of function: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call' and explicitly disambiguates with 'this is NOT open-web search.' It names the deliverable (findings packet) and gives concrete example questions while distinguishing itself from sibling ask_pipeworx. A specific verb, resource, scope, and sibling differentiation are all present.

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

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

Usage conditions are explicit and actionable: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx,' plus 'Best for broad/multi-part questions over structured data.' The description names the alternative tool, the condition that selects it, and the kind of question this tool is built for, leaving nothing 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 declare readOnlyHint=true and idempotentHint=true, so no contradiction. Description adds valuable behavioral details: returns top-N results with ready-to-call schemas, no second lookup needed. Fully transparent.

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 somewhat lengthy but efficiently front-loaded with core action and usage context. Every sentence adds value; the list of domains is necessary for scope. Minor compression possible, but well-structured overall.

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 the return format (top-N tools with names, descriptions, schemas, examples). Given the tool's simplicity and well-defined input, this is 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 clear descriptions for each parameter. Description reiterates the alias flexibility ('task', 'q', etc.) but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb-resource pair 'Find tools' and clearly outlines the domain coverage (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by being the dedicated tool-discovery tool, not a data retrieval 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?

Explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set' and lists exactly when to use it (browse, search, look up tools). No alternative guidance needed as it's unique in purpose.

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 establish read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral detail: parallel fan-out across sources, soft-fail behavior for the USPTO API sunset, resolved_from/resolved_to handling, empty sections meaning real 'no data' rather than bugs, and private companies returning resolved:false with a notes line. This is exactly the kind of context that lets an agent predict outcomes.

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 densely packed, with intent examples front-loaded before the return payload breakdown. Every segment earns its place given the tool's multi-source complexity, though a slightly tighter structure could reduce reading burden while preserving the same information.

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

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

Because there is no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: it lists cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and the sources_used/sources_failed markers. It also preemptively explains empty sections and failure modes, making the tool fully callable by an agent without external documentation.

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

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

Schema coverage is 100%, so the baseline is already 3. The description adds meaningful semantics beyond the schema by clarifying that 'company' and 'ticker' are interchangeable, that names resolve via SEC EDGAR's company-name match, and that private companies yield resolved:false. This extra color justifies a score above baseline, though the schema already documents the core parameter shapes.

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

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

The description opens with concrete intent examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and calls out the exact scope: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from narrower single-source lookups by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', which separates it from sibling tools with narrower 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 usage guidance: use this tool when the user asks for a holistic view and prefer it over chaining single-pack SEC/XBRL/news lookups. It also explains what happens for private companies, but it does not explicitly name sibling tools or spell out 'do not use for narrow single-fact questions', so the guidance is strong but not fully exhaustive.

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, so no contradiction. Description adds minimal behavioral context beyond deletion, but is consistent.

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

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

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

Given the tool's simplicity (one required param, no output schema), the description covers purpose, usage guidance, and is sufficient with 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 coverage is 100% with a single parameter described. Description only mentions 'by key' without adding detail beyond the schema.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall'.

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 context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall'.

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

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

Adds detail beyond annotations: fetches page, extracts title/description/links, emits standard markdown format. No contradiction with readOnlyHint, idempotentHint, etc.

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 explains what it does and output, second lists use cases. 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?

Given two parameters (one required), no output schema, and rich annotations, the description is complete. Explains process, output format, and typical use cases.

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 is appropriate. Description implies url usage but adds no new semantic detail beyond schema descriptions.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb and resource. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing solely on llms.txt generation.

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

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

Provides explicit use cases (client indexing, personal projects, competitor auditing) but does not mention when not to use or compare with similar sibling tools like 'ai_visibility_check'.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds value by detailing the returned fields and noting that only active subscriptions are returned by default, which is beyond what annotations provide.

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

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

Two sentences front-load the purpose and provide additional context with no wasted words.

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

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

For a simple list tool with one optional boolean parameter and no output schema, the description adequately covers purpose, returned fields, and usage guidance. It is self-contained and 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?

The only parameter (include_inactive) is fully described in the schema. The description implies its effect by saying 'active subscriptions', but adds no additional semantics beyond the schema. Baseline 3 due to high schema coverage.

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

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

Description clearly states 'List the caller's active subscriptions' – a specific verb and resource. It also lists returned fields (id, type, params, etc.), distinguishing it 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?

The description gives explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This provides context for when to use, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context by listing the exact metadata fields and the presence of a sample row, which is beyond the annotations.

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

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

Two sentences: first states what is returned, second gives usage guidance. No superfluous text, perfectly sized.

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

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

Given the simple tool (1 param, no output schema, rich annotations), the description fully covers its purpose, usage, and output without 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% with clear parameter description. The description mentions 'Requires a dataset id' but does not add new semantic meaning beyond the schema.

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

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

The description clearly states it returns metadata including specific fields and a sample row, and distinguishes itself from siblings like opendosm_get_dataset and opendosm_list_datasets by focusing on metadata inspection.

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

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

Explicitly advises using this tool before pulling data or checking freshness, and notes the requirement of a dataset id. Could mention when not to use, but sufficient for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it's keyless and authoritative, and importantly clarifies that date ranges are not supported by 'range' but by sort with limit. 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?

Well-structured with core purpose first, then parameter details, then examples. Every sentence adds value, though slightly lengthy. Could be trimmed slightly but remains clear and informative.

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

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

Given no output schema, description covers all necessary context: how to discover dataset IDs, parameter usage with examples, limitations (date ranges), and list of high-value IDs. Fully adequate for agent invocation.

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

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

With 100% schema coverage, description adds significant value: explains filter syntax (value@column), range syntax (column[start:end]), and sort prefix for descending. Provides examples and boundary details, far beyond schema descriptions.

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

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

The description clearly states it fetches records from Malaysian statistics datasets, specifies keyless authoritative source, and distinguishes from siblings by noting no listing endpoint and recommending opendosm_list_datasets or opendosm_dataset_meta for ID discovery. It also lists high-value dataset IDs.

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 requires dataset ID, provides examples of filter and range syntax, explains that date ranges are not supported by range and suggests using sort and limit instead. Gives clear guidance on when to use sibling tools for ID discovery.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the data's provenance (hand-verified, covering multiple topics) and the absence of a machine endpoint, which clarifies the tool's behavior beyond the annotations.

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

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

Two succinct sentences with no wasted words. Front-loaded key info (list curated datasets) followed by context and optional filter. Excellent structure.

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 listing tool with one optional parameter and no output schema, the description covers purpose, data source, and filter capability adequately. It could mention the return format slightly, but completeness is strong given the tool's simplicity.

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

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

Schema coverage is 100% for the single optional parameter. The description adds example topics (inflation, labour, etc.) and indicates the parameter is a filter, enriching the semantic meaning beyond the schema.

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

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

The description clearly states the tool lists curated, verified datasets from data.gov.my / OpenDOSM, with a specific verb (list) and resource (datasets). It distinguishes itself from siblings by focusing on a unique domain (Malaysian statistics) and mentions the hand-verified nature.

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

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

The description explains that no machine endpoint exists and the tool returns a hand-verified set, providing context for when to use it. It also mentions optional filtering by topic. However, it does not explicitly exclude when not to use or direct to sibling tools like opendosm_get_dataset for specific datasets.

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 only provide false hints, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), the claim_token flow for anonymous filing, that the team reads digests daily, and that it is free and doesn't count against quota. These are meaningful behavioral traits beyond what annotations could 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 longer than typical but every sentence adds necessary operational detail (use cases, exclusions, claim_token, rate limits). It is front-loaded with purpose and flows logically. Slight deduction for the motivational sentence about roadmap signal, which is not essential for invocation.

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 must explain return behavior. It does explain the claim_token return for anonymous filing, but doesn't fully specify the immediate response when an account is present, nor the exact structure of the resolution status read. This is a minor gap, but the overall contextual picture is strong.

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 extra semantics: it explains how to use claim_token to check resolution status later, instructs not to paste end-user prompts, and reinforces which type values map to which use cases. This goes beyond the schema descriptions, justifying 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 opens with a specific verb+resource, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the tool's purpose. It also distinguishes itself from siblings like ask_pipeworx and discover_tools by framing it as a feedback channel for reporting bugs, features, data gaps, or praise.

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

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

Explicit when-to-use guidance is provided for each feedback type (bug, feature/data_gap, praise), plus a clear when-not-to-us: do not report issues with non-Pipeworx MCP servers, and instead file with that server. It also tells agents how to identify Pipeworx tools ('the ones this connection lists'), which is excellent alternative selection guidance.

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

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

Annotations already provide readOnly, openWorld, idempotent, non-destructive hints. Description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This exceeds what annotations convey.

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

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

Extremely concise: one sentence for main output, then bulleted use cases, then technical details. Every sentence adds value. Front-loaded with most important information.

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

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

Given one optional parameter, no output schema, and simple aggregate data, the description fully covers what the tool returns (top tools, packs, call volume), its data source, caching, and PII handling. No gaps.

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

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

Schema has 100% coverage for the single parameter (window with enum). Description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides guidance beyond the enum values.

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, packs, and call volume over recent windows. Includes specific use cases (discovering hot data sources, confirming canonical tool, checking alignment). Distinguishes from siblings like discover_tools and deep_research by focusing on aggregate cross-agent usage.

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

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

Explicitly lists three use cases with context (e.g., 'discovering what data sources are hot for current events'). Does not explicitly name sibling alternatives or when to avoid, but the use cases imply appropriate context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: Jaccard similarity anchor, placeholder filter, partition_check logic, fill check against live CLOB depth, and conditions for null arb signals. 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 with clear sections (modes, semantic anchor, partition filter, response, fill check) but is relatively verbose. It could be slightly more concise without losing critical details, but the density of information is justified given the tool's complexity.

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

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

For a tool with two optional parameters and no output schema, the description is highly complete. It specifies response fields, edge cases (fill check, placeholder filtering, skipped pairs), and references a sibling tool for custom sizing. No gaps in understanding how to use or interpret results.

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

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

Schema description coverage is 100% with meaningful descriptions. The description adds more context: examples of event slugs, explanation of what each mode does (e.g., walking child markets, computing partition_check), and cross-event behavior. This adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, 'event' for a specific market slug, 'topic' for cross-event scanning. It explains why topic mode is beneficial (catches cross-event patterns) and includes a fill check cautioning against trading if the edge is not realizable in the book.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: caching at KV level, edge calculation details (slippage, kelly, liquidity), model families, diagnostic info, and tradeable-edge filters. 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 very detailed and front-loaded with purpose, but it is verbose (over 300 words). It is structured with segments for each model family and output fields, which aids readability, but brevity is sacrificed for completeness.

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

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

Given the tool's complexity (9 parameters, no output schema), the description thoroughly covers the output structure (by_segment, diagnostics, fed_note), edge fields, caching, and knob effects. It leaves no ambiguity about what the tool returns and how to interpret results.

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

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

Schema coverage is 100% with parameter descriptions. The main description adds value by explaining the role of tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in the context of edge models, and how they filter opportunities. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific verb 'scan' and resource 'top Polymarket markets'. It is built for daily discovery, distinguishing it from other tools by its unique output structure (by_segment with three model families).

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

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

The description implies usage for 'what should I bet on today' and mentions edge knobs for filtering, but does not explicitly state when to use this tool vs alternatives like polymarket_arbitrage or polymarket_edge_tracker. No when-not guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral detail: reads from daily snapshots, returns tracked/expired arrays with specific fields, and notes limits like 60-day TTL and decay computed from daily closes.

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

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

The description is dense and well-structured: purpose first, then response format, then limitations. Every sentence provides value without unnecessary words.

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

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

Despite no output schema, the description thoroughly explains the return structure: tracked[], expired[], snapshot_dates[], and their subfields. It also covers limitations and history depth, making the tool's behavior fully understandable.

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 restates parameter defaults and constraints (days: default 14, max 30; window: default 1wk) but does not add new semantics 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 it provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?'. This differentiates it from sibling tools like polymarket_edges (raw edges) and polymarket_arbitrage.

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

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

The description gives usage context by contrasting a fresh wide edge with a 3-week-old one, implying the tool is for assessing historical persistence. It does not explicitly state when not to use it or name alternatives, but the purpose 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?

Discloses detailed behavior including return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains risk of partial basket fills, and notes the dominant loss mode. Annotations already indicate read-only and idempotent; description adds significant context without contradiction.

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

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

The description is fairly long but well-structured and front-loaded with the main purpose. Every sentence serves a purpose given the tool's complexity, though some minor restructuring could improve readability.

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

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

With no output schema, the description thoroughly explains all return fields for both modes, covers edge cases (thin books, partial fills), and provides warnings. It is complete for a complex financial risk-check 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?

While schema provides 100% parameter descriptions, the tool description adds substantial meaning beyond schema, such as the difference in size_usd interpretation between single-market and basket modes, side default behavior, and the clamping range. This enhances usability for the AI agent.

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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two clear modes (single-market and basket), which differentiates 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?

Provides explicit when-to-use guidance: 'REQUIRES one of market or event' and instructs to use before acting on polymarket_arbitrage signals or trades above $500. It also warns against partial basket fills converting arb into unhedged directional positions, the dominant loss mode.

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?

With readOnlyHint, idempotentHint, and destructiveHint already provided, the description adds substantial behavioral context beyond annotations: compatibility_codes semantics, gross-vs-net fee caveats, pairing_unverified being set in either mode, unknown legs never being paired, and the precise meaning of null in temporal_alignment. This is exactly the kind of non-obvious runtime behavior an agent needs to interpret results correctly.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core purpose. Some redundancy exists, such as repeating the pairing_unverified caveat and listing codes in multiple places, but given the tool's complexity the density is largely justified.

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, yet the description thoroughly explains the response structure: leg-by-leg prices, top_spreads_pp, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skip counters. It also covers edge cases like unknown legs and unparseable resolution months, so an agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, but the description adds real meaning on top: topic is a pre-mapped shortcut set, explicit ticker/slug overrides the mapped side, and both modes run the same token-overlap matcher. It also clarifies that the topic list is fixed and enumerates the exact values, making parameter selection safer and more informed.

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

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

The description opens with a specific verb-resource pair: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on Kalshi-vs-Polymarket same-question spreads and by explaining the two operating modes. The purpose is unambiguous and differentiated.

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

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

The description explicitly explains when to use each mode: topic shortcuts for pre-mapped macros and explicit ticker/slug pairings for custom comparisons. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly name sibling tools as alternatives, but the mode-selection guidance is strong 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context about scoping ('Scoped to your identifier - anonymous IP, BYO key hash, or account ID'), which is not present in annotations. No contradictions.

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

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

Three sentences front-loaded with the core purpose. Each sentence adds value: the first describes the action, the second gives usage guidance and examples, the third covers scoping and related tools. No wasted words.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationship to siblings. Annotations handle safety. No gaps remain for the agent to misinterpret.

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 single optional 'key' parameter. Description clarifies that omitting the key lists all saved keys, adding behavioral insight beyond the schema's description. Examples in the schema ('user_research_topic') are supplemented by the description's concrete examples (ticker, address, notes).

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 main action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It includes the verb 'retrieve'/'list' and the resource 'values/keys', and distinguishes from siblings by mentioning pairing with remember and forget.

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

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

Explicitly states when to use the tool: 'Use to look up context the agent stored earlier...' and provides examples of use cases (ticker, address, notes). It also notes the alternative of omitting the key to list all keys and mentions sibling tools (remember, forget) for complementary operations.

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 details beyond annotations: it explains the return structure (source, citation_uri, raw payload), filtering options, and the mark_read side effect. Annotations already indicate safe, idempotent, read-only behavior, and the description complements them without contradiction.

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

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

The description is concise (4 sentences) and well-structured: first sentence states purpose, second details return fields, third explains filters and mark_read, fourth mentions polling and alternative access. No superfluous information.

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

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

Despite lacking an output schema, the description covers return fields, filtering, and side effects. It mentions polling and alternative access. Could be slightly more explicit about the full return structure, but overall adequate for a read-only, idempotent tool with good 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?

All 5 parameters have schema descriptions (100% coverage). The description adds value by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and the purpose of unread_only, enhancing what the schema provides.

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

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

The description clearly states the action ('Pull fired events from your subscription feed') and the resource (recent alerts). It differentiates from siblings like 'list_subscriptions' by focusing on event retrieval rather than subscription management.

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

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

The description provides context for usage, mentioning polling and an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when not to use this tool versus alternatives, though differentiation from siblings is implicit.

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 context beyond annotations, detailing the multi-source fan-out, fallback logic, and date handling. It contradicts none of the annotations (readOnlyHint, idempotentHint, etc.) and provides a clear picture of the tool's 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?

The description is a single paragraph that efficiently packs example queries, source details, and fallback behavior. It is front-loaded with examples and every sentence adds value, though a slightly more structured format could improve readability.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains the output structure (changes[] grouped by source, total_changes, citations) and covers key behaviors. A minor gap is the absence of result limits or pagination details, but overall it is complete enough for an agent.

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

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

Schema coverage is 100% and the description enhances parameter understanding by explaining the 'since' format (ISO or relative shorthand) and providing usage guidance. It adds value beyond the schema, though the schema already does much of the work.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, covering SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling tool 'entity_profile' by explicitly recommending that tool for static profiles.

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

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

The description gives explicit when-to-use cues with example queries like 'What's new with X' and 'latest on Y'. It also specifies when not to use, directing users to 'entity_profile' for static profiles, and explains fallback behavior (GDELT preferred, GNews when rate-limited) and limitations (USPTO soft-fail).

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

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

Annotations are present (idempotentHint=true, destructiveHint=false), and the description adds: scoped by user identifier, authenticated users get persistent memory, anonymous sessions 24-hour retention. It also implies it's a write operation (contradicts no annotation). This goes beyond annotations with specific behavioral detail.

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 (5 sentences) with no wasted words. The main purpose is in the first sentence, followed by usage guidance, and then behavioral details. Each 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?

Given the tool's simplicity (2 params, no output schema, no nested objects), the description covers all needed aspects: purpose, usage, data storage behavior, and lifecycle (pair with recall/forget). No gaps.

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

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

Schema coverage is 100%, so schema already describes both parameters well. The description adds value by providing usage examples for value ('findings, addresses, preferences, notes') and suggesting key naming conventions ('key (e.g., "subject_property", "target_ticker")'). This enhances beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the resource (key-value memory) and action (save/remember). It distinguishes from sibling tools like recall and forget by explicitly mentioning pairing, and from other tools by focusing on cross-session persistence.

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

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

The description gives explicit guidance on when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It pairs with recall and forget, providing clear alternatives and context. No exclusions needed; the examples make scope clear.

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

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

The annotations already signal read-only, idempotent, non-destructive behavior. The description adds rich operational detail beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit 'unresolved' reporting instead of omission, source-labelling of every identifier, ambiguity behavior, and internal cascading through multiple lookup endpoints. 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 extremely dense, with long parentheticals and a run-on first sentence. It is front-loaded with purpose and organized by supported types, but it could be significantly tightened without losing information. It is more exhaustive than 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?

Even without an output schema, the description covers all essential invocation context: accepted types and inputs, supported identifiers per type, ambiguity behavior, unresolved-field semantics, source fallback behavior, and expected cascading lookups. An agent has enough information to decide whether and how to call 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 coverage is 100%, so the baseline is 3, but the description goes well beyond the schema. It adds crucial value-format semantics: pass the entity name only, use the exact issuer string for bonds, avoid trailing security-class words, accept ticker/CIK/ISIN/name for company, and accept brand/generic for drug. This is strong added value, though somewhat redundant with the schema's value description.

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

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

The description opens with concrete user phrasings and states the tool's job: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates supported types and specific identifier outputs (CIK, ticker, LEI, FIGI, RxCUI), which clearly differentiates it from sibling tools that consume IDs, such as entity_profile or compare_entities.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and gives per-type input guidance. It also explains when it deliberately does not choose an identifier (ambiguous FIGI matches return figi_candidates). It never names an alternative tool or an explicit when-not-to-use condition, so it misses the top threshold.

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. Description adds valuable behavioral detail: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. 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?

Two focused sentences plus an illustrative example quote. Every sentence adds value: first states action and method, second provides use case. No redundancy or fluff.

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

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

Despite no output schema, description fully explains return values (ranked list with score, confidence, signal density). Covers entity count range, models array, API key usage. Complete for a 4-param tool with full schema coverage.

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

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

Input schema has 100% coverage with descriptions. Description adds context like 'first entry treated as subject' for entities and 'Optional shared context' for context. Provides sufficient extra meaning beyond schema explanations.

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

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

The description clearly states it compares AI visibility across multiple entities, using ai_visibility_check and ranking by score. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the competitive audit use case.

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 'Useful for competitive AI-marketing audits' and provides a concrete example question. Clearly implies when to use (comparative visibility check) but does not explicitly state when not to use or list alternatives beyond the sibling context.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: fan-out across two services, return format (summary block, per-advisory detail, links, alternative versions), and a practical warning about bundlephobia's first measurement taking 5-30 seconds with sources_failed reporting timeouts. 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 moderately long (4-5 sentences) but every sentence provides unique value: composite action, return content, usage trigger, ecosystem scope, failure mode. It is front-loaded with the main purpose. A slight trim could improve conciseness, but it is well-structured and not wasteful.

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 services, multiple data points) and lack of output schema, the description comprehensively covers return structure (summary block fields, per-advisory detail, links, alternative versions), usage scenario, limitations (NPM only, bundlephobia latency), and error handling (sources_failed). No gaps remain.

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

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

Schema coverage is 100% (both parameters documented). The description adds value by noting scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted. This goes beyond the schema descriptions. Slightly more could be added about the effect of omitting version, but the description is adequate.

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 composite 'should I add this npm package' check with specific resources (deps.dev, bundlephobia), lists what it returns (license, advisories, bundle size, etc.), and distinguishes from siblings by noting NPM ecosystem only and directing other ecosystems to another 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?

Explicit usage guidance is provided: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also clarifies ecosystem scope (NPM only) and directs to alternatives for other package managers. The description mentions graceful degradation for partial failures, helping agents set expectations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and provides character offsets. No contradiction.

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

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

The description is compact and efficiently structured: it starts with the core action, then provides usage guidance, technical details, and constraints. Every sentence adds unique 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?

Despite no output schema, the description explains the return format (top-N passages with character offsets and similarity scores), the embedding/chunking approach, the character cap and truncation behavior. For a complex semantic search tool, this is complete and actionable.

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 contextual examples: for 'text' it reinforces 'max ~200K chars', for 'query' gives natural-language examples ('supply-chain risk'), and for 'limit' specifies range 1-20 and default 5. This adds practical meaning beyond the schema.

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

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

The description clearly states the tool does semantic search inside a fetched record. It specifies the verb ('search within'), the resource ('a fetched record'), and distinguishes it from siblings by mentioning it pairs with ask_pipeworx_grounded and contrasts with fetching whole documents.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and provides an alternative ('fetch with the gateway, ground over the relevant passages'). Also mentions pairing with ask_pipeworx_grounded.

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 non-read-only, open-world hints, idempotent, and non-destructive. The description adds context such as delivery channel limits (SMS 10/day cap), phone verification requirement, and the one-time webhook secret return. These details go beyond what annotations provide.

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

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

The description is relatively long but well-structured, starting with the core purpose followed by prerequisites, types, and delivery details. Every sentence adds necessary detail, though some technical specifics (like webhook HMAC) could be considered excessive for a general description.

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 (3 parameters, nested objects, no output schema), the description covers key aspects: types, parameter formats, delivery options, rate limits, and verification requirements. It does not explain idempotency or what happens on repeated calls, but overall is fairly comprehensive.

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

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

With 100% schema description coverage, the description still adds substantial value by providing concrete examples for each subscription type and detailed explanations for delivery channel parameters (e.g., webhook HMAC signing, SMS cap). This significantly 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 clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It also specifies the return value ('Returns the new subscription id') and lists supported subscription types, making it very clear what the tool does.

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

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

The description mentions a precondition ('Requires a Pipeworx OAuth account') but does not explicitly state when to use this tool vs alternatives like 'list_subscriptions' or 'unsubscribe'. Usage context is implied but not clearly delineated.

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, etc., and the description adds behavioral context: returns category-bucketed, live-catalog examples, supports optional topic filtering, and is safe for initial discovery. No contradictions.

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

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

The description is a single paragraph with front-loaded key purpose. It lists all topics and explains return structure. Slightly verbose but every sentence is informative; could be tightened slightly without loss.

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

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

No output schema, but description fully explains what is returned (category-bucketed example questions with tool+argument shapes). Covers both usage modes (no args vs. topic) and context for when to use. Complete for an onboarding 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% (one parameter with description), but the description lists specific topic values (finance, pharma, etc.) and explains that omitting gives full spread, adding significant meaning beyond the schema's generic description.

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

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

The description clearly states the tool is the onboarding entry point for 'what can I ask Pipeworx?', returns categorized example questions with tool+argument shapes, and distinguishes itself from sibling tools like ask_pipeworx or entity_profile by being the first-use discovery 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context. Does not explicitly state when not to use, but the guidance is sufficient for an AI agent to select this tool appropriately.

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=false and destructiveHint=false. The description adds context that the row is deactivated (not deleted) and historical events remain, which is beyond what annotations disclose.

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

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

Two clear, front-loaded sentences with no wasted words. Every sentence adds 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 the single parameter, no output schema, and full annotations, the description covers ownership, deactivation behavior, and historical availability, making it complete.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. It adds no extra meaning beyond the schema, which already describes the id 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?

The description clearly states the action (Cancel a subscription by id) and the resource (subscription), distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

The description specifies ownership enforcement (only own subscriptions) and the behavioral difference from deletion (deactivated, not deleted). It implies when to use but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantive behavioral detail: it enumerates all six possible verdicts, explains the difference between 'could_not_verify' (check did not happen, includes verification_error) and 'unsupported' (no source covers it), and clarifies that 'could_not_verify' must not be treated as evidence. This meaningfully extends the annotation 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 longer than average but every sentence serves a purpose: trigger phrases, routing logic, verdict list, caller warning, and efficiency claim. It is front-loaded with invocation examples and the core purpose. Slightly verbose due to the detailed error-semantics explanation, but that detail is essential for correct usage.

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

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

Despite no output schema, the description fully specifies return values (verdicts, actual value with citation, reasoning) and the critical error-handling semantic. It covers both covered and uncovered claim types, explains the fallback path, and gives default behavior for tolerance. For a tool with this complexity, the description is remarkably 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%, and the description enriches both parameters: it explains how tolerance_pct overrides the claim's implied tolerance, gives a practical use case ('set 1–2 for hallucination detection'), and states the default behavior. This goes well beyond the schema's basic field descriptions.

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

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

The description opens with concrete trigger phrases and clearly states the tool performs 'natural-language claim verification against authoritative sources.' It distinguishes from siblings by describing the two-tier pipeline (SEC EDGAR fast path vs grounded pipeline) and explicitly notes it 'Replaces 4–6 sequential calls,' making the tool's unique role evident.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic for financial vs other claims. It doesn't name sibling tools as alternatives, but the 'Replaces 4–6 sequential calls' implicitly advises consolidating those steps into this single call, giving clear context if not explicit exclusions.

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