Microsoft Todo

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

The description adds behavioral context beyond annotations, such as default model cost (free), optional Anthropic with BYO key, and return structure. No contradiction with annotations (readOnlyHint, 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?

The description is concise (two sentences), front-loaded with purpose, and each sentence adds essential information without redundancy.

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

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

Despite no output schema, the description fully explains return shape (per-model {score, confidence, signals, raw_response} + combined view) and covers all parameters. Complete for a probe tool with its complexity.

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

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

With 100% schema coverage, the description still adds significant meaning: explains entity as brand/product/topic, models as list with default and option for Anthropic, _apiKey as required for Anthropic, and context as disambiguation. Adds critical cost and usage nuances.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for visibility'), clearly distinguishing it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on scoring visibility across models.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context. It does not explicitly list exclusions or alternatives, but the context is sufficient.

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

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

Annotations already signal read-only, open-world, idempotent, non-destructive behavior. The description goes beyond these by explaining that the tool routes to one of 5,706 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier in one fast call. No contradiction exists, and the added behavior is meaningful.

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 key directive "PREFER OVER WEB SEARCH" and then compactly delivers scope, examples, alternatives, and exceptions. Every sentence contributes to selection or invocation decisions, and the structure is easy to scan.

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

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

For a single-required-parameter tool with rich annotations, the description is complete: it specifies what the tool does, what kinds of questions it handles, examples, return characteristics, fallback/step-up alternatives, and availability across tiers. No output schema is necessary for such a simple question-and-answer interface.

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 covers all six parameters with full descriptions, including the fact that five are aliases for the single required 'question' field. The description adds example queries but does not add meaning beyond the schema, so the baseline of 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 states a clear, specific purpose: route factual questions to the most relevant source tool across thousands of verified sources and return cited structured answers. It explicitly contrasts itself with web search and with siblings like ask_pipeworx_grounded and deep_research, so an agent can confidently select it.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual/current/historical questions, use for trigger phrases like "what is", "look up", "find", "current", etc. It also names alternatives and the conditions for stepping up to ask_pipeworx_grounded or deep_research, and even clarifies how breaking-news is handled.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals live behavioral context: candidate routing improvements can be under test, none is active right now so it currently matches ask_pipeworx, and results are used for comparison/merge decisions. The 'Falls back to nothing' clarification prevents the false assumption that this beta might degrade to a stub.

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

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

Four sentences, front-loaded with the core definition, followed by current state, usage guidance, and a clarifying correction. Details like the 5,706 tools and retirement date are dense but earn their place because they concretely tell the agent how this beta differs from the stable tool.

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

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

Together with the annotations and full schema, the description covers what the tool is, how to invoke it, when to prefer it, current behavior, and what not to expect (no fallback). It references ask_pipeworx for the response shape, and that sibling is directly available in the tool list.

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 documents all six parameters with 100% coverage: question is described as a natural-language request in the description, and all five aliases explicitly say 'Alias for question'. The description adds no parameter-level semantics beyond saying arguments are the same as ask_pipeworx, so the baseline of 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?

Starts by identifying itself as 'Beta version of ask_pipeworx' with 'identical universal router', naming the specific verb (ask), resource (Pipeworx), and scope (5,706 tools). It distinguishes itself from the stable ask_pipeworx by being the experimental routing edge.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. It does not give an explicit exclusion for ask_pipeworx_grounded or state 'use stable ask_pipeworx when you do not want experimental routing', but the condition is clear.

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

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

Annotations already cover read-only/idempotent safety, and the description adds substantial behavioral detail: extracts only from tool result, returns explicit refusal with enumerated reasons, and costs one extra LLM call. These are not present in annotations.

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

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

The description is dense but every sentence earns its place, front-loading the core purpose then covering return shape, refusal reasons, usage guidance, and cost tradeoff. No filler or redundancy.

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

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

For a tool with no output schema, the description supplies the full return contract, refusal semantics, and usage context. Combined with annotations and complete schema coverage, nothing an agent needs 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% with all six parameters being aliases for the same 'question' field, so the schema fully documents them. The description adds no parameter-specific semantics, but none are needed beyond 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?

States a specific purpose: a hallucination-resistant answer mode for high-stakes reads, with grounded extraction and explicit refusal. It distinguishes itself from sibling ask_pipeworx by noting same routing but stricter answer extraction. Clear verb+resource pairing.

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

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

Explicitly says use when an answer will be quoted/cited/acted on and must not invent facts, and prefer ask_pipeworx for casual lookups due to the extra LLM call. Names the alternative and the conditions that select 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?

The description provides extensive behavioral details beyond annotations: market resolution process, classifier list, fan-out examples, response shapes, resolver contract with match confidence, parent event extractor, news fallback mechanisms, safety short-circuits, closed market handling, spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but each section adds value, covering many scenarios. It is front-loaded with the main purpose and structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Could be slightly more concise but appropriate for the complexity.

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

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

Despite no output schema, the description thoroughly explains all response fields, evidence structure, safety mechanisms, edge cases, and caveats. It leaves no important aspect undocumented for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: market parameter accepts slug, URL, or question text with examples; depth parameter explains 'quick' vs 'thorough'; include_raw explains when to use true vs false. Goes well 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 researches Polymarket bets by pulling relevant Pipeworx data, classifying the bet, and returning an evidence packet with market-vs-model comparison. It distinguishes from sibling tools by being specific to Polymarket betting research with fan-out to category-specific data sources.

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

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

The description explicitly states use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It provides numerous examples of fan-out for different bet categories. However, it does not explicitly state when NOT to use this tool or list alternatives, though the context is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses data sources (SEC EDGAR for companies, FAERS etc. for drugs), handling of fiscal years, sorting by primary metric, and output format with citation URIs. No contradictions.

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

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

Description is dense but well-structured, front-loading trigger phrases. Every sentence adds value, though could be slightly more concise.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers purpose, data sources, sorting, output format. No output schema, but return type is described adequately.

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: explains 'values' for company (tickers/CIKs) and drug (names), provides examples, and clarifies max/min constraints. Adds context beyond the schema.

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

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

The description starts with user-trigger phrases like 'Compare X and Y' and 'X vs Y', clearly stating the tool performs side-by-side comparison of 2-5 entities. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Provides example queries but does not explicitly state when to avoid using.

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?

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: account and paid-plan requirements, parallel tool invocation, gap[] reporting with a never-invented guarantee, fetchable citation_uri conditions, semantic excerpting of large records, contradiction[] scans, and latency expectations. No annotation contradiction exists; openWorldHint is consistent with fetching live structured data with fetched_at timestamps.

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 but front-loaded: it opens with the critical ACCOUNT REQUIRED warning and the ask_pipeworx fallback before explaining what the tool does. Some depth-mode details are redundant with the schema, and the long single paragraph could be better broken up, but nearly every sentence carries useful 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 no output schema, the description thoroughly explains the return packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. It also covers edge cases (empty gaps for non-catalog topics), auth conditions, paid tiers, latency, and when to defer to ask_pipeworx. Nothing crucial for calling the tool 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?

The input schema already covers both parameters at 100% coverage, including detailed depth enum semantics and a clear question description. The description mostly restates or reformulates this information with examples and behavioral consequences, rather than adding new parameter-level meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a highly specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources ... in ONE call.' It also names the exact mechanism — decomposition into facets, parallel routing to 5,706 tools, and a findings packet — which clearly separates it from open-web search and from sibling tools like ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, with named examples. It also gives explicit exclusions: single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx, and unsigned-in users must use ask_pipeworx. This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly, without contradicting annotations.

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

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

Well-structured with front-loaded purpose, examples, return details, and usage guidance. Slightly long but each sentence adds value; no waste.

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 6 parameters, no output schema, but description explains returned content (names, descriptions, schemas). Missing security or rate limit info but acceptable.

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

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

Schema coverage is 100% with descriptions for all 6 parameters; description adds natural language context and aliases but doesn't significantly extend meaning.

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

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

The description uses specific verb 'find' and resource 'tools', and lists many domains. It clearly distinguishes itself from sibling tools as the discovery mechanism, not a task-specific 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 states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use and implies when-not-to (already know tool).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), details returned fields, mentions patent API sunset and soft-fail behavior, and explains news fallback. 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 example queries and packs a lot of information into a few sentences. Every sentence adds value, though it is slightly lengthy. Still very efficient.

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

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

Given no output schema, the description thoroughly explains return structure (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with source details and limitations. Parameters are fully covered. The description is complete for a complex multi-source 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% with both parameters described. The description adds usage examples and clarifies that names are not supported, but does not add new semantic constraints beyond what the schema already provides (type enum, value as string). Baseline of 3 is appropriate.

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

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

The description starts with concrete example queries and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from sibling tools like compare_entities and resolve_entity by specifying it's the preferred holistic view and that names require resolve_entity first.

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: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also clearly states when not to use ('names not supported – use resolve_entity first') and what to pass (ticker or CIK).

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive); the description adds useful behavioral detail beyond that: filtering to incomplete tasks, returning a flat list, and listing the exact returned fields. No contradictions with 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, front-loaded with action and scoping, and ending with user-oriented example queries. No filler or redundancy.

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

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

For a one-optional-parameter read-only tool with strong annotations and an explicit output-fields list, this is nearly complete. It could mention default/timezone/inclusive boundary nuances, but nothing essential is missing for correct invocation.

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

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

The input schema fully documents days_ahead (type, default, description), and the description restates it as 'N days', adding little beyond what the schema provides. Baseline 3 applies due to 100% 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?

States a specific verb ('find'), resource ('Microsoft To Do tasks'), and precise selection criteria ('upcoming, incomplete ... due within the next N days'). It also names the output fields, so an agent can distinguish it from list_tasks/get_task and other task tools.

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

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

Provides clear when-to-use context via 'Use to answer...' and scopes to all of the user's to-do lists. It doesn't explicitly name alternatives like list_tasks or state when not to use it, so it stops short of a full 5.

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

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

Descriptive text just says 'Delete', which aligns with annotations (destructiveHint=true). No additional behavioral context 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?

Extremely concise: two sentences that efficiently convey purpose, usage guidance, and sibling context without waste.

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?

All necessary information for a simple deletion tool (one param, no output schema) is present: what it does, when to use, and with what siblings.

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 schema already describes the 'key' parameter. Description adds no extra 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?

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and implicitly distinguishes from sibling tools '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?

Explicit guidance on when to use: context stale, task done, or clearing sensitive data. Also suggests 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?

Annotations already indicate a safe, idempotent read operation. The description adds behavioral context by explaining the fetch-extract-emit process and output format, which is valuable beyond annotations.

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

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

Three sentences front-loading purpose, process, and usage. Every sentence adds value; 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?

For a simple tool with two parameters and no output schema, the description covers purpose, usage, behavior, and output format adequately. No gaps 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%, so the description does not need to add meaning. It mentions only the 'url' parameter, not 'max_links', but the schema already describes both. 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 clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and purpose (AI crawler indexing). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the specific output format.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own projects, and auditing competitors. It does not mention when not to use or alternatives, but the use cases are clear and sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by disclosing the specific data returned (title, status, body, dates, checklist items), which is especially useful given there is no output schema.

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, both purposeful: the first defines the operation and its return payload, the second supplies workflow context. There is no fluff or repetition of schema information.

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

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

For a read-only single-item retrieval tool with strong annotations, the description is complete: it explains what the tool does, what it returns, and when in the workflow to call it. No output schema exists, but the description compensates by enumerating the expected fields.

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% and both parameters have clear descriptions. The tool description restates that identification is by list ID and task ID but adds no new semantic detail beyond the schema. The baseline of 3 is appropriate because the schema already carries the parameter documentation burden.

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

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

The description states a specific verb ('Get'), a precise resource ('a single Microsoft To Do task'), and the identifying inputs (list ID and task ID). It also enumerates the returned fields, making the tool's purpose unmistakable and distinct from list-oriented siblings.

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

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

The description gives explicit workflow guidance: 'Use after list_tasks or find_due_tasks to read a to-do item in full.' This clearly indicates the intended context. It does not explicitly state when not to use this tool or name direct alternatives, but the sequencing is informative enough for an agent to select it 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 already indicate read-only and non-destructive. The description adds return fields and default active-only behavior, but does not mention pagination or rate limits.

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 with no fluff: first states purpose and return fields, second gives usage guidance. Highly efficient.

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

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

For a simple read-only list tool with one optional param and good annotations, the description covers purpose, return structure, and usage guidance completely.

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

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

Schema coverage is 100% with clear parameter description. The description adds context of 'active subscriptions' implying default, but does not significantly enhance meaning beyond schema.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. It distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use and contrasts with subscribe/unsubscribe.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by specifying the signed-in-user scope, the returned fields, and the role of well-known lists. No annotation contradiction exists.

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

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

Two sentences: the first states the operation and output, the second states the intended use case. There is no padding or repetition, and the most important information 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?

This is a simple, zero-parameter read-only list operation. The description covers scope, key output fields, and why an agent would call it. Even without an output schema, an agent has enough to select and invoke the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter semantics because none are needed.

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

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

The description uses a specific verb and resource: 'List the Microsoft To Do task lists for the signed-in user.' It also states what is returned (display names and well-known-list status) and how it relates to scheduling tasks, which clearly distinguishes it from siblings like list_tasks or find_due_tasks.

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 says to use this tool 'to discover a to-do list and its ID before listing tasks or reminders,' giving clear when-to-use context. It stops short of explicitly naming sibling alternatives or saying when not to use it, so it does not earn a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description only needs to add context. It adds useful behavioral detail about the return format (compact task summaries with specific fields) and optional status filtering. No contradiction with annotations.

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

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

Two sentences with no fluff. The primary action is front-loaded, followed by return format and usage context. Every sentence earns its place.

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

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

This is a simple read-only listing tool. The description covers purpose, return shape, and use case; the schema fully documents parameters; annotations cover safety. Nothing critical is missing for an agent to invoke it 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?

All three parameters are fully described in the schema (100% coverage), so the description adds minimal semantics beyond the schema. 'Optionally filter by status' aligns with the status parameter but does not introduce new meaning; the baseline of 3 is appropriate.

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

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

States a specific verb ('List') and resource ('tasks in a Microsoft To Do list'), and clarifies the return shape with compact task summaries. It is clearly distinct from siblings like get_task (single task) but does not explicitly reference them, so it falls short of a 5.

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

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

Provides clear context: 'Use to browse a user's to-do list and see what tasks or reminders it contains.' It does not explicitly mention alternatives or exclusions (e.g., use get_task for a single task), but the intended use case is clear.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), reply semantics, roadmap impact, and the 'don't paste the end-user's prompt' guideline. 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?

Though long, every sentence earns its place: core purpose, categorical triggers, exclusions, token mechanics, rate limits, quota impact, and content guidelines. It is front-loaded with purpose and flows logically 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?

For a tool with 4 params, nested objects, and no output schema, the description is highly complete. It covers category mapping, exclusions, claim_token workflow, return behavior ('returns the status and, once resolved, what actually changed'), rate limits, and content expectations. Nothing significant is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that claim_token is a later-read mechanism ('pass it back later as pipeworx_feedback...') and instructs users to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which adds qualitative guidance for the message 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?

Clearly states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates the feedback categories (bug, feature/data_gap, praise). It also scopes itself to tools served by this Pipeworx connection, which distinguishes it from all sibling research/query tools.

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

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

Provides explicit when-to-use triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: 'ONLY for tools served by this Pipeworx connection... file it with that server instead,' and explains how to identify Pipeworx tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, cached with varying TTL. 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 sentences plus a concise bullet list and caching note. Every part is informative. No redundancy or filler.

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

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

For a simple tool with 1 parameter, full annotations, and no output schema, the description covers purpose, use cases, caching, data source, and privacy. No missing information.

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

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

Schema covers the single parameter with enum and description. Description adds nuance about short vs long windows ('surfaces hot right now' vs 'steady-state demand'), providing extra meaning beyond schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window. It uses specific verbs ('returns') and specifies the resource (Pipeworx trends). Distinguishes from siblings like discover_tools (which lists all tools) and ask_pipeworx variants.

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

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

Three explicit use cases are provided (discovering hot sources, confirming canonical tool, aligning use case). No when-not or alternative tools mentioned, but the context is clear enough.

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

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

The description adds value beyond the annotations (which indicate read-only, idempotent, non-destructive behavior) by detailing the scanning logic, fill check condition, and that it does not execute trades. It does not contradict annotations and transparently discloses constraints like semantic anchor and partition filter.

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

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

The description is detailed but well-structured with section headers and bullet points. It front-loads the core purpose and mode selection. Some sentences are lengthy but not wasteful; overall it efficiently conveys complex logic.

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 thoroughly covers behavior, modes, edge cases (fill check, similarity threshold), and response structure. It is self-contained and leaves little ambiguity for the 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 description coverage is 100%, and the description adds rich context: explains event slug format, acceptance of full URLs, topic mode's cross-event search, semantic anchor, and partition filter. It significantly enhances understanding beyond the schema definitions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) with distinct behaviors and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by its unique arbitrage detection logic.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific event (recommended), and topic for cross-event scanning. It also explains when not to trade based on fill check results. However, it does not directly compare to sibling tools or mention when to choose this tool over 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?

Describes internal model families, segmentation, diagnostics, and caching behavior, adding significant context beyond annotations. No contradiction with readOnlyHint, idempotentHint, or other 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 lengthy and detailed, which aids clarity but lacks conciseness. Front-loading the purpose helps, but the technical breakdown could be more succinct without losing value.

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

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

Despite no output schema, the description fully explains the response structure, diagnostics, and caching, making it contextually complete for the tool's complexity.

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

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

Schema coverage is 100% with decent descriptions, but the tool description adds value by explaining the rationale, defaults, and usage of key parameters like min_liquidity and max_spread_pp as 'tradeable-edge filters'.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using specific verbs and resources. It differentiates from siblings by focusing on model-driven edge detection, not arbitrage or tracking.

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 discovering betting opportunities ('what should I bet on today') but does not explicitly exclude alternatives like polymarket_arbitrage or edge_tracker. No when-not-to-use 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 cover read-only, idempotent, non-destructive. Description adds substantial context: daily snapshots, decay from daily closes, TTL limits, gaps, and response structure. No contradictions.

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

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

Front-loaded with purpose and key concept. Detailed but not excessively verbose given the tool's complexity. Could potentially trim minor details but remains well-structured.

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

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

No output schema exists; description fully explains response fields (tracked[], expired[], snapshot_dates[]) with interpretation. Covers limits, defaults, and edge cases comprehensively.

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. Description adds defaults (days=14, max 30; window='1wk'), clamps, and context (decay uses default slippage). Adds value beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question. It distinguishes from siblings like polymarket_edges (current 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?

Describes use case for assessing edge history vs freshness, and contrasts a fresh wide edge with an old one. Implicitly advises against intraday use but does not explicitly reference sibling tools for alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant behavioral detail: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and describes the behavior in basket mode (theoretical_sum vs realizable_sum, capture_ratio, thin_legs). It also discloses the risk of forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but well-structured with sections for single-market and basket modes, and clear listing of return fields. It is front-loaded with the core purpose. Some use of all-caps for emphasis (e.g., 'REQUIRES', 'USE THIS') is slightly verbose, but every sentence adds valuable information for the agent, earning a high conciseness score.

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

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

Given the complexity of the tool (two modes, multiple return values, no output schema), the description is remarkably complete. It explains all return fields (top_of_book, vwap, slippage, shares_filled, verdict, etc.), covers defaults, and highlights critical warnings about partial fills and forced directional risk. This allows the agent to understand the tool's behavior without needing additional context.

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

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

Schema coverage is 100%, with each parameter already described. The tool description adds mode-specific semantics, such as default values for `side` in single-market vs basket mode, the interpretation of `size_usd` (settlement notional in basket mode), and the requirement for either `market` or `event`. This provides meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes. It also positions itself relative to sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', making its purpose distinct.

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

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

The description provides explicit guidance on when to use: before acting on arb signals or large trades. It specifies the requirement for one of `market` or `event`, explains both modes, and warns about the risk of partial fills converting arb into unhedged directional positions. It also gives default values and usage context for parameters.

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 indicate read-only, idempotent, non-destructive behavior, and the description meaningfully extends this with operational nuance: compatibility_warning and compatibility_codes can both be non-empty, unclassified legs are never paired, skipped_cross_type/subtype counters expose dropped comparisons, and temporal_alignment clarifies resolution periods. This is rich disclosure beyond the annotations.

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

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

The description is front-loaded with the core purpose, then moves through modes, response fields, safety fields, and caveats. It is dense and somewhat lengthy, but every section carries relevant operational detail and is clearly labeled, which justifies the length for a complex tool.

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

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

Because there is no output schema, the description carries the full burden of explaining return behavior. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, skipped counters, temporal_alignment, and low-confidence pairs. An agent has enough context to invoke the tool and interpret its results.

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

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

The input schema already covers 100% of parameters, and the description adds useful context: topic is a pre-mapped shortcut list, while kalshi_event_ticker and polymarket_event_slug enable explicit custom pairings and override the mapped side. The added semantics are helpful but largely reinforce what the schema already communicates.

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 a specific resource: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also communicates scope and the two available modes. However, it does not explicitly differentiate itself from closely related sibling tools like polymarket_arbitrage, so it falls short of a 5.

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

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

The description provides concrete usage guidance: how to use topic shortcuts vs. explicit ticker/slug pairings, and that explicit parameters override the mapped side. It also warns that pre-mapped topics are not inherently tradeable and that compatibility fields should be read. It does not mention when to choose this tool over a sibling alternative, so it stops at 4.

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, destructiveHint. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, account ID) and behavior when key omitted (lists all keys). No contradiction with annotations.

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

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

Two sentences with no waste. The first sentence states core functionality, the second provides usage context and pairing. Information is front-loaded and 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?

With one optional parameter, no output schema, and annotations present, the description covers all necessary context: workflow (save/recall/forget), scoping, and listing behavior. 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% and the schema description already explains the parameter fully. The description restates this information without adding new semantics, meeting the baseline.

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

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

The description clearly states the verb (retrieve/list) and resource (saved values via remember). It distinguishes the tool from siblings (remember, forget) and provides concrete use cases (user's target ticker, address, prior research notes).

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

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

The description explains when to use: to look up context stored earlier without re-deriving it. It implicitly identifies alternatives (remember, forget) but does not explicitly state when not to use this tool.

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

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

The description explains the mark_read parameter's effect (flags events as read so next call shows newer ones), adding context beyond the readOnlyHint annotation. 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 four sentences, concise, and front-loaded with the core purpose. Every sentence adds value without unnecessary details.

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

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

Given the absence of an output schema and required parameters, the description sufficiently describes the output (source, citation_uri, payload) and provides usage context (polling, API alternative). It is complete for a read-only fetch 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?

The description adds context to parameters, e.g., explaining that type filters by subscription type and since is an ISO timestamp. This enriches the schema descriptions, which already had 100% coverage.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It differentiates from sibling tools like list_subscriptions and recall by focusing on retrieving alert events.

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 filtering options (type, since) and mentions that polling works fine, offering an alternative API endpoint. However, it does not explicitly state when not to use this tool or compare it to siblings.

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

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

Beyond annotations, the description details internal fan-out to SEC EDGAR, GDELT/GNews fallback, and USPTO with soft-fail behavior, plus return structure (changes[], total_changes, citation URIs). No annotation contradictions.

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

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

The description is well-structured with examples first, then source details, then parameters, and differentiation. It is slightly verbose for a tool description but every sentence contributes meaningful 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?

Comprehensive for a complex tool with multiple data sources and no output schema: describes return format, source behaviors, rate-limit fallbacks, and window formats. Fully covers what an agent needs to invoke correctly.

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

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

Schema coverage is 100%, but the description adds valuable context: relative date shorthand formats, example ticker/CIK inputs, and recommendation for typical monitoring window ('30d' or '1m').

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

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

The description clearly states the tool returns a change feed for a company over a recent window, using specific verbs like 'What's new with X' and explicitly distinguishes from the sibling tool entity_profile 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 provides explicit when-to-use guidance with example queries and directly tells the agent to use entity_profile for static profiles, offering clear context on tool selection.

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

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

Discloses key-value storage, scoping by identifier, and persistence duration (24h/anonymous vs persistent/authenticated). Annotations support non-destructive, non-readOnly, idempotent 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?

Three concise sentences, front-loaded with purpose. No fluff; every sentence adds essential context.

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

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

Covers all needed context: purpose, when to use, behavior, persistence, and relation to siblings. No gaps given tool 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 already describes both parameters with examples. Description adds value by providing usage conventions for keys and value types.

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?

Clear verb+resource ('Save data') with explicit purpose ('reuse later'). Distinguishes from sibling tools 'recall' and 'forget'.

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

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

States when to use ('when you discover something worth carrying forward') and mentions pairing with recall/forget. Also scoping and persistence details.

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 detailed behaviors: the cross-source identity spine (SEC EDGAR, GLEIF, OpenFIGI), graceful degradation when GLEIF/OpenFIGI is unavailable, and explicit handling of unresolved identifiers via an 'unresolved' field. These are important operational details not captured in the readOnly/idempotent hints.

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

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

The description is long but front-loaded with example queries and a clear purpose. It is organized into logical sections (purpose, supported types, fallback behavior) and every detail serves a purpose, though some technical density could be trimmed without losing 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 tool's complexity (multiple entity types, multiple data sources, no output schema), the description is remarkably complete. It specifies exactly which identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), the source provenance, and the behavior when resolution fails. This fully compensates for the lack of an output schema.

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

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

Although the schema covers 100% of parameters, the description enriches semantics significantly. For 'value', it lists accepted formats (ticker, CIK, ISIN, company name) and gives concrete examples (AAPL, CH0038863350), plus explains the ISIN-to-LEI mapping. For 'type', it clarifies the difference between company and drug outputs, adding meaning beyond the enum labels.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific example queries ('What's the ticker for...', 'find the CIK for...') and distinguishes its function from siblings by emphasizing it is the first step for name-to-ID needs, making it a distinct utility.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, clarifying its efficiency value. However, it does not explicitly name alternatives or state when NOT to use it, so it falls short of a 5.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. 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?

Two sentences plus a parenthetical example. Every sentence adds value: main action, use case, return details. No filler.

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

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

Given no output schema, the description explains return type (ranked list with score, confidence, signal density). It covers what the tool does, but lacks details on pagination or error handling. Still sufficiently complete for its purpose.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that 'entities' are 2-8 items with first entry treated as 'subject', and 'context' disambiguates common names. This provides useful nuance 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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question ('does Claude know about us...'). It does not explicitly list when not to use or alternative tools, but context is clear enough for an AI agent.

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

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

Beyond annotations (readOnly, idempotent), the description discloses that bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timeouts. 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 dense and front-loaded with the main purpose, but it is slightly long. However, every sentence provides useful information, and there is no redundancy. Could be slightly more structured but efficient.

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

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

Given the complexity (composite tool, two services, partial failures, timeout behavior), the description thoroughly covers what the tool does, what it returns, its limitations (npm only), and edge cases. No output schema exists, so the description adequately explains return values.

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

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

Schema already covers both parameters (100% coverage) with descriptions. The tool description adds marginal value by mentioning scoped packages and default version behavior, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's composite nature, combining deps.dev and bundlephobia to answer 'should I add this npm package?' It distinguishes itself from siblings by being npm-specific and aggregating multiple concerns.

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

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

Explicitly says when to use it ('is X safe / popular / small') and when not to (other ecosystems, pointing to deps.dev:version directly). Provides clear guidance on context.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses specific behavioral traits: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also notes that every passage carries an offset for quote verification, which is critical for agent decision-making.

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 and well-structured. It begins with the core functionality in the first sentence, then explains when to use, pairs with a sibling tool, and ends with technical details. Every sentence serves a purpose without unnecessary repetition.

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 fully explains the return structure (passages with offsets and similarity scores) and algorithmic details. It also covers constraints (character limit, window size, truncation behavior) and provides a usage scenario, making it complete for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example queries for the 'query' parameter and explicitly stating the default value for 'limit' (5) and the max character limit for 'text' (200K). These details are practical and enhance understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record' and specifies the input (text and natural-language query) and output (top-N passages with character offsets and similarity scores). It also distinguishes from sibling tools by mentioning how it pairs with ask_pipeworx_grounded.

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

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

Provides explicit guidance on when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also suggests an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations already indicate non-read-only, idempotent, non-destructive behavior. The description adds crucial context: requires OAuth account, BYO/anonymous cannot persist, webhook signing secret returned once, auto-disable after 10 failures, and SMS daily cap. 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 well-structured, front-loading the core purpose and then detailing types and delivery. Some redundancy with schema descriptions is present but acceptable given the complexity. No wasted sentences, though length could be reduced slightly without losing information.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is highly complete: it covers all types, delivery options, prerequisites, and failure behaviors. Minor gap: the idempotentHint annotation suggests repeated calls may be safe, but description doesn't address duplicate subscription behavior.

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

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

The input schema has 100% description coverage, but the tool description adds significant meaning beyond the schema: it explains each enum value for 'type' with real-world examples, provides detailed parameter structures for each type, and elaborates on delivery constraints (phone verification, webhook signing, auto-disable).

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 creates a subscription ('Create a proactive monitoring subscription to a live-data event stream') and returns the subscription ID. It lists supported types and delivery channels, clearly differentiating from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides context on when to use the tool (to create a persistent subscription) and prerequisites (Pipeworx OAuth account, phone verification for SMS). It implicitly distinguishes from one-off queries or listing tools but does not explicitly state when not to use it or mention all 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 confirm the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. This goes beyond the annotations to explain the output nature.

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 a front-loaded purpose statement and clear sentences. It is slightly verbose but each sentence contributes value, especially for an onboarding tool. It could be more concise, but the level of detail is appropriate for the tool's role.

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 fully explains the return format (category-bucketed example questions with tool+argument shapes) and provides a list of categories. Combined with usage guidance and parameter details, it leaves no significant gaps for an agent to understand how to use 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% with a clear description for the topic parameter. The description enriches this by listing the categories (finance, pharma, etc.) in context and explaining that omitting topic gives a cross-category spread. This adds meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose as an onboarding entry point for new agents, using specific verbs like 'returns category-bucketed example questions' and 'learn how to call the meta-tools'. It distinguishes itself from sibling tools by positioning it as the first tool to call when unsure about Pipeworx's capabilities.

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

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

Explicit guidance is given on when to use the tool ('FIRST when you do not yet know what Pipeworx can do') and how to use it (no arguments for full spread, topic argument to focus). However, it does not explicitly state when to avoid it or compare to alternatives, though the context implies its unique role.

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-destructive and idempotent, and the description adds that the row is deactivated (not deleted) and ownership is enforced. This goes beyond annotations, providing useful behavioral 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?

Two sentences that are front-loaded with the action and efficiently convey the purpose, constraint, and effect. No redundant information; each sentence adds essential value.

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

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

For a simple tool with one fully documented parameter and annotations covering safety, the description covers ownership, non-destructive behavior, and historical event availability. It is complete and sufficient for an agent to invoke correctly.

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

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

Schema has 100% coverage with clear description of the 'id' parameter ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter detail beyond the schema, so baseline score 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 clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' (opposite), 'list_subscriptions' (listing), and 'recent_alerts' (historical events), making the purpose unambiguous.

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

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

The description mentions 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear usage context. It does not explicitly state alternatives but implies when not to use (not for others' subscriptions) and references 'recent_alerts' for historical access.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description details the processing pipeline, the list of verdicts, the distinction between 'could_not_verify' and 'unsupported', and the critical warning that 'could_not_verify' must not be treated as evidence. This goes well beyond the structured annotations.

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

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

The description is long but well-structured and front-loaded with examples and usage. Each segment (routing, return values, error warnings) contributes necessary information; while it could be tightened, it is not overly verbose.

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

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

Given the tool's complexity, the description covers the use cases, internal routing, return contract, error semantics, and the performance benefit of replacing multiple sequential calls. It provides ample context for an agent to invoke the tool correctly, even without an output schema.

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

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

The input schema already provides thorough descriptions for both parameters (claim and tolerance_pct) with 100% coverage. The description adds examples of claims but does not add parameter-specific guidance beyond the schema, such as how to set tolerance for strict checking. It only references tolerance implicitly through the verdict 'approximately_correct'.

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 the tool's function: verifying natural-language factual claims against authoritative sources. It includes concrete query phrasings and distinguishes between company-financial and other claims, which differentiates it from sibling tools like ask_pipeworx or search tools.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example phrases for triggering the tool. It explains the two routing paths but does not name specific sibling tools as alternatives or call out when not to use this tool, though the context is clear.

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