Textstats

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

Discloses that the default model is free, that Anthropic calls require a BYO key and cost the user directly, and that results include per-model {score, confidence, signals, raw_response} plus a combined view. Annotations already establish read-only/idempotent behavior, so the description adds cost and model-selection context without contradicting them.

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

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

Four sentences pack the core action, cost behavior, return shape, and use cases without redundancy. The most important action is front-loaded in the first sentence.

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

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

For a read-only probe with no output schema, the description supplies the return structure, default behavior, cost caveat, and typical applications. This is sufficient for an agent to select and invoke the tool correctly, matching the completeness of top-tier references.

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 all four parameters are already documented. The description adds value by explaining the default model for the `models` parameter and the cost implications of `_apiKey`, plus giving concrete `entity` examples. This builds on, rather than repeats, the schema.

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

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

Clearly states it probes LLMs for knowledge about a business/brand/product/topic and produces a 0-100 visibility score per model. The verb 'probe' and specific output distinguish it from sibling tools like deep_research or compare_entities, which focus on different research objectives.

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') and notes the default free model vs BYO Anthropic key. However, it does not name alternative tools or say when not to use it, so it earns a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds transparency about internal routing behavior (5,498 tools), the returned structured answer with citations, and performance ('one fast call'). It doesn't mention failure modes for ambiguous questions or rate limits, but for a read-only query tool this is sufficient and the annotation coverage lowers the burden.

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

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

Though the description is long, every sentence earns its place: it states the primary purpose, lists covered domains, gives examples, explains trigger phrases, and contrasts with alternatives. The key directive is front-loaded ('PREFER OVER WEB SEARCH'), and the structure flows logically from purpose to usage to escalation criteria.

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

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

For a tool with no output schema, the description adequately explains the output (structured answer with citations) and provides enough context for an agent to select it. It comprehensively covers use cases, trigger phrases, examples, and alternatives, making it a complete standalone guide for invocation. The annotations and schema fill in the remaining structured details.

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

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

The schema has 100% coverage with descriptions for all parameters, including aliases. The description adds meaning beyond the schema by providing concrete example questions and indicating the natural-language nature of queries. It reinforces what kinds of input are appropriate (e.g., facts, lookups, current data) and clarifies that the question can be phrased as 'what is', 'look up', etc.

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 what the tool does: it routes questions to 5,498 tools across 1,440 verified sources and returns structured answers with stable pipeworx:// citation URIs. It clearly distinguishes itself from web search and sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research, and by specifying its role as the default entry point.

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

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

Provides extensive when-to-use guidance: 'PREFER OVER WEB SEARCH' for a specific list of domains, 'START HERE for most questions', and explicit step-up alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also supplies trigger phrases and concrete examples, making the decision process 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds important behavioral context: it is a full working router with no fallback, currently identical to ask_pipeworx because no candidate is active, and candidate improvements may be enabled live. This enriches the agent's understanding beyond the structured hints.

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

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

The description is well-structured and front-loaded: it opens with the core identity and beta purpose, then addresses current status, usage, and fallback behavior. Each of the four sentences delivers distinct, valuable information 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?

Given the tool's complexity (universal router), the description covers its current behavior, relationship to the stable version, and safety profile. It explicitly notes the response shape matches ask_pipeworx, so the absence of an output schema is mitigated by the reference to the sibling tool.

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

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

The input schema fully documents all parameters as aliases for 'question' (100% coverage), so the schema carries the semantic weight. The description only repeats that arguments are the same as ask_pipeworx, without adding new meaning to the parameter semantics.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with 5,498 tools and the same response shape, while also distinguishing it from the stable ask_pipeworx. The specific verb 'ask' and resource 'pipeworx' plus the beta context make its function unambiguous.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use guidance. It does not explicitly state when not to use it or mention alternatives beyond the stable router, so it stops short of a full exclusion list.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the extract-only-from-data behavior, the exact return structure with evidence quotes and confidence, and the explicit refusal reasons. It also transparently notes the cost of one extra LLM call, providing rich behavioral context.

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

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

The description is dense but efficient: it front-loads the core concept, then adds specific use cases, return shapes, refusal reasons, and cost trade-offs without redundant fluff. Every sentence delivers actionable 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?

This complex tool is fully described: purpose, routing scope, return format, refusal reasons, cost comparison, and application contexts. With no output schema, the description compensates by explaining the full response contract, making it complete for an agent.

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

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

The input schema has 100% coverage for the single 'question' parameter, including all aliases. The description does not add parameter-specific details, but the schema already fully documents semantics, so the baseline of 3 applies.

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

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

The description explicitly states 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: routing, fetching, then extracting answers only from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and refusal behavior, making the purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also states when to avoid it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, directly addressing 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, and idempotentHint, and the description goes far beyond these by detailing the parallel fan-out behavior, the resolver contract (market_match_confidence, market_match_score, market_match_alternatives), safety short-circuits, news fallback logic (_fallback_attempted, _fallback_failed_reason), and resolution-rule risk (cancellation_rule). This provides a comprehensive behavioral model for the agent with 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 exceptionally long but well-organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every part adds unique information and earns its place, but the overall length is far beyond what is typical and could overwhelm an agent attempting to quickly parse the essentials. It is structured but not concise.

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

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

For a complex research tool with no output schema, the description covers inputs, resolution, fan-out, response shapes, edge cases, safety mechanisms, and even risk caveats like cancellation rules. It is exceptionally complete and gives an agent everything needed to correctly invoke and interpret results, making it one of the most thorough tool descriptions possible.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema itself fully documents market, depth, and include_raw, including examples and enum values. The description adds some context (e.g., fan-out examples and include_raw size implications) but does not materially improve understanding beyond what the schema already provides.

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

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

The description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It lists explicit input formats (slug, URL, question text), example use cases, and a detailed classifier list, which clearly distinguishes it from sibling tools like polymarket_arbitrage or validate_claim. This leaves no ambiguity about what the tool does.

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

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

The description gives clear when-to-use context with explicit user intents ("should I bet on X", "what does the data say about Y", "is there edge in Z") and covers edge cases like low-confidence matches and closed markets. However, it does not explicitly mention alternatives or say when not to use this tool, so it lacks explicit exclusions. Still, the usage context is strong enough to guide correct selection.

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

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

Beyond the readOnlyHint=true annotation, the description discloses specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles edge cases (off-calendar fiscal years), and explains output traits like sorting by primary metric and returning paired data with citation URIs. This adds substantial behavioral context.

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

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

The description is dense and front-loaded with trigger phrases, then provides concrete details about data sources, sorting, and output. It is longer than minimal but each sentence carries useful information; the structure is logical and scannable, though slightly verbose.

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

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

With no output schema, the description compensates by explaining the return format ('paired data + pipeworx:// citation URIs'), the metrics for each entity type, sorting behavior, and that it replaces 8–15 sequential lookups. This covers the necessary context for invocation and expected results.

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

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

Schema coverage is 100% with clear descriptions for both 'type' and 'values'. The description adds example values and elaborates on what metrics are pulled, but this is more behavioral than parameter-level semantics. It does not significantly enhance meaning beyond the schema, so baseline 3 applies.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with a clear verb and resource. It also lists trigger phrases like 'X vs Y' and 'rank these companies' and distinguishes itself from sequential single-pack lookups.

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

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

It provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and clarifies when to use type='company' vs type='drug' with data source details. This directly addresses when to use the 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 cover read-only, non-destructive, idempotent, and open-world hints; the description adds significant context: account/auth requirements, paid plan for thorough, latency expectations, gaps[] behavior, never-invented guarantee, citation_uri resolvability, and semantic excerpting. It does not contradict 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 every sentence carries substantive info (auth, alternatives, output shape, depth semantics, latency). It is front-loaded with the account requirement and avoids filler. Slightly verbose for a tool description, but appropriate 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?

There is no output schema, yet the description fully covers return value structure: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], and hop field. It also addresses failure modes (news topics yielding empty gaps) and performance expectations. Exceptionally complete for a two-parameter tool with no output schema.

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

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

The schema already provides full descriptions for both params (100% coverage), but the description adds operational nuance: depth values correspond to facet counts and hop strategies, and 'thorough' requires a paid plan. It also explains latency implications. This exceeds the baseline of 3 but does not fully transform the parameter understanding beyond the schema's concise breakdown.

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: 'Grounded multi-source research across Pipeworx's 1440 STRUCTURED data sources' with decomposition into facets and parallel routing. It also distinguishes from siblings by naming ask_pipeworx as the alternative for single lookups or news. The verb+resource+scope is specific and unambiguous.

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

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

The description gives explicit when-to-use statements ('Best for broad/multi-part questions over structured data') and when-not ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also names auth constraints ('If you are not signed in, use ask_pipeworx instead'). This is model guidance with clear 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 the tool safe (readOnly, idempotent, non-destructive), so the bar is lower. The description adds valuable context about behavior: it returns top-N tools with names, descriptions, and schemas, and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the safety annotations to clarify the output and the meta-nature of the call.

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, each serving a distinct purpose: what it does, example use cases, and call-first guidance. It is front-loaded with the core purpose and uses bullet-like enumeration efficiently. Slightly long due to the domain list, but every part earns its place.

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

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

Given the tool's meta-purpose and the rich sibling set, the description covers the essential context: purpose, when to use, result content, and precedence. There is no output schema, but the description clearly states that results include names, descriptions, full schemas, and examples, which is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by listing example queries ('analyze housing market trends', 'look up FDA drug approvals') and explaining that the query accepts multiple aliases (task, q, description, search), which reinforces the parameter semantics without redundancy.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being the meta-tool for discovery, listing covered domains and explicitly noting it returns ready-to-call tools with full schemas.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This also implies when not to use it (when you already know the tool or need a single answer), covering the alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial context beyond this: parallel fan-out across multiple sources, specific return fields (cik, filings, fundamentals, patents, news, LEI), API fallbacks (GDELT→GNews), and known limitations (patents API sunset, soft-fail). No contradictions with annotations.

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

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

The description is dense but well-organized: starts with user-phrase examples, then defines the tool, lists return fields, and ends with limitations. Every sentence conveys useful information, but it is longer than necessary due to extensive examples and nested details. Still, given the multi-source complexity, this length is justified.

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

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

Despite lacking an output schema, the description fully enumerates return fields (cik, company_name, filings with URIs, fundamentals sorted by period_end, patents, news fallback, LEI) and notes operational caveats (patents sunset, soft-fail, parallel call). This is complete for a complex tool, leaving no major gaps for the agent.

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

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

Schema description coverage is 100%: both parameters have full descriptions. The description repeats the same value format ('ticker AAPL or zero-padded CIK') without adding new semantics beyond the schema. The type parameter's enum is also fully documented. Baseline 3 is appropriate since no extra meaning is added.

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 'full cross-source profile of a US public company in ONE parallel call' with specific example queries and a list of return fields. It distinguishes itself from siblings by explicitly mentioning 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-based lookups.

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

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

Provides explicit guidance on when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use: 'names not supported (use resolve_entity first if you only have a name).' This clearly delineates usage boundaries.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is signaled. The description adds context that this clears previously stored memories and is for stale context or sensitive data, which goes beyond the raw annotation. It does not contradict annotations, and the idempotentHint is consistent with a delete-by-key operation.

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

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

The entire description is two sentences, front-loaded with the action ('Delete a previously stored memory by key') and followed by concise use cases. Every sentence adds value, with no redundancy.

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

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

For a simple delete-by-key tool, the description plus annotations and schema provide sufficient context for invocation. It lacks explicit behavior for missing keys or return values, but given the tool's simplicity and the existing annotation coverage, this is a minor gap.

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

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

Schema coverage is 100% because the only parameter, 'key', has a description 'Memory key to delete' and an example. The tool description does not add additional syntax or format details beyond what the schema provides, so it meets the baseline but does not exceed 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 states 'Delete a previously stored memory by key', which is a specific verb+resource combination that clearly distinguishes this from sibling tools like remember and recall. The title 'Forget' is also expanded upon with actionable meaning.

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

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

The description explicitly provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references siblings by saying 'Pair with remember and recall,' giving clear context for when this tool is appropriate.

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

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

The annotations (readOnlyHint: true, idempotentHint: true, destructiveHint: false) already establish the safety profile. The description adds behavioral detail: it fetches the page, extracts title/description/links, emits standard llms.txt markdown, and the output is a single text blob for site-root placement. 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 two sentences: the first states the core functionality and process, the second lists concise use cases. Every clause adds value, no unnecessary words, and the most important information is front-loaded.

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

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

With no output schema, the description explains the output format ('standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'). It also covers use cases and parameter behavior. Annotations cover safety, making the tool fully described for selection and invocation.

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

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

The input schema provides 100% coverage for both parameters (url and max_links). The description does not add significant semantic meaning beyond the schema—'any URL' is already implied in the schema's example. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool 'Generate a production-ready llms.txt file for any URL' and describes the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This specific verb+resource+output distinguishes it from siblings like readability or scan_competitor_ai_presence, which focus on other aspects.

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

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

The description explicitly provides three use cases: getting a client's site indexed by AI, drafting llms.txt for your own project, and auditing how an AI crawler sees a competitor. This gives clear context for when to use the tool, but it does not mention alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context by specifying the scope ('the caller's') and the list of returned fields. This goes beyond annotation basics, though it does not disclose potential pagination or limits.

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

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

The description is two concise sentences, front-loaded with the verb and resource, followed by a practical usage tip. Every word serves a purpose with no filler.

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

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

Given the simple signature (one optional parameter), rich annotations, and no output schema, the description adequately covers purpose, scope, return fields, and usage context. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The single parameter include_inactive is fully described in the schema (100% coverage), so the description need not repeat it. The description adds no additional semantic information about the parameter, making the schema the primary source.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the exact returned fields. The phrase 'before adding more or to find an id to cancel' explicitly distinguishes it from sibling subscribe/unsubscribe tools.

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

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

It provides clear usage context by advising to use this tool before adding more subscriptions or to find an id to cancel. However, it does not explicitly name the alternative tools (subscribe/unsubscribe), so it stops short of a 5.

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

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

The annotations are all false, offering no behavioral hints, so the description carries the full burden. It thoroughly discloses the workflow (returns claim_token when filed without an account, pass it back to read resolution), rate limit (5/day), and quota impact. It also clarifies scope and what should not be reported, with no contradiction to 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 every sentence earns its place by covering scope, exclusions, workflow, rate limits, and quota. It is front-loaded with the core purpose and follows a logical structure, though a slightly tighter phrasing could reduce cognitive load.

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 does not fully specify return values for all cases, but it does cover the no-account claim_token path and later token use. It explains rate limiting, free usage, and scope exclusions, which is strong for a feedback tool. Minor ambiguity remains about the response when an account is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds an explicit invocation example for claim_token and reinforces message specifics. It does not merely repeat the schema; it explains the pass-back flow, adding real value beyond the field descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' naming the exact action, target, and scope. It clearly distinguishes this from sibling research and discovery 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?

It explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion: do not file for tools from other MCP servers. It even names the alternative behavior—'file with that server instead'—making the decision boundary 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?

Annotations already declare readOnly, openWorld, and idempotent, but the description adds substantial context: it states data is derived from 'CF analytics-engine', contains 'no PII', and is 'Cached 5min-1h depending on window'. It also clarifies the output shape '(pack, tool, count)'. This goes beyond the annotations and helps the agent understand behavior, privacy, and freshness.

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 yet comprehensive. It opens with a clear one-liner, lists output specifics, provides a numbered list of use cases, and ends with notes on data provenance and caching. Every sentence earns its place without redundancy.

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

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

For a tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, output format, use cases, data source, privacy, and caching. An agent can confidently decide when to call it and what to expect in the 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 description coverage is 100% and the single 'window' parameter is fully documented in the schema. The description repeats the window options and the trade-off between shorter and longer windows, but does not add new information beyond the schema. This aligns with the baseline for high schema coverage.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and resource ('top tools, top packs, total call volume'), and the focus on 'what other AI agents are calling' distinguishes it from sibling tools like discover_tools.

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

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

The description provides explicit use cases via a numbered list: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. This gives clear context on when to use the tool, though it does not name alternative tools or explicitly state when not to use it.

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

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

The description goes far beyond the read-only annotation by detailing internal logic: partition_sum checks, placeholder filters, skipped_low_similarity, and the fill-check caveat that realizable_edge_pp <= 0 means the edge is not tradeable in the book. This gives the agent deep insight into edge cases and failure modes, with no contradiction to annotations.

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

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

The description is long, but it is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence adds necessary operational detail for a complex tool; however, it could be trimmed to improve scannability.

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

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

Even though there is no output schema, the description spells out the response shape (opportunities[] with gap_pp, suggested_trade, reasoning, etc.) and explains failure semantics (e.g., null arb signal on placeholder-heavy partitions). Given the tool's complexity, this is a complete and self-sufficient description.

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 enriches both parameters significantly: event gains slug examples and 'Full Polymarket URLs also accepted', topic gains seed-question examples and explains what cross-event scanning does. This goes well beyond the schema's bare descriptions, adding mode-specific behavior and expected formats.

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

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

The description opens with a specific verb and resource ('Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'), clearly distinguishing this tool from siblings like polymarket_edges or polymarket_fill_risk. It also explains the three invocation modes (trending_scan, event, topic), further clarifying scope.

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?

Excellent when-to-use guidance: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)' are explicit. It also tells users to use polymarket_fill_risk for custom sizing, naming an alternative and preventing misuse.

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 declare safe read-only, open-world, idempotent behavior. The description adds considerable behavioral detail: KV-level caching (1h) keyed on knobs, the 24h-move warning, why partition_overround returns kelly_fraction_half=0 at parent level, placeholder-slug filtering, and the _diagnostics funnel to explain 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?

The description is heavily detailed, almost a specification, with many nested clauses and technical asides (e.g., per-sport α values, Run 8 gates). It is front-loaded and structured with segment names and top-level response fields, but it could be tightened by moving some details to parameter descriptions or an output schema. Still, it earns its length for a complex tool with no output schema.

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 and 9 parameters, the description carries the full burden of explaining the response shape and interpretation. It covers by_segment structure, fed_candidates exclusion, diagnostics, the 24h warning, and how knobs filter opportunities. This is complete for an agent to correctly use and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial extra meaning: it explains why min_partition_leg_kelly exists (min_kelly doesn't filter partition arbs), the slippage context ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), and how min_edge_pp is evaluated net of slippage. This goes well beyond the schema.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by emphasizing the Pipeworx data disagreement and the 'what should I bet on today' use case.

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

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

The description provides strong usage context: built for agents to discover opportunities without paging hundreds of markets, and it explains how to adjust tradeable-edge knobs (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly name alternative tools for when not to use this one, stopping short of the 'alternatives' criterion for a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds substantial context: the 60-day TTL limit, dependence on snapshotting being enabled, daily close calculations, net slippage assumptions, and the meaning of gaps in snapshot_dates. This goes well beyond the structured annotations.

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

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

The description is long, but well-structured with Args, RESPONSE, and LIMITS sections, and front-loaded with the core purpose. Every sentence contributes meaningful detail that the schema and annotations do not cover, so the length earns its place.

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

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

There is no output schema, so the description must explain the return shape, and it does so thoroughly: tracked[] fields, expired[] meaning, snapshot_dates[] purpose, and the limitations of history depth. For a complex time-series telemetry tool, this is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining days and window in the context of snapshot families and lookback behavior, and clarifies the max 30/day default. It reinforces the schema but adds the conceptual link to polymarket_edges windows, which is useful.

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 defines the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific question about edge age and shrinkage. It distinguishes itself from the sibling polymarket_edges tool by focusing on time-series persistence rather than current edge generation.

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

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

The description conveys when to use this tool by contrasting fresh vs. old edges and explaining that a wide edge that has persisted for weeks is a different trade. It does not explicitly state exclusions or direct alternatives, but the sibling context and repeated references to polymarket_edges imply the appropriate alternative for raw current edges.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the internal walk of the order-book ladder, the exact metrics returned (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and the risk of partial basket fills converting an arb into an unhedged directional position. This is deep behavioral context that the annotations cannot convey.

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

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

The description is long but exceptionally well-structured, with clearly labeled SINGLE-MARKET and BASKET sections, explicit return lists, and a final 'USE THIS' guidance paragraph. Every sentence carries unique, decision-relevant information, and the key purpose is front-loaded in the first clause.

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 fully enumerates all return fields for both modes, describes the verdict values (clean|degraded|cannot_fill), and explains edge cases like forced_directional_risk and thin_legs. For a tool of this complexity, the description is complete enough for an agent to select, invoke, and interpret results correctly without external documentation.

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

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

Although the schema already documents each parameter at 100% coverage, the description adds significant semantic meaning: it explains that `market` and `event` select mutually exclusive modes, clarifies that `side` has mode-specific defaults and basket auto-detection, and interprets `size_usd` differently for buys (max spend) vs sells (target proceeds) and for baskets (settlement notional per leg). This goes far beyond the schema's basic field descriptions.

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

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

The description opens with a specific, differentiated purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling trading tools by focusing on fill risk, and it unambiguously describes both single-market and basket/partition modes with distinct verbs and resources.

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

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

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and provides exclusions for partial fills and directional risk, leaving no ambiguity about when to prefer this tool over alternatives.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: it discloses that the tool returns compatibility_warning in specific edge cases, explains skipped_cross_type/subtype counters, and details temporal_alignment semantics. It also openly admits that most pre-mapped topics currently return warnings, setting accurate expectations about real-world output.

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 information-dense, but every sentence serves a purpose. It is front-loaded with the core concept, then flows through modes, response, safety fields, and caveats. The structured use of ALL-CAPS labels (TWO MODES, RESPONSE, SAFETY FIELDS) aids readability, though a more compact phrasing of the skipped_cross_type details could slightly improve conciseness.

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

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

With no output schema, the description carries full responsibility for explaining return values. It covers leg-by-leg prices, matched spreads in pp, compatibility_warning triggers, temporal_alignment, and skipped_cross counters. It also contextualizes when the spread is a real signal vs when it is meaningless, making the tool's behavior fully understandable for correct invocation and interpretation.

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

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

Schema coverage is 100%, but the description enriches the three parameters significantly: it lists all 10 topic shortcuts, explains that topic auto-fetches matching events, and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This interaction between parameters is not evident from the schema alone, so the description adds genuine value.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' a specific verb+resource statement that clearly distinguishes this tool from siblings like polymarket_arbitrage (intra-venue) and bet_research. It further clarifies the scope (same resolving question, participant pool differences) and provides two distinct modes, making the purpose unambiguous.

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

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

The description explicitly states two usage modes (topic shortcuts vs explicit tickers) and provides strong when-not guidance: compatibility_warning cases indicate when no arb exists, temporal_alignment:false means spreads are meaningless, and the closing caveat warns that 'pre-mapped ≠ tradeable.' This gives the agent clear conditions for when to use the tool versus when to avoid 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 include readOnlyHint and idempotentHint, and the description adds valuable context such as 'keyless, offline' and 'syllable-estimation heuristic,' which informs the user about determinism and dependencies. It also mentions the underlying counts returned, giving a clearer picture of behavior beyond the annotations.

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

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

The description is two sentences, front-loaded with the main verb and resource, and every clause adds relevant information: the metrics, the scale, the counts, and the heuristic. No filler or redundancy exists.

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 single-parameter tool with rich annotations and no output schema, the description is quite complete: it names the exact outputs (Flesch scores and counts) and provides a key detail about the heuristic. It could mention edge cases like empty text or non-English input, but these are not essential for basic usage.

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

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

Schema coverage is 100% with the single 'text' parameter already described. The description does not add significant detail about the parameter itself, but it does explain that word/sentence/syllable counts are computed, which indirectly clarifies how the text is processed. This meets the baseline without adding new parameter-level semantics.

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

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

The description clearly states the tool computes readability scores, specifically naming Flesch Reading Ease and Flesch-Kincaid Grade Level. It also distinguishes itself from siblings by highlighting keyless and offline operation, making the purpose unambiguous.

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

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

The description implies the tool is for computing readability scores when you need those metrics, but it does not explicitly state when to use this tool vs alternatives like text_stats. No exclusions or comparison to sibling tools is provided, but the purpose itself strongly suggests the usage scenario.

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 the tool read-only, idempotent, and non-destructive, so the description only needs to add context beyond those. It does so by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key to list all keys. 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, front-loaded with the core action and parameter behavior. Every sentence adds distinct value: the retrieval/list behavior, the use case, and the scoping/relation to sibling tools. No redundancy or filler.

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

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

Given this is a simple one-optional-parameter tool with no output schema and rich annotations, the description covers all essential aspects: how to retrieve, how to list all, when to use it, scoping, and sibling tool relationships. An agent has enough information to invoke it correctly without further clarification.

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

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

The sole parameter 'key' is fully documented in the schema (100% coverage), and the description reinforces the same behavior. It adds illustrative examples (ticker, address, research notes) but no substantive new meaning beyond what the schema already provides.

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

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

The description opens with a specific verb ('Retrieve') and resource ('value previously saved via remember'), then clearly distinguishes the two modes: retrieve by key or list all saved keys when the argument is omitted. It is easy to tell apart from sibling memory 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?

It explicitly states when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and names the paired alternatives: 'Pair with remember to save, forget to delete.' This gives clear context and exclusions for alternative tools.

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

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

The description discloses a significant side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotation readOnlyHint:true, because marking events read modifies persistent state. This is a direct annotation contradiction, so the description fails to align with the safety hints.

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

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

The description is four sentences, front-loaded with the core purpose, then return payload, filtering, side effect, and alternative endpoint. Every sentence provides actionable information with zero fluff, making it concise and well-structured.

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

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

The description covers the return shape (source, citation_uri, raw payload), filter options, the mark_read side effect, and an alternative access point. Given there is no output schema and the tool has 5 optional parameters, this is strong. However, it doesn't mention unread_only or limit in the narrative, though those are in the schema, so it's not fully complete.

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

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

The schema already covers all 5 parameters with descriptions (100% coverage), but the description adds value by providing an example type ('sec_8k'), clarifying the since parameter's ISO timestamp requirement, and explaining the consequence of mark_read (next call only shows newer ones). This goes slightly beyond the schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' using a specific verb and resource. It clearly distinguishes from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes), making the tool's purpose unambiguous.

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

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

The description explains the tool is for retrieving alerts and even notes that polling is acceptable. It provides an alternative HTTP endpoint for scripts/dashboards, giving context for when to use the tool vs. external access. However, it doesn't explicitly name sibling tools as alternatives, so it's not a perfect 5.

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

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

While annotations already mark readOnly=true and idempotent=true, the description adds non-obvious behaviors: the GDELT→GNews fallback on rate limit/5xx, USPTO soft-fail due to PatentsView sunset, and accepted `since` formats. This transparently discloses edge-case behavior beyond annotation hints.

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

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

The description is long but structured: it opens with user-intent examples, then sources/fallback, then input format, then output, then alternative. Every sentence provides distinct value with no redundancy, though slightly dense for a multi-source tool.

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

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

Given no output schema, the description compensates by specifying return structure (changes[] grouped by source, total_changes, citation URIs) and covers failure modes (soft-fail, fallback). It also disambiguates from entity_profile, making the tool contextually complete for an agent.

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

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

Schema already covers all 3 parameters with descriptions, so baseline 3. The description adds practical details like `since` relative shorthand examples ('7d', '30d', '3m', '1y') and `value` as ticker or zero-padded CIK, which aids correct invocation beyond the schema.

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

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

The description explicitly states the tool is a 'change feed for a company' and provides concrete user intents ('What's new with X', 'latest on Y'). It names the verb 'fans out' and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO), clearly distinguishing it from entity_profile.

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

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

The description provides explicit usage context through query paraphrases and states a clear alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This gives unambiguous when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (idempotentHint true, readOnlyHint false), the description adds valuable behavioral context: key-value pairs are scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and the lifecycle with recall/forget. This significantly enriches the agent's understanding without contradicting annotations.

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

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

Four sentences, front-loaded with purpose, and each sentence adds value. No fluff or redundancy. The description efficiently covers purpose, usage, storage details, and pairing instructions.

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 key-value storage tool with two required parameters and no output schema, the description is complete. It covers what to store, when to use it, persistence behavior, and how to retrieve/delete. No significant gaps remain.

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

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

The input schema already covers both parameters with 100% coverage, providing clear descriptions for key and value. The description adds only the generic 'key-value pair' phrase, which does not meaningfully extend the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from siblings by explicitly naming recall and forget as complementary tools, making 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?

It provides explicit usage context: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also names alternatives (recall to retrieve, forget to delete), giving clear guidance on when to use this tool versus 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?

Annotations already mark this as readOnly/idempotent. The description adds that each call cascades through several lookup endpoints internally, and explains the auto-disambiguation behavior. It also discloses the output format including citation URIs, which is useful beyond the formal schema.

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

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

The description is efficiently structured with examples, a clear 'Use FIRST' directive, and a SUPPORTED TYPES section. While it is somewhat long, each section adds necessary detail. No filler sentences.

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

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

The description covers both supported types, their outputs (ticker, CIK, RxCUI, etc.), and citation URIs. It gives usage examples and explains the internal cascade, which compensates for the lack of an output schema. It does not address error conditions or edge cases, but these are less critical for a lookup tool.

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

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

The input schema already documents both parameters with examples (type enum, value alternatives). The description largely repeats this information, though it adds the note about auto-disambiguation and the fact that the value can be a ticker, CIK, or name. However, the added value is minimal given 100% schema coverage.

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

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

The description opens with concrete example queries and states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It clearly identifies the action (resolve) and resource (names to identifiers), and distinguishes itself from sibling tools by focusing on ID lookup.

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

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

It provides explicit instruction: 'Use FIRST whenever you have a name but need an ID.' This is a clear when-to-use directive. It also notes that it replaces 2-3 manual lookups, giving context for alternative approaches.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context beyond annotations: it states the tool calls ai_visibility_check per entity, ranks by score, and the return format includes score, confidence, and 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?

The description is three sentences, front-loaded with the main purpose, then describes the process and output format, and ends with a clear use case. Every sentence earns its place with no redundancy or filler.

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

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

The tool is moderately complex (multi-entity, calls sub-tool, ranks results) and has no output schema. The description covers the purpose, process, and return values sufficiently. It relies on schema for parameters and annotations for safety, making it complete enough for an agent to select and invoke.

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

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

Schema coverage is 100% with parameter descriptions for models, _apiKey, context, and entities. The description reinforces the comparative use case but adds no parameter-level detail beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings by naming the underlying sub-tool and the comparative nature.

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

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

Provides explicit use case: competitive AI-marketing audits, with a concrete example question. It implies use is for multi-entity comparison vs single-entity ai_visibility_check, but does not explicitly name alternatives or exclusions. Clear context, but formal when-not-to-use guidance is missing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30 seconds, and sources_failed will list timeouts while the rest still returns. This goes beyond annotations and sets proper expectations for latency and failure handling.

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

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

The description is well-structured and every sentence conveys distinct value: purpose, usage trigger, return format, ecosystem scope, and failure behavior. It is front-loaded with the core purpose and each additional sentence earns its place, making it informative 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?

Despite no output schema, the description thoroughly details the return shape (summary block fields, per-advisory detail, links, alternative versions), covers partial failure, latency, and ecosystem limitations. For a composite tool of this complexity, the description is complete enough for an agent to invoke 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 coverage is 100% and both parameters already have detailed descriptions (package accepts scoped names; version defaults to latest). The description adds no new parameter-level semantics beyond what the schema provides, so the 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's purpose as a composite check for 'should I add this npm package to my project', explicitly naming the fan-out to deps.dev and bundlephobia with the specific data types returned. It distinguishes from alternatives by noting NPM-only scope and pointing to deps.dev:version for other ecosystems.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small"' and explains when NOT to use it (non-NPM packages go to deps.dev:version directly). This is clear, direct guidance for choosing this tool over alternatives.

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

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

The description discloses substantial behavioral details beyond the readOnlyHint and idempotentHint annotations: BGE-base-en embeddings, 500-char overlapping windows, a 200K char cap with truncation flagging, and output features like character offsets for verifiable quotes. This gives the agent a precise mental model of the tool's internal behavior.

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

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

The description is front-loaded with the core action ('Semantic search INSIDE a fetched record'), then flows into usage guidance, and concludes with technical details. Every sentence earns its place—functional, use-case, or algorithmic—with no filler or redundancy.

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

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

Despite having no output schema, the description compensates by specifying what the tool returns: top-N passages with character offsets and similarity scores. It also covers the input cap, truncation flag, and pairing with ask_pipeworx_grounded, providing a complete operational picture for safe and effective invocation.

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

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

The input schema already achieves 100% coverage with clear descriptions for all three parameters. The description adds context like truncation behavior and output structure, but the core meaning of text, query, and limit is fully captured by the schema. Therefore, the description adds no significant parameter-level meaning beyond the baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb-resource pairing. It clearly distinguishes itself from sibling search tools by emphasizing that it operates on already-fetched text, and it explicitly contrasts with ask_pipeworx_grounded to cement its niche.

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

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

It explicitly states 'Use when the record is too big to cram into the prompt' and explains the companion workflow with ask_pipeworx_grounded. However, it does not provide explicit 'when not to use' scenarios or alternative tools for different use cases, so it's clear but not exhaustive.

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

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

The description enriches the annotations by disclosing authentication requirements (OAuth account, anonymous/BYO cannot persist), rate limits (10/day SMS cap), phone verification, and return value. It also clarifies that the feed is always on and how to access it, adding significant context 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 well-structured, with the main purpose front-loaded, followed by supported types and delivery channels. Every sentence adds critical detail, and despite its length, it is dense and free of fluff, effectively using examples and parentheticals.

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 3 parameters (2 required), nested objects, no output schema, and 5 enumerated types. The description covers return value, authentication, delivery options, per-type param guidance, and limitations, making it comprehensive for a create-subscription tool of this complexity.

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

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

Although schema coverage is 100%, the description goes beyond the schema by providing concrete examples per type (e.g., items:['5.02'] = officer change), explaining the meaning of delivery channels, and noting restrictions like verified phone and webhook HMAC signing. This adds substantial value to parameter understanding.

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

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

The description uses a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the returned value (subscription id), distinguishes it from siblings like list_subscriptions and unsubscribe, and enumerates supported subscription types, making the tool's purpose unambiguous.

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

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

The description provides clear context for when to use the tool: requires a Pipeworx OAuth account, and explicitly mentions alternative delivery mechanisms (feed can be pulled via recent_alerts or a URL). It does not explicitly name sibling tools for exclusion, but the prerequisites and delivery options give strong 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable context beyond annotations: it is an onboarding entry point, returns categorized examples from the live catalog, and supports no-arg or topic-filtered calls. 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 fairly long, but it is front-loaded with example user queries and each sentence earns its place by explaining the tool's role, return value, parameter usage, and placement in the toolset. Slightly verbose due to the enumerated category list, but justified for an onboarding tool.

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

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

Despite lacking an output schema, the description explains what the tool returns (category-bucketed example questions with tool+argument shape), how to invoke it (no args vs topic), and when to use it (first contact). It does not specify the exact JSON return structure, but for an entry-point tool this is sufficient given the rich context provided.

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

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

The input schema already provides complete documentation for the optional 'topic' parameter, including allowed values, an example, and the behavior when omitted. The description repeats this ('pass topic to focus', examples like 'finance', 'pharma') but adds no new meaning beyond what the schema provides, so it meets the baseline.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It differentiates from siblings like ask_pipeworx by positioning itself as the learning/orientation tool, making its purpose unmistakable.

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and notes it can be used to learn how to call meta-tools, providing clear when-to-use context. It also implies when not to use (when you already have a specific question), effectively guiding selection among 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?

The annotations already declare readOnlyHint and idempotentHint. The description adds useful behavioral context beyond annotations: 'keyless, offline' and the specific reading time rate (200 wpm), which informs the agent about no network dependencies and computation parameters. It does not disclose edge cases or language limitations, but the added details are valuable.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then lists specific statistics. Every phrase adds value, and there is no redundant or filler 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?

The tool is simple (one parameter, no output schema). The description compensates for the missing output schema by enumerating all computed statistics (character counts, word/sentence/paragraph counts, reading time, average word length, longest word). It also includes operational context ('keyless, offline') sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%; the only parameter 'text' is described as 'The text to analyze.' The description does not add additional parameter semantics, such as format constraints, encoding, or length limits. Baseline of 3 is appropriate since the schema already documents the parameter fully.

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 with a specific verb ('Compute') and resource ('text statistics'), and enumerates exactly which statistics are computed. This distinguishes it from siblings like 'readability' by naming specific outputs (reading time, word counts) and the 'keyless, offline' qualifier.

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

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

The description implies usage for any text analysis need but does not explicitly state when to use versus alternatives such as 'readability'. No when-not or alternative guidance is provided. The context is clear enough for a simple utility, but explicit exclusions or comparisons are lacking.

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 important behavioral details beyond the annotations: ownership enforcement and the deactivation (not deletion) behavior. The annotation already indicates destructiveHint=false and idempotentHint=true, but the description adds clarity that the row is deactivated and that historical events stay available via recent_alerts, which is valuable for the agent.

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

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

Three concise, information-dense sentences. Each sentence earns its place: the first states the action, the second explains the ownership constraint, and the third clarifies the soft-delete behavior and its consequence. No redundancy or fluff.

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

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

For a one-parameter tool with helpful annotations, the description is complete. It explains the cancel operation, the ownership rule, and the impact on historical data. No output schema is present, but the agent can infer a successful cancellation from the idempotent and non-destructive hints. The description fully supports correct invocation.

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

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

The input schema has 100% coverage with a clear description for the single parameter id. The tool description simply reinforces 'by id' without adding new meaning, so the schema is already doing the heavy lifting. No extra parameter semantics are needed.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb ('Cancel') and resource ('subscription'), and it distinguishes itself from sibling tools like subscribe and list_subscriptions by describing the cancellation behavior and the soft-delete mechanism.

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

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

The description implies the appropriate use case (cancelling a subscription) and provides useful context about ownership (only cancel your own) and the fact that historical events remain accessible via recent_alerts. While it does not explicitly mention alternatives or when not to use it, the context is clear and sufficiently guides 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds significant behavioral context: how claims are routed between the structured SEC/XBRL path and the grounded pipeline, that it returns a verdict with evidence and reasoning, and that it consolidates 4–6 sequential calls into one. This is far above the annotation baseline.

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 contributes: query examples, routing logic, verdict options, and efficiency benefits. It is front-loaded with usage patterns and avoids filler. A slight trim of the trailing 'Replaces 4–6 sequential calls' could tighten it, but overall it's well-structured and dense.

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

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

Given a moderately complex tool with conditional routing, two parameters, and no output schema, the description is remarkably complete. It explains return values (verdict types, actual value, citation, reasoning), covers both the structured and fallback paths, and even mentions the tolerance semantics. No significant behavioral context is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% for both parameters, but the description adds meaningful semantics beyond the schema. It clarifies that 'claim' is a natural-language statement and explains exactly how 'tolerance_pct' overrides the claim-implied tolerance, including a concrete use case for hallucination detection (set 1–2). This exceeds the baseline for high schema coverage.

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

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

The description opens with concrete natural-language query patterns ('Is it true that…' / 'fact check') and a specific verb + resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by detailing the SEC EDGAR + XBRL fast path for company-financial claims and the grounded pipeline for all other claims.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic (company-financial vs. other factual claims), giving clear context for invocation. It stops short of naming explicit alternatives or when-not-to-use scenarios, so it doesn't earn a 5.

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