Nato

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

Annotations already indicate read-only and idempotent behavior. The description adds that it returns per-model data and combined view, discloses the free default model and that Anthropic calls pass through the user's API key. 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?

Three sentences, front-loaded with primary purpose, then details on models and output, then use cases. No redundant information; every sentence adds value.

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

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

For a tool with 4 parameters and no output schema, the description covers the return format per model and combined view, use cases, and model options. Could mention limitations like rate limits or that it's free tier, but overall sufficient.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by explaining default model behavior and the role of '_apiKey' in enabling Anthropic probes, enhancing understanding beyond the schema.

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

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

Clearly states the action 'probe one or more LLMs' and the resource 'business/brand/product/topic', with specific output 'score visibility (0-100) per model'. Distinguishes from sibling tools like 'compare_entities' and 'scan_competitor_ai_presence' by focusing on AI model visibility.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default free model and optional Anthropic with BYO key. Lacks explicit when-not-to-use or alternatives but offers clear context for appropriate usage.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail by explaining that it routes to one of 5,767 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs—information not available from annotations alone.

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

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

The description is front-loaded with the most important routing guidance, then explains behavior, gives trigger phrases, and finishes with concrete examples. It is long but each sentence carries actionable information without 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 broad routing tool with a single required natural-language parameter and no output schema, the description provides enough context: what it does, when to use it, how it behaves, and what the response shape is (structured answer with citations). No critical selection or invocation detail appears missing.

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

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

The input schema already documents all six parameters as aliases for the natural-language question, with 100% coverage. The description adds value by supplying concrete example queries across domains and reinforcing that the question is a free-form natural language request, which helps an agent formulate appropriate input.

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 as a question router that selects from thousands of tools and returns structured answers with citations, which strongly conveys its purpose. However, it does not differentiate itself from the similarly named siblings ask_pipeworx_beta and ask_pipeworx_grounded, so it stops short of full sibling differentiation.

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

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

The description explicitly instructs agents to prefer this tool over web search for factual, authoritative, or current-data questions, even when web search could answer them. It provides concrete trigger phrases and examples, making when-to-use guidance unambiguous.

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 explaining the experimental live-routing behavior, the possibility of candidates being under test, the current state (no active candidate), and the fallback safety that it remains a full working router. This gives an agent realistic expectations without contradicting readOnlyHint or idempotentHint.

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

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

The description is information-dense and front-loaded with purpose, then experimental status, then current behavior. It could be tightened slightly, for example 'Falls back to nothing — this IS a full working router' is somewhat redundant, but every sentence otherwise contributes 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?

For a routing tool with no output schema, the description fully covers what the agent needs: current behavior, parity with ask_pipeworx, experimental nature, and the comparison mechanism. The lack of an output schema is mitigated by the explicit 'same response shape' statement referencing the stable sibling.

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

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

Schema description coverage is 100%, so the schema already documents the alias parameters thoroughly. The description only states 'same arguments' and adds no new semantic detail about the question parameter or its aliases, which matches the baseline expectation of 3.

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

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

The description clearly identifies the tool as a beta fork of ask_pipeworx, stating it is the 'same universal router' with 'same 5,767 tools, same arguments, same response shape.' This makes the function's purpose unambiguous and distinguishes it from the stable ask_pipeworx and other 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?

It explicitly says to use it 'exactly like ask_pipeworx' and 'when you want the newest routing,' and it references the stable router for comparison. However, it stops short of giving an explicit exclusion such as 'use ask_pipeworx when you need stable production behavior,' leaving some of the when-not-to-use decision to inference.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context: extraction is limited to tool results, refusal reasons are enumerated (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and it discloses the extra LLM call cost. 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?

Three dense sentences cover purpose, routing, output format, refusal behavior, use cases, exclusions, and cost. Every clause adds information and the primary purpose is front-loaded. 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?

Despite no output schema, the description fully documents the success and refusal return shapes, the routing mechanism, the use context, and the tradeoff versus ask_pipeworx. An agent has enough to decide whether to call it and what to expect in response.

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 properties documented as aliases for 'question'. The description explains the routing/processing but does not add meaning about the question parameter beyond what the schema already provides. Baseline 3 applies because the schema fully carries parameter documentation.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results, returning evidence and confidence. It distinguishes itself from the sibling ask_pipeworx by explicitly naming the alternative and the added grounding/evidence behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives a clear fallback: 'prefer ask_pipeworx for casual lookups.'

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

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

The description discloses extensive behavioral traits beyond annotations: it explains the resolution process, fan-out logic, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits, wide-spread warnings, and cancellation rule parsing. This far exceeds what annotations (readOnlyHint, openWorldHint, idempotentHint) provide.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). It is front-loaded with the core purpose. While comprehensive, every sentence adds value; the length is justified given the tool's complexity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers inputs, processing, all output fields, edge cases (low confidence, closed markets, wide spreads), safety mechanisms, and resolution rules. No important aspect is omitted.

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 three parameters with descriptions (100% coverage), so baseline is 3. The tool description adds context: depth is explained as 'quick = 2-3 evidence sources, thorough = full fan-out', and include_raw explains summarized vs full payloads. Market parameter details are reinforced.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). It distinguishes itself from sibling tools by emphasizing aggregation of multiple data sources in a single call.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed contextual guidance, including when to inspect confidence levels and when the tool may block (low-confidence match, closed markets). This helps the agent choose between this and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and efficiently conveys key information. While slightly lengthy, every sentence adds value, with no wasted words. A minor reduction in length could still maintain clarity.

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 (2 parameters, no output schema), the description fully covers what the tool does, its inputs, behavior, and output format (paired data + citation URIs). It is complete for effective use.

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

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

Schema coverage is 100% but the description adds significant meaning: it explains what each type pulls (company: specific financial metrics; drug: specific counts) and how results are sorted. This goes well beyond the schema's brief 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 uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resource (2-5 companies or drugs) and action. It distinguishes from siblings by explicitly stating preference over sequential single-pack lookups, which differentiates from tools like entity_profile.

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

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

The description explicitly states when to use this tool ('for comparing entities', 'ALWAYS PREFER') and provides context on entity types and data sources. It implies when not to use (for single lookups) through the sibling context and by emphasizing efficiency gains.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: it explains parallel decomposition across 5,767 tools, the findings packet structure, gaps[] never-invented behavior, hop/citation_uri semantics, contradictions[] for standard/thorough, semantic excerpting, and expected latency ranges (15-60s, thorough up to ~90s). No contradiction with annotations; the openWorldHint is reinforced by the 'never invented' disclosure.

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 the account requirement, then the core value proposition, then usage guidance, then depth semantics, then performance expectations. It is dense but not bloated; nearly every sentence earns its place. Loses one point for density: the description is long and packs multiple distinct topics (auth, research mechanics, output format, depth semantics, latency) into one paragraph, which could be structurally clearer for an agent scanning quickly.

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

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

Complete despite having no output schema: the description discloses return format (findings packet with verbatim evidence + confidence + source + fetched_at + citation), gaps[] behavior, contradictions[] availability, hop field, citation_uri resolution semantics, and latency. For a tool with 2 params, no nested objects, and no output schema, the agent has everything needed to select and 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?

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning beyond the schema. It explains what depth levels actually do at a behavioral level: standard adds gap-recovery hop + contradictions scan; thorough is paid, adds full iterative hop, chases leads, plus contradictions scan. It also explains the question parameter's intent ('Broad/multi-part is fine — decomposition is the point'), which goes beyond the schema's 'natural language' note.

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+resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call'. It clearly distinguishes itself from open-web search and names ask_pipeworx as a sibling alternative. The tool's purpose is unmistakable even amid many sibling 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?

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data'. It also gives a clear when-not-to-use: 'For a single lookup use ask_pipeworx instead' and for breaking/current-news topics prefer ask_pipeworx. It names alternatives and conditions, so an agent can route correctly without inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint ensuring safe usage. The description adds valuable behavioral context: returns top-N most relevant tools with full input schemas and curated examples, ready to call directly. 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?

Single paragraph with efficient sentences. Front-loaded with the primary action. Could be slightly more structured, but no fluff 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 discovery tool with no output schema, the description thoroughly explains what it returns (tool names, descriptions, full input schemas with examples) and that results are callable immediately. It also mentions the top-N relevance ranking. No gaps.

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

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

All 6 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds example query phrases (e.g., 'look up FDA drug approvals') and lists many domains, which provides helpful context beyond the schema but does not add meaning to individual parameters.

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 specifies the exact action ('Find tools by describing the data or task') and the resource (tools available). It lists concrete example domains (SEC filings, financials, etc.), making it clear and highly distinguishable from sibling tools, none of which are general discovery tools.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context for when to use it. Lacks explicit 'when not to use' instructions, but the guidance is strong.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description goes beyond them by disclosing fan-out behavior, soft-fail conditions (USPTO sunset), expected empty results (FDA products for small-molecule/generic-only companies), fallback chains (GDELT to GNews), resolved/unresolved results, and the fact that empty sections are not bugs. This is rich behavioral context well beyond annotations.

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

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

The description is information-dense and front-loaded with examples, but it is very long and packed with a large list of outputs and edge-case disclaimers. Every sentence adds useful info, yet the sheer length makes it harder to parse quickly; some detail (resolved_from/resolved_to, specific source lists) could be tightened while preserving value.

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

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

Despite having no output schema, the description enumerates all key return fields with clarifications (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed). It also documents the private-company resolved:false behavior, which is a common edge case. The description is sufficient for an agent to call and interpret the result 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%, so the schema already documents both parameters. The description adds real meaning by showing that `type` accepts 'company' or 'ticker' interchangeably and that `value` accepts a ticker, zero-padded CIK, or company name — directly reinforcing and expanding on schema semantics. With full schema coverage, this is above baseline because the description clarifies the interchangeability and name resolution behavior.

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

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

The description opens with concrete invocation examples ('Tell me about X' / 'research Acme') and immediately states the core capability: a full cross-source profile of a US public company in one parallel call. It strongly differentiates from siblings by explicitly saying ALWAYS PREFER over chaining single-pack lookups, and the list of data sources makes the purpose unmistakable.

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

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

The description explicitly instructs when to use this tool ('ALWAYS PREFER...when the user asks for a holistic view') and contrasts it with the alternative approach of chaining single-source SEC/XBRL/news lookups. It also clarifies input formats (ticker, CIK, or company name based on schema descriptions) and explains the failure mode for private companies, which is clear usage guidance.

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

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

The description aligns with annotations (destructiveHint=true, readOnlyHint=false) by confirming deletion. While it does not add new behavioral details beyond annotations, it is consistent and sufficient for a simple operation.

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

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

Two sentences with no unnecessary words. The action and use cases are front-loaded, making it efficient for an agent to parse.

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 one parameter, no output schema, and clear annotations, the description covers purpose, usage, and how it relates to sibling tools. It is complete for this complexity.

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

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

Schema coverage is 100%, and the parameter 'key' is already described in the schema as 'Memory key to delete'. The description adds no additional meaning beyond that.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and names the resource ('memory'). It distinguishes itself from siblings by mentioning 'remember' and 'recall' as paired tools.

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

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

Explicitly provides three use cases: stale context, task completion, and clearing sensitive data. Also notes pairing with 'remember' and 'recall', giving clear guidance on when 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only operation. The description adds context by explaining the fetches and extraction process, aligning with annotations. It does not contradict them and provides useful behavioral details 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 consists of three concise sentences: purpose, process, and use cases. No extraneous words, and it is front-loaded with the key action. Every sentence adds value.

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

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

Given the tool has only 2 parameters, no output schema, and simple behavior (read-only file generation), the description fully covers the necessary context, including output format ('single text blob') and placement guidance. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters well-described. The description adds no new meaning beyond the schema's existing descriptions (e.g., url and max_links already include defaults and limits). Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the target AI crawlers. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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

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

The description provides explicit use cases (client site indexing, personal projects, auditing competitors) and implies when to use it. It lacks explicit when-not-to-use or alternative tools, but the context is clear and sufficient for the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; description adds concrete return field details, adding value 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?

Two sentences, front-loaded with the core action and data, no wasted words.

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

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

Despite no output schema, the description lists the return fields and explains usage, providing sufficient completeness for a read-only listing 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%; the description does not add extra meaning beyond what the schema provides for the include_inactive parameter, so baseline 3 is appropriate.

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

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

The description states it lists the caller's active subscriptions and specifies the return fields, clearly distinguishing it from siblings like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds valuable context: 'Keyless, offline' meaning no authentication and local execution, which goes beyond annotations.

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

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

The description is concise: two sentences that immediately state the purpose and key usage details, with no unnecessary 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 one-parameter tool with rich annotations and no output schema, the description sufficiently covers purpose, input format, and key behavioral traits (offline, keyless). The return value is obvious from the tool name.

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

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

Schema description coverage is 100% with examples. The description adds format rules not fully covered in the schema description (e.g., word separators), providing extra clarity 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 'Decode Morse code back to text', using a specific verb and resource. It distinguishes from the sibling tool 'morse_encode' which performs the reverse operation.

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

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

The description specifies input format details (letters separated by spaces, words by '/' or double space) and notes 'Keyless, offline'. However, it does not explicitly state when to use this tool versus alternatives like 'morse_encode'.

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, etc. Description adds 'keyless, offline' but no further behavioral traits. 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?

Single sentence with 12 words, front-loaded with action and output format. No unnecessary content.

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

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

For a simple tool with one parameter and no output schema, the description fully explains purpose and output format. Complete.

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

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

Schema coverage is 100% for the single parameter, and description does not add meaning beyond the schema's property description.

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

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

The description explicitly states 'Encode text to Morse code' with specific formatting details, and distinguishes from sibling tools like morse_decode.

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?

No explicit when-to-use guidance; however, the 'Keyless, offline' qualifier gives context on requirements. Lacks comparison to alternatives like spell_nato.

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

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

Annotations only indicate non-read-only, non-idempotent behavior, so the description carries the transparency burden. It adds substantial behavioral details: rate-limited to 5 per identifier per day, free and not counting against quota, returns a claim_token when filed without an account, and signals that the team reads digests daily. This goes well beyond the annotation flags.

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

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

The description is longer than average, but every sentence earns its place by adding a rule, constraint, or workflow step. It is front-loaded with the core purpose and then layers usage scope, token mechanics, and rate limits without redundancy.

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

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

Given there is no output schema, the description adequately explains return behavior (claim_token, later status check) and covers workflow, exclusions, rate limits, and team response. It is complete for a feedback tool with 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?

Although the schema already describes all parameters at 100% coverage, the description enriches meaning by explaining how to use them together: it tells users to describe issues in terms of Pipeworx tools/packs (not end-user prompts) and details the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This adds practical guidance that the schema alone lacks.

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

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

The description opens with a clear verb+resource ('Tell the Pipeworx team') and specifies the exact purpose: reporting broken/missing/existing functionality. It distinguishes itself from sibling tools like ask_pipeworx (asking questions) and discover_tools (exploring capabilities) by centering on tool feedback.

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 enumerates when to use the tool (bug, feature/data_gap, praise) and provides a strong exclusion: only for tools served by this Pipeworx connection, with a clear alternative ('file it with that server instead'). It also explains the claim_token follow-up workflow, giving an actionable after-use path.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds valuable behavioral details: it's self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. 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 three sentences long, front-loaded with the core purpose, and every sentence adds value. No redundant or vague language.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers the key return elements (top tools, top packs, total call volume), caching, and use cases. It could mention the exact format of the response, but the description is sufficient for the agent to understand what it will get.

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

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

The schema coverage is 100% with one parameter (window) having enums and description. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It uses a specific verb ('returns') and resource ('trending data on Pipeworx'), distinguishing it clearly from sibling tools like discover_tools or 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?

Description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment) and mentions caching behavior. While it doesn't explicitly say when not to use it, the use cases are specific enough to guide the agent. No direct sibling comparison is needed because the tool's purpose is unique.

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 (readOnlyHint: true, idempotentHint: true, destructiveHint: false) clearly indicate no side effects. The description goes far beyond annotations by detailing internal logic: semantic anchor with Jaccard similarity threshold, partition filter that drops placeholder slugs, and fill check that checks live CLOB depth. It warns when signals should not be traded (realizable_edge_pp <= 0). This is highly transparent.

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

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

The description is long and dense with technical jargon (monotonicity violations, partition-sum checks, Jaccard similarity). While it is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), it could be more concise. Approximately 280 words; trimming could improve readability without losing essential detail.

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

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

The tool has no output schema, but the description comprehensively explains the response structure (opportunities[], partition_check object with fields). It covers edge cases (skipped_low_similarity, placeholders_filtered) and gives detailed behavior for event and topic modes. Given the tool's complexity and zero output schema, the description is as complete as needed.

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 documented. The description adds significant meaning: event accepts slug or URL, topic accepts seed questions. It explains behavior for each parameter (e.g., topic mode searches related events, flattens markets, runs comparator). This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two distinct modes (event and topic) with clear verb+resource relationships, and it distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection rather than edge tracking or fill risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan,' 'event (recommended for a specific market),' and 'topic (for cross-event scanning).' It explains the strengths of cross-event mode over single-event mode. However, it lacks explicit 'when not to use' statements, such as pointing to polymarket_fill_risk for custom sizing (though it mentions that tool at the end).

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds significant behavioral detail: caching at KV level keyed on knobs, model family internals, Fed bet exclusion rationale, and diagnostics for empty segments. 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?

Description is verbose with deep technical details (e.g., 'lognormal barrier from 90d FRED log-returns', 'per-sport α (tennis 1.02, soccer 1.10, MMA 1.15)'). While structured with segments and knobs, it could be more concise. First sentence effectively fronts purpose, but subsequent detail is dense.

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

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

No output schema, so description must explain return structure. It does so thoroughly: by_segment, fed_candidates/fed_note, _diagnostics, and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h move warning). Covers filtering rationale and why Fed bets are excluded. Complete for a complex 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 covers all 9 parameters with descriptions, so baseline is 3. Description adds practical usage context (e.g., min_liquidity 'Set to 5000 to drop thin-book opportunities', slippage_pp advice). Provides value beyond schema, justifying +1.

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 starts with clear verb 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and explicitly targets 'what should I bet on today'. It distinguishes three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and contrasts with siblings by focusing on edge discovery rather than 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?

Description explains when to use ('what should I bet on today') and provides filtering knobs (min_liquidity, max_spread_pp, etc.) but does not explicitly state when not to use or compare with alternatives like polymarket_arbitrage. Context implies differentiation but lacks direct exclusion 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds significant behavioral context: it explains the returned structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, snapshot gaps), and data granularity (daily closes, not intraday). 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 verbose but well-structured, front-loading the purpose and using clear formatting for output fields. Every sentence adds value, though slight trimming could improve conciseness 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?

No output schema is provided, but the description thoroughly explains the output structure (tracked, expired, snapshot_dates) with field-level details and limitations. For a telemetry tool, this is highly complete.

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

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

Schema description coverage is 100%, but the description adds meaning: it explains that 'days' defaults to 14 and clamps to 2-30, and 'window' defaults to '1wk' and describes snapshot families. This supplements the schema with practical usage context.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis rather than current snapshots.

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 implicitly guides usage by contrasting fresh vs. stale edges ('a 3-week-old wide edge is wide for a reason nobody is willing to take'). It does not explicitly state when not to use, but the context is clear. Alternatives are implied by sibling tools but not named directly.

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 (readOnlyHint, idempotentHint, destructiveHint=false) already indicate safe read-only behavior. Description adds substantial behavioral context beyond annotations: it walks the order book ladder, returns specific fields (slippage, verdict, forced_directional_risk), and describes per-leg fill details for basket mode. 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, usage guidance) and front-loaded purpose. However, it is somewhat verbose with detailed return field lists, which would be more appropriate in an output schema. Still, every sentence earns its place, and the structure aids readability.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It covers both modes thoroughly, explains return fields, provides usage guidelines, warns about risks (partial fills, forced directional risk), and specifies thresholds. No gaps for an AI agent to understand invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds semantic value beyond schema: clarifies that size_usd for single-market is 'max spend on buys, target proceeds on sells' and for basket is 'settlement notional — shares per leg'. Also explains side defaults. This extra context justifies a 4.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with distinct modes (single-market and basket) and return fields. It uses specific verbs like 'check', 'walks the ladder', and 'returns', distinguishing it from trading-oriented siblings like polymarket_arbitrage.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial basket fills converting arb into unhedged directional position). Provides clear when-to-use and when-not-to-use context.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: compatibility_warning can be non-empty even when pairs are returned, temporal_alignment null means unknown rather than aligned, fees are not modeled so spreads are gross, unknown legs are never paired, and pre-mapped does not mean tradeable. This goes far 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 long, but it is intentionally structured with labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, making it scannable. The front-loaded purpose sentence is effective. Some redundancy and density exist, but the complexity of the tool justifies the length and structured format.

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

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

With no output schema, the description carries the full burden of explaining return values, caveats, error-like conditions, and interpretation. It covers top_spreads_pp, compatibility_codes, temporal_alignment, fees_note, skipped counters, and unclassified legs. An agent has enough context to invoke the tool and interpret its response correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by explaining that 'topic' is a pre-mapped shortcut, that kalshi_event_ticker and polymarket_event_slug override the mapped side, and that both modes execute the identical overlap matcher. This enriches the schema without contradicting it.

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

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

The description opens with a precise verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's function and distinguishes it from the sibling tools like polymarket_arbitrage or polymarket_edges, which address different cross-market concepts.

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

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

The description clearly explains the two usage modes — 'topic' shortcuts vs explicit ticker/slug pairings — and states that both run the identical matcher. It also warns that most pre-mapped topics return warnings, which is actionable guidance. It does not explicitly name sibling alternatives or exclusion conditions, but the mode guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to user identifier, beyond what annotations provide. 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 concise sentences plus scoping note. No fluff, front-loaded with core action.

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 1 parameter, high schema coverage, and annotations, the description fully explains behavior. No output schema, but functionality is clearly described.

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

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

Schema covers 100% of parameters with description for 'key'. Description essentially restates schema info, adding no new meaning. Baseline 3.

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

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

The description clearly states the tool's purpose: retrieve a value saved via remember, or list all saved keys if key is omitted. It distinguishes itself from sibling tools like remember and forget.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Mentions pairing with remember and forget, providing clear usage 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?

Description states mark_read flags events as read, implying state mutation, but annotations declare readOnlyHint=true, creating a direct contradiction. According to rules, this forces a score of 1.

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

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

Concise, front-loaded with purpose, no redundant sentences. Every sentence adds 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?

Despite no output schema, description details returned fields (source, citation_uri, payload). Covers all parameters, polling behavior, and alternative access method. Complete for this tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by giving examples (e.g., 'sec_8k' for type) and clarifying that mark_read affects next call. Exceeds baseline.

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

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

Description clearly states it pulls fired events from subscription feed, using specific verb 'Pull' and resource 'fired events from your subscription feed'. It distinguishes itself from sibling tools by focusing on recent alerts from persistent feed.

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 guidance on filtering by type and since, explains mark_read behavior for polling, and notes an alternative GET endpoint for scripts/dashboards. Lacks explicit when-not-to-use but offers sufficient context.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral details: fans out in parallel to multiple sources, fallback mechanism (GDELT→GNews), soft-fail for USPTO, and response format (changes grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

Description is detailed but well-organized: starts with examples, then explains data sources, parameter syntax, return structure, and when to use alternative. Front-loads key information. Slightly verbose but every sentence adds value.

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

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

Despite no output schema, description explains return structure (changes[], total_changes, citation URIs). Covers all needed context: sources, fallbacks, parameter options, and distinguishes from sibling. Complete for a complex 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 descriptions for all three params. Description adds extra context: 'type' is limited to 'company', 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or zero-padded CIK, and recommends default '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?

Description starts with clear example queries and states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling tool entity_profile.

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

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

Explicitly states when to use ('What's new', 'latest', 'updates') and when not to ('Use entity_profile instead when you want the static profile...'). Provides example queries and typical usage like '30d'.

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 idempotentHint=true and destructiveHint=false, so the tool is safe to call multiple times and not destructive. The description adds value by explaining the write behavior, key-value storage, scoping by identifier, and session-based persistence. There is no contradiction with annotations.

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

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

The description is concise, front-loading the main purpose and usage, then providing details on storage semantics and alternatives. Every sentence adds value without redundancy.

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

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

Given the simplicity of the tool (2 parameters, no output schema, no nested objects), the description provides all necessary context: what is stored, when to use, how it is scoped, persistence duration, and relationship to siblings. Annotations cover idempotency and non-destructiveness.

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 provides 100% coverage with clear descriptions for both parameters (key and value). The description adds context by explaining that the key should be a mnemonic like 'subject_property' and the value can be any text. Since schema already does the heavy lifting, this is above baseline but not exceptional.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the action (save), the resource (data), and provides concrete examples like 'resolved ticker, target address, user preference.' It also distinguishes from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

The description explicitly states when to use the tool: 'when you discover something worth carrying forward.' It provides context on scoping ('scoped by your identifier') and persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It also names alternatives: recall and forget.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive safety, so the bar is for added context; the description adds meaningful behavioral detail: graceful degradation (LEI/FIGI enrichment degrades, EDGAR identifiers still return), internal cascading through multiple endpoints, and the explicit rule about passing the entity name only rather than the full noun phrase. It does not document pagination or exact response shape, but with no output schema that is a minor gap.

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

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

The description is information-dense but long and somewhat sprawling, with parenthetical-heavy nesting that makes it harder to scan. The most important guidance is front-loaded, but the LEI/FIGI detail in the middle is lengthy, and a few clauses ('more than one instrument' / 'exact ticker map when a ticker is implied') are muddled and could be tightened.

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 two-parameter tool with 100% schema coverage and no output schema, the description covers what input goes in, what identifiers come back, how failures degrade, and the main pitfall (passing the full noun phrase). It does not describe the return shape or mention the `unresolved` field referenced in the description, but overall it is close to complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds substantial value beyond the schema: it explains how value is interpreted per type, gives concrete formats (AAPL, CIK 0000320193, ISIN example), and details the 'entity name only' constraint and why. This elevates it above 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?

States a precise verb-resource pairing ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'), gives concrete example queries, enumerates supported entity types, and is clearly differentiated from siblings like compare_entities or entity_profile. The opening spoken-language examples make the tool's purpose instantly recognizable.

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 FIRST whenever you have a name but need an ID,' and the description emphasizes it replaces 2-3 manual lookups. It distinguishes supported types and clearly states that non-equity instruments without tickers DO resolve here, which prevents an agent from wrongly assuming it is equity-only.

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. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Three sentences, front-loaded with purpose, then details on behavior and use case. Every sentence adds value, no fluff.

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

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

Despite no output schema, the description clearly describes the return value: ranked list with score, confidence, signal density per entity. It also explains the internal probe mechanism (ai_visibility_check). Complete for a comparison 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%. The description adds meaning beyond schema: explains that the first entity is treated as 'subject' and rest as competitors, and that context disambiguates common names. It does not cover all parameters in depth but provides useful context.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', with a specific verb ('compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies when to use but does not explicitly state when not to use or name alternatives beyond the listed 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?

Adds valuable behavioral context beyond annotations: it fans out to two services, handles partial failures gracefully, and mentions bundlephobia's first measurement may take 5-30s. Annotations already declare readOnlyHint=true and idempotentHint=true, so description complements them well.

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 longer but front-loaded with main purpose. It efficiently conveys composite nature, usage context, return format, and limitations. Slightly verbose but justified by complexity.

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

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

Description fully covers what the tool does, its return value (summary block, advisories, links, versions), limitations (NPM only, timeout), and partial failure behavior. No output schema exists, so description must provide this, which it does.

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

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

Schema covers both parameters with descriptions. The description adds little beyond the schema (e.g., 'npm package name', 'specific version'), so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for npm packages aggregating data from deps.dev and bundlephobia. It specifies what it covers (license, advisories, version history, bundle size, etc.) and is distinct from sibling tools.

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

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

Explicitly states when to use ('is X safe/popular/small', 'what does adding lodash cost me') and provides exclusions (NPM only; other ecosystems handled by deps.dev:version directly).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds internal details: BGE-base-en embeddings, 500-char windows, 200K char cap with truncation, and offset information. No contradictions.

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

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

The description is a single paragraph of ~120 words, front-loading purpose and then providing details. Every sentence adds value, with 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?

Given the tool's simplicity (3 params, no output schema), the description covers input, algorithm, limits, and behavior. It also explains pairing with another tool, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% for all 3 parameters. The description adds value by providing example queries (e.g., 'supply-chain risk') and clarifying defaults ('limit 1-20, default 5').

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' using a 'natural-language query'. It specifies the verb 'search' and resource 'inside a fetched record', distinguishing it from siblings by mentioning 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?

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also mentions pairing with another tool, but could be more explicit about when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'keyless, offline,' which provides additional behavioral context about operation without keys and local execution. It does not explain the output format but it is implied by the NATO spelling.

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

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

The description is two sentences, front-loaded with the primary action and use case. Every word adds value; no superfluous information.

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

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

For a simple transformation tool with one string parameter, no output schema, and comprehensive annotations, the description covers purpose, usage, and behavioral traits (keyless, offline) completely. No gaps are apparent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying 'NATO phonetic alphabet,' which clarifies how the input text is transformed. This goes beyond the schema's property description 'The text to spell.'

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

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

The description clearly states the action (spell), resource (text), and method (NATO phonetic alphabet) with an example. It distinguishes itself from siblings like morse_encode by specifying a different encoding scheme.

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 provides a clear use case ('Great for reading codes/confirmation numbers aloud') and mentions keyless, offline operation, which implies when to use. However, it does not explicitly state when not to use or compare with alternatives like Morse code.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, returns subscription ID, specifies delivery channel details, phone verification requirement, SMS daily cap of 10, webhook signing, and auto-disable after 10 failures. 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 detailed but well-structured with clear sections for types and delivery channels. It is slightly long but front-loaded with the core action. Every sentence adds value.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers return value, required accounts, rate limits, and failure behavior. It is sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% and the description enriches parameters with detailed examples and constraints for each type, such as sec_8k items codes, polymarket_edge topic, and delivery options. This provides meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions by explaining what it does.

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

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

The description provides clear when-to-use context by listing supported subscription types and delivery channels. It also mentions prerequisites (Pipeworx OAuth account, phone verification for SMS) but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant context about being an onboarding tool returning categorized examples from a live catalog, adding value 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?

Long but front-loaded with common queries and well-structured with categories and usage patterns. Some redundancy but overall efficient for the 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?

No output schema, but description fully explains return content (category-bucketed examples with tool signatures) and covers both full spread and topic-focused usage. Complete for its role.

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 one optional parameter described. Description enriches with example focus areas and default behavior, but baseline 3 is appropriate as schema already 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?

Description clearly states it is the onboarding entry point providing categorized example questions with tool+argument shapes, and distinguishes from siblings by being the first tool to use when the agent doesn't know capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and describes calling with no arguments or with a topic, but lacks explicit when-not-to-use guidance.

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

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

Beyond annotations, the description clarifies that the row is deactivated (not deleted) and ownership is enforced, adding valuable behavioral context that annotations do not provide.

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

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

Two sentences, concise and front-loaded, with no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, deactivation effect, and historical impact, which is complete enough.

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 much. It mentions 'by id' but no further syntax details; the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('cancel') and resource ('subscription'), clearly distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions') and the effect on historical data, providing clear context for when to use the tool. However, it does not explicitly compare with alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond annotations: it defines the verdict enum, distinguishes the meaning of could_not_verify (check did not happen, with error structure) from unsupported (no source), and notes that evidence includes pipeworx:// citations. This is exactly the kind of extra transparency that helps callers interpret results correctly.

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

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

The description is long but every sentence carries essential information: examples, routing logic, return types, edge cases, and the efficiency gain. It is well-structured with clear separations between when-to-use, how routing works, what is returned, and critical warnings. No filler or 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?

The tool is complex (two routing paths, multiple verdicts, error handling) and has no output schema. The description covers the return format (verdict, actual value, citation, reasoning), explains the subtle difference between could_not_verify and unsupported, and hints at the underlying pipeline. This is sufficient for an agent to call the tool and interpret results correctly.

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

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

Schema description coverage is 100%; both 'claim' and 'tolerance_pct' have descriptive comments in the schema. The tool description adds context about the default tolerance behavior and the use of percent-delta math, but it does not add meaning beyond what the schema already provides for the parameters. Baseline 3 is appropriate.

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

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

The description opens with explicit natural-language examples ('Is it true that…', 'fact check') that make the tool's purpose unmistakable. It clearly specifies a noun phrase: natural-language claim verification against authoritative sources, and distinguishes itself from siblings by describing the structured SEC EDGAR fast path vs. grounded pipeline.

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 whenever the agent needs to check whether something a user said is factually correct' and explains two routing paths. It does not explicitly mention sibling tools or say when not to use, but it positions itself as the replacement for 4-6 sequential calls, providing clear context for when it is appropriate.

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