Wiktionary

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds value by detailing the output structure (per-model score, confidence, signals, raw_response, combined view) and explaining that _apiKey is passed directly to Anthropic. 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?

Four sentences with no redundancy. Front-loaded with the core purpose, then details on models and output. Every sentence earns its place.

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

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

Given no output schema, the description adequately explains the return format and typical use cases. Could elaborate on 'signals' or limitations, but is sufficiently complete for a read-only probe tool with clear annotations.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context beyond schema: default model for 'models' parameter (Workers AI Llama-3.3-70b), and that _apiKey is passed straight through to Anthropic. This enhances understanding for the agent.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model and optional Anthropic integration, distinguishing it from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model visibility scoring.

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

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

Provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use which model (default free Workers AI, optional Anthropic with BYO key). However, it does not explicitly exclude cases where alternatives like 'scan_competitor_ai_presence' would be more appropriate.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds that it returns structured answers with stable pipeworx:// citation URIs and works on every tier in one fast call. 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 comprehensive but front-loaded with the key usage directive. Every sentence adds value, and it is well-structured with clear sections and bullet-like examples.

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

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

Given the complexity of the tool (routing to thousands of tools) and no output schema, the description fully explains the purpose, input, output format (citations), and when to use it, making it complete for agent invocation.

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

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

Schema coverage is 100% with clear descriptions for the 'question' parameter and aliases. The description reinforces natural language input and provides examples, adding value but not strictly necessary beyond schema.

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

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

The description clearly states 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists specific domains (SEC filings, FDA drugs, etc.). It identifies the resource (Pipeworx) and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance: 'START HERE for most questions' and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded for hallucination-resistant single answer, deep_research for broad questions). Also advises against web search for certain questions.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the extraction process, the refusal reasons (not_in_source, no_tool_match, etc.), and the return format (answer, evidence, confidence, source, fetched_at, refusal_reason). It fully discloses that the tool may refuse if data doesn't directly answer, adding critical 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 fairly concise given the wealth of information: purpose, behavior, return format, usage guidance, and cost tradeoff. It is front-loaded with the primary purpose. Every sentence serves a purpose, though it could be slightly tighter without losing meaning.

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

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

Despite lacking an output schema, the description fully explains the return format including both success and refusal cases with specific reason strings. It covers the routing mechanism, aliasing of parameters, and the cost tradeoff. For a tool of this complexity, the description is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The parameter descriptions are minimal ('Alias for question') and the tool description adds little beyond stating the question is in natural language. The description does not elaborate on parameter values, formats, or constraints, so it meets baseline but does not exceed.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads. It contrasts with the sibling tool 'ask_pipeworx', stating it uses the same routing but extracts answers only from tool results, and specifies when to use it: for answers that will be quoted, cited, or acted on. This makes the purpose distinct and clear.

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

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

Explicit guidance is provided: use for high-stakes reads when accuracy is critical, and prefer ask_pipeworx for casual lookups. It also discloses the extra LLM cost, helping the agent decide between the two. This is best-in-class 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 declare readOnly, idempotent, non-destructive. Description adds extensive behavioral context: resolver contract, parent event extractor, news fallback, cancellation rule parsing, and statuses for low-confidence/closed/illiquid markets. No contradiction with annotations.

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

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

Description is very long (four paragraphs) with detailed examples and edge cases. Not concise, but well-organized with front-loaded purpose and usage. Could be improved with bullet points or headings.

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

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

No output schema, but description thoroughly explains response shapes (result.market, result.analysis, result.evidence), resolver contract, parent event extraction, news fields, and safety mechanisms. Covers all necessary details for an agent to use the tool correctly.

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

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

Schema coverage 100% with descriptions, but tool description adds crucial context: explains market input formats, depth enum effects (quick vs thorough), and include_raw behavior (summarized vs full payloads). Adds value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifies three types of inputs (slug, URL, question text), and describes the output (evidence packet + comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on individual bet research.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes safety notes for low-confidence, closed markets, wide spreads, and resolution-rule risk, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: correct handling of off-calendar fiscal years, sorting by primary metric, and returning pipeworx:// citation URIs. It does not contradict annotations. A small improvement could be mentioning error handling or rate limits.

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

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

The description is a single paragraph but packs a lot of information efficiently. It uses short phrases and examples. While it could benefit from separate sections for company vs. drug, it is not overly verbose and front-loads key information.

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

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

Given the tool's complexity (two types, multiple entities, different data sources) and no output schema, the description covers essential aspects: what data is retrieved, sorting, and return format (paired data + URIs). It could briefly describe the output structure, but it is largely complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values'. The description adds value by providing concrete examples (e.g., '["AAPL","MSFT"]' and '["ozempic","mounjaro"]') and explaining how the type parameter affects what data is pulled. This enriches understanding beyond the schema.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with clear triggers like 'X vs Y'. It differentiates itself from sequential single-pack lookups and specifies the data sources (SEC EDGAR for companies, FAERS for drugs) and sorting behavior. This provides a distinct and specific purpose.

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 includes an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides natural language examples of when to use the tool and implies not to use for single entities (since minItems=2). This gives clear usage guidance and excludes 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 adds context beyond annotations: account requirement, parallel decomposition of questions, returns verbatim evidence with gaps[], never invents information, and expected 15-60s duration. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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

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

The description is lengthy but well-structured: front-loaded with account requirement and alternatives, then main functionality, examples, caveats. Every sentence adds necessary information for a complex tool; minor verbosity prevents a perfect 5.

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 details the return format (verbatim evidence, confidence, source, fetched_at, stable citation, gaps[]). It covers purpose, usage, behavior, parameters, and fallback scenarios, making it sufficient for an agent to use correctly.

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

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

Schema coverage is 100% for 2 parameters. The description adds value by explaining depth levels (quick=3, standard=5 by default, thorough=8) and clarifying that the question should be broad/multi-part for decomposition. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across 1241 structured data sources, distinguishes from siblings by naming ask_pipeworx for single lookups and breaking news, and explicitly mentions it is not open-web search.

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

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

The description provides explicit when-to-use vs alternatives: use ask_pipeworx for single lookups, prefer ask_pipeworx for breaking news, and account requirements (free tier via GitHub, 'thorough' depth needs paid plan). It also states best use cases for broad/multi-part questions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive nature. The description adds that definitions are 'grouped by part-of-speech sections,' providing some behavioral context. However, it does not disclose behavior for missing words or invalid languages, which would be useful 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 extremely concise (one phrase) and front-loaded. However, it is not a complete sentence, which slightly reduces clarity. Every word earns its place, but it could be more structured as a full 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?

Given the presence of an output schema, the description does not need to detail returns. However, it omits mentioning the core action (look up definitions for a word) and the optional language support. The grouping detail is useful, but overall completeness is adequate with noticeable gaps.

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

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

With only 50% schema description coverage, the description adds no parameter-specific details. It does not explain how 'word' or 'lang' are used, and the parameter descriptions in the schema are minimal. The description fails to compensate for the lack of schema detail.

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 'Parsed definitions grouped by part-of-speech sections' conveys the tool's output and grouping, but does not use a verb+resource format (e.g., 'Get definitions for a word') and could be more specific. It distinguishes from siblings like 'etymology' by mentioning part-of-speech grouping, but the purpose is not as explicit as it could be.

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

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

No guidance is provided on when to use this tool versus alternatives like 'etymology' or 'pronunciations'. There are no when-to-use or when-not-to-use hints, leaving the agent without context for selection.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe and non-destructive. The description adds valuable behavioral context: it returns the 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and provides important information about the output format and readiness for invocation.

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

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

The description is a single paragraph that front-loads the purpose, then provides usage guidance, and finally details the return value. It is well-structured but slightly lengthy. Every sentence adds information, but some redundancy exists (e.g., listing many domains). Still, it is efficient overall.

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

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

Given the tool's role (discovering other tools) and the richness of the input schema and annotations, the description is complete. It covers what the tool does, when to use it, what it returns (top-N tools with schemas), examples of queries, and the fact that results are callable immediately. No output schema is needed because the description explains the return format sufficiently.

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

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

Schema description coverage is 100%, with all parameters documented. The description adds value by providing examples (e.g., 'analyze housing market trends') and clarifying that multiple aliases (task, q, description, search) are accepted. This helps the agent understand how to form valid queries beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a discovery/search tool that returns tool names, descriptions, and full input schemas. The description also lists specific domains (e.g., SEC filings, FDA drugs), providing a clear 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?

The description explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies that this tool is for browsing and discovering available tools, but it does not provide explicit 'when not to use' or alternatives, though the context makes it clear.

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

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

Beyond the provided annotations (readOnlyHint, idempotentHint, etc.), the description adds that the tool fans out across multiple sources in parallel, returns specific data fields, and that patents may soft-fail due to API sunset. It does not discuss rate limits or latency, but the added context is valuable and consistent with annotations. No contradiction.

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

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

The description is moderately long but well-structured: example queries first, then explanation of sources and return fields, then input constraints. Every sentence adds value, though a small trim could make it more concise. It is front-loaded with the core purpose.

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 main outputs (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and inputs thoroughly. However, since there is no output schema, the description does not specify the exact structure of the returned data (e.g., JSON object shape). Given the tool's complexity, this is a 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?

Input schema has 100% coverage with descriptions for both parameters, providing baseline 3. The description adds specificity: value must be a ticker or zero-padded CIK, and names are not supported. This extra detail about the exact format and the note to use resolve_entity for names goes beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call', with specific examples and differentiation from chaining separate tools. It names the resources (SEC, XBRL, USPTO, news, GLEIF) and explicitly distinguishes itself from siblings like deep_research and single-source 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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity if only a name is available, and notes that patents may soft-fail. This clearly separates when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds only that it extracts from wikitext, which is useful but does not significantly expand behavioral 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?

A single, front-loaded sentence with no wasted words. It is appropriately concise for a simple tool, though it may be too brief given the lack of parameter descriptions.

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 2 parameters, no schema descriptions, and an output schema not mentioned, the description is too minimal. It does not explain the output or provide contextual details, leaving gaps for agent 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 description coverage is 0%, so the description should compensate. However, it lacks any explanation of the parameters 'word' and 'lang', such as default language or accepted formats. The examples provide some guidance, but the description itself adds no 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 'Etymology section extracted from wikitext' clearly indicates the tool retrieves etymology information from wikitext. The verb 'extracted' and resource 'etymology section' are specific, and the tool is distinct from siblings like 'definition' or 'pronunciations'.

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

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

No guidance on when to use this tool versus alternatives, or when not to use it. The description is purely functional and does not provide contextual cues for selection.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds that it deletes a memory, which is consistent. It does not reveal additional side effects, but for a simple deletion operation this is sufficient. No contradiction with annotations.

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

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

Two concise sentences with no fluff. The first sentence front-loads the purpose, and the second provides usage guidance and sibling links. Every word earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers all essential aspects: what it does, when to use it, and how it relates to other tools. No gaps given the annotations and schema richness.

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 'key' parameter described as 'Memory key to delete'. The description does not add additional meaning beyond the schema; it merely restates 'by key'. Baseline is 3 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 the action ('Delete') and the resource ('previously stored memory by key'). It also distinguishes from siblings by explicitly mentioning 'Pair with remember and recall', showing it is the inverse of those tools.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also names alternatives (remember and recall), guiding the agent to the correct tool for each operation.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the process and output form. No contradiction with annotations; the description complements them well.

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

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

The description is three sentences with no wasted words. It starts with the action and purpose, then explains the process, and ends with use cases. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Given no output schema, the description adequately explains the output: 'Output is a single text blob ready to drop at site-root/llms.txt.' It covers input (url, max_links), process, output, and use cases. For a simple tool, this is complete and sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with both parameters described in the schema. The description mentions 'Url' implicitly and restates max_links default/max from the schema. It does not add new semantic information beyond what the schema already provides, so it meets the baseline but does not exceed.

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 action ('Generate a production-ready llms.txt file') and resource ('for any URL'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the specific llms.txt format output. The verb 'generate' is specific and the purpose is immediately understandable.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly mention when not to use or compare to alternatives, but the use cases are clear and sufficient for most agents to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of listing active subscriptions adds minimal behavioral context. 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?

Two sentences, front-loaded with the essential action, and every word adds value. No unnecessary information.

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

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

The tool is simple with one optional parameter and no output schema. The description adequately covers the purpose, return fields, and usage context, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with the parameter description already present. The description's mention of 'active' implies default exclusion of inactive, but it does not add significant meaning beyond the schema.

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

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

The description explicitly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the return fields, clearly distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use it but does not explicitly mention when not to use it or 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?

Discloses rate-limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily which affects roadmap. Adds significant behavioral context beyond annotations, which are mostly false/neutral.

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

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

The description is concise, with about four sentences that front-load the purpose and provide essential guidelines. No unnecessary words, and each sentence adds value.

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

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

Given no output schema, the description adequately explains the outcome (digest, roadmap impact) and constraints (rate limit, quota). It is complete for a feedback submission tool, covering input, behavior, and expectations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the type enum with examples, clarifying the optional context structure, and advising on message content and length. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: sending feedback to Pipeworx about bugs, feature requests, or praise. It distinguishes itself by listing specific use cases and is unique among sibling tools.

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

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

Explicitly describes when to use the tool for bug, feature/data_gap, or praise. Provides guidance on what to include (specific tools) and what not to include (end-user prompt). Mentions rate limits but does not explicitly state when not to use it, though context implies it's for feedback only.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable context: the data source (CF analytics-engine), no PII, and caching behavior (5min-1h depending on window). This goes beyond what annotations provide.

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

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

The description is a single paragraph starting with the core action. Every sentence adds value (use cases, data source, caching). It could be slightly more concise, but it's well-structured and informative.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is fully complete. It covers what it returns, why it's useful, how it's derived, privacy, and caching. No gaps.

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

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

Schema coverage is 100% with the 'window' parameter fully described (enum, description). The description adds extra nuance by explaining that shorter windows show current hotness and longer windows show steady-state demand, enriching the meaning beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a window. It lists three specific use cases (discovery, confirmation, alignment), making the purpose explicit and distinct 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 contexts for use: discovering hot data sources, confirming canonical choices, and checking alignment. It implies when to use shorter vs longer windows. Does not include explicit when-not-to-use or alternative tools, but the guidance is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it details the internal checks (monotonicity, partition sum, Jaccard similarity, placeholder filtering, fill check) and warns against trading when realizable edge is non-positive, all consistent with annotations.

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

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

The description is comprehensive and well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but it is relatively long (approximately 250 words). While every sentence adds value, a slightly more concise version could improve readability without losing information.

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

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

Given that there is no output schema, the description provides a detailed explanation of the response structure (opportunities array with fields, partition_check in event mode). It covers the tool's logic, modes, and edge cases, making it sufficiently complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds meaningful context beyond the schema: it explains that event accepts full URLs, specifies recommended usage, and describes how topic triggers cross-event scanning. This adds value beyond the schema's basic descriptions.

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

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

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

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

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

The description provides explicit guidance on when to use each mode: call with no args for trending_scan, pass event for a specific market, or topic for cross-event scanning. It also explains when not to trade based on fill check results and directs to polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses detailed behavioral traits: internal model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation formulas, slippage handling, Kelly fraction caps, 24h-move warnings, and caching policy (1h at KV level). It also explains why certain segments may be empty and provides diagnostics. 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 verbose, containing highly technical details (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio', 'favorite-longshot bias correction with per-sport α'). While informative, it could be more concise by separating core usage from model internals for better readability.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure: top-level fields (by_segment, fed_candidates, _diagnostics) and each segment's content (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). It also covers edge details (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning). The description is comprehensive for a complex tool with 9 parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing usage context for parameters (e.g., slippage_pp mentions 'zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade') and practical recommendations (e.g., 'Set to 2 to require tight books'). This exceeds the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scanning and returning opportunities), and the core logic (disagreement with market price). This effectively distinguishes it from siblings like 'polymarket_arbitrage' by focusing on edge detection driven by Pipeworx data.

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 the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on configuring tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) and explains when to adjust them. However, it does not explicitly mention when to prefer sibling tools, though the context implies this is the primary edge scanner.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: limitations on history depth (60-day TTL, snapshot start time), decay computation (daily closes, not intraday), and the structure of the response (tracked, expired, snapshot_dates). No contradictions with annotations.

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

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

The description is detailed and well-structured, starting with purpose, then explaining response fields, and ending with limits. Every sentence adds value, though it is somewhat long. It could be slightly more concise without losing information.

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

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

Given no output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]) and provides context on limits and computation. It is complete and sufficient for an agent to understand what the tool returns and its behavioral characteristics.

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

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

Schema coverage is 100% with both parameters described. The description adds extra context: 'days' has default 14, max 30 (though schema says clamp 2-30, slightly inconsistent), and 'window' lists accepted values (24hr, 1wk, 1mo) with default 1wk. This adds value beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering how long an edge has existed and if it is shrinking. It specifies the resource (polymarket_edges snapshots) and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides clear usage context: for assessing edge age and decay, contrasting fresh versus old edges. It implies when to use (when historical context is needed) and contrasts with polymorphic_edges, but does not explicitly state when not to use or list alternative tools beyond the contrast.

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

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

Beyond annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses that the tool requires one of market or event, defaults and clamping for size_usd, and the meaning of size_usd in each mode. It also warns about risks of partial fills, which annotations do not cover.

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?

Despite length, every sentence is informative. Use of all-caps headings (SINGLE-MARKET, BASKET) and clear bullet-like return fields makes scanning easy. No fluff.

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

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

For a tool with no output schema, the description thoroughly lists all return fields for both modes, explains the verdict, and highlights risks (thin books, partial fills). Given complexity, this is remarkably complete.

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

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

Schema already describes all parameters (100% coverage). The description adds value by explaining side behavior per mode, size_usd interpretation ('max spend on buys, target proceeds on sells' for single-market, 'settlement notional' for basket), and default/clamp values. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes two modes (single-market and basket) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their signals.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (partial basket fills create unhedged directional positions) and gives mode-specific instructions.

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

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

The description adds rich behavioral context beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It details compatibility_warning conditions, temporal alignment checks, and skipped cross-type/subtype counters, explaining when spreads are meaningful and when they are not.

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

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

The description is comprehensive and well-structured with sections for modes, response, and safety fields. It is somewhat long but every sentence adds value; front-loaded with purpose and modes.

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

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

Given the complexity of cross-venue spread computation and the lack of an output schema, the description thoroughly covers return values, safety fields, and edge cases. It explains compatibility checks, temporal alignment, and leg matching, making it complete for an agent to understand tool behavior.

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

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

Schema coverage is 100%, and the description adds semantic meaning by explaining the two modes and how explicit parameters override topic-mapped ones. The schema descriptions are already informative, but the text adds context like 'overrides the topic-mapped side'.

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 the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue comparison.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics currently return compatibility_warning, guiding users when the tool may not produce valid spreads. However, it does not explicitly compare with sibling tools for when to use this over similar ones.

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 'extracted from wikitext' which hints at source but adds minimal behavioral context beyond annotations. No contradiction.

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

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

The description is extremely short (one sentence) and front-loaded, but it under-specifies the tool's functionality and parameters. Conciseness is not an asset when missing critical information.

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

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

Given two parameters with zero schema descriptions and an output schema (not hidden), the description should explain input expectations. It does not, leaving the agent uncertain about required inputs (lang optional, word required). Incomplete for effective tool selection.

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 0%, so the description must compensate for parameter meaning. It does not explain 'word' or 'lang' (e.g., language code, format). Falls short of providing needed semantic context.

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

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

The description clearly states the tool provides IPA/phonetic transcriptions extracted from wikitext, which is a specific verb+resource purpose. It naturally distinguishes from sibling tools like definition or etymology.

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

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

No guidance is provided on when to use this tool vs alternatives (e.g., definition, etymology). The description simply states functionality without context or exclusions.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds valuable context about scope (anonymous IP, BYO key hash, account ID) and pairing with sibling tools, enhancing transparency 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?

Three sentences, each serving a purpose: core function, use cases, and scope/partners. No redundancy, well 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?

Covers retrieval behavior, examples, scope, and sibling tools. Lacks details on return format or error handling, but given schema coverage and annotations, it is sufficiently complete for a simple read 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%, but description adds meaning by explaining the dual behavior: supplying a key retrieves a value, omitting it lists all keys. This goes beyond the schema's description.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with explicit mention of pairing with remember and forget. It distinguishes from siblings by explaining the role in saving/retrieving/deleting context.

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

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

Provides clear context: use when you need previously stored information, and omit key to list all keys. It implies not to use if nothing was stored, but lacks explicit alternative suggestions or when-not criteria.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds valuable behavioral details: it returns specific fields, explains the effect of mark_read (flags events read so next call shows newer ones), and confirms polling works fine. 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 compact yet thorough, front-loading the main action and returning fields, then covering filtering and behavioral options. Every sentence adds value with no redundancy or fluff.

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

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

Given 5 parameters and no output schema, the description adequately explains the input parameters (especially type, since, mark_read) and mentions key return fields. It lacks explicit mention of limit and unread_only behavior, but these are covered by the schema. Overall, it provides enough context for effective use.

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

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

Schema has 100% coverage with descriptions for all 5 parameters. The description adds meaning beyond schema by synthesizing usage: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp). Set mark_read:true to flag returned events read…' It provides examples and explains the consequence of mark_read, though it does not mention limit or unread_only.

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 pulls fired events from the subscription feed, specifying the returned fields (source, citation_uri, raw event payload). It distinguishes itself from siblings by focusing specifically on alerts from the evaluator's feed, which is a unique resource among the sibling tools.

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

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

The description provides clear context on when to use the tool (to access recent alerts from the subscription feed) and mentions an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' However, it does not explicitly contrast with sibling tools or provide exclusions.

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

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

Annotations already declare read-only, open-world, and idempotent. Description adds transparency on multi-source fan-out, fallback logic, and return structure (changes grouped, total count, URIs), which goes beyond annotations 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?

Single paragraph is dense but effective. Front-loads purpose with example queries. Could be slightly more structured with bullet points, but every sentence adds value without redundancy.

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

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

Given 3 required parameters, 100% schema coverage, and no output schema, the description explains multi-source behavior, fallback, and return structure. Lacks explicit pagination or limits, but adequate for a change feed 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% for 3 parameters. Description adds value by explaining `since` accepts ISO or relative with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m'. Also clarifies `value` can be a ticker or CIK, and `type` is restricted to 'company'.

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

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

The description clearly states the tool provides a change feed for a company, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and when to use it ('What's new with X'). It distinguishes from sibling tool entity_profile by noting when to use that instead.

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

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

Explicitly provides when-to-use examples, fallback behavior (GDELT→GNews), soft-fail for USPTO, and directs to entity_profile for static profiles. Also guides on `since` parameter format and typical monitoring values.

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

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

The description explains the key-value store nature, scoping by identifier, and persistence differences (authenticated vs. anonymous). This adds significant context beyond the annotations, which already indicate idempotent and non-destructive behavior with no contradiction.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence adds value, and it avoids superfluous information.

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

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

Given the tool's simplicity and the richness of the schema and annotations, the description is complete. It covers purpose, usage, scope, persistence, and companion tools.

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% description coverage with examples. The description adds general usage context but no new parameter-specific details beyond what's in the schema. A score of 4 reflects that the description complements the schema 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 purpose: saving data for reuse across conversations/sessions. It lists specific examples (resolved ticker, target address, user preference) and distinguishes from siblings recall and forget.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and how it pairs with recall and forget. It also differentiates persistence based on authentication status, providing clear context for usage.

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

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

The description goes beyond the annotations by revealing that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups. It also specifies the exact return fields for each entity type, including citation URIs. This adds significant transparency about internal behavior and output format.

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 efficient. It opens with concrete examples, clearly separates the supported types with bullet points, and avoids redundancy. Every sentence contributes value, such as explaining the internal cascade and the scope of replacements.

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 two entity types, multiple input options, and lack of output schema, the description covers all necessary behavioral and return details. It explains how to use the tool, what results to expect (including fields and citation URIs), and why it is efficient (replaces 2-3 lookups). This is comprehensive for a resolution 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 defines both parameters with 100% coverage. The description adds meaningful semantic context: it explains acceptable input formats for 'value' (ticker, CIK, name for company; brand or generic name for drug) and elaborates on what each 'type' returns. This enriches the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical identifier. It provides specific examples like 'What's the ticker for...' and 'find the CIK for...', making the action and resource explicit. It distinguishes itself from sibling tools by emphasizing this is the first step when an ID is needed, which sets it apart from tools like 'entity_profile' or 'compare_entities' that operate on already-resolved entities.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID', providing clear context for when to use the tool. It also details supported entity types and their input formats. However, it does not explicitly state when NOT to use it or mention alternative tools for specific cases (e.g., if the ID is already known), which would strengthen the guidelines.

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

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

Description explains it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and description adds behavioral context beyond annotations.

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

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

Two sentences plus a parenthetical example, no wasted words, purpose 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?

Given complexity (multi-entity, internal tool, output format), the description covers purpose, behavior, usage, and parameter semantics. No output schema but output is described sufficiently.

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

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

Schema coverage is 100% but description adds value: clarifies that the first entity in the array is the subject and rest are competitors, which is not in schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check probes, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

Explicitly says 'useful for competitive AI-marketing audits' and provides an example question. Does not explicitly mention when not to use or alternatives, but context implies usage for multi-entity comparisons.

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

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

The description adds significant behavioral context beyond annotations: explains partial failures, bundlephobia timing (5-30s), and the sources_failed field. Annotations already indicate readOnly and idempotent, but the description enriches understanding of real-world behavior.

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

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

The description is a single paragraph but tightly written with no fluff. It could benefit from bullet points for the return fields, but front-loads purpose and usage well.

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

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

Despite no output schema, the description fully explains return values: summary block, advisory details, links, alternative versions, and partial failure behavior. For a 2-parameter tool, this is complete.

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

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

Schema coverage is 100% with both parameters described. The description adds extra meaning: package accepts scoped names, version defaults to latest. This goes beyond the schema definitions.

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

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

The description clearly states the tool scans an npm package dependency, performing a composite check across deps.dev and bundlephobia. It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on npm package evaluation.

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

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

The description explicitly states when to use the tool: when an agent asks about safety, popularity, or size of an npm package. It also specifies exclusions: NPM only in v1, and mentions alternative tools for other ecosystems (e.g., deps.dev:version).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context, such as result ordering or handling of no results. No contradiction with annotations.

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

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

Description is a single short sentence, which is concise but lacks structure and important details. It does not use a typical verb-driven format for tool descriptions.

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 an output schema present, return values are covered. However, the description omits context on search behavior (e.g., fuzzy matching, case sensitivity, result limits), making it incomplete for a complex search tool among many siblings.

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

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

Schema coverage is 33% (only limit has description). The tool description does not explain the 'lang' parameter or the exact nature of the 'query' parameter beyond 'title + fulltext'. Does not compensate for low schema coverage.

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

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

Description states 'Wiktionary title + fulltext search', which indicates the tool searches Wiktionary. However, it lacks specificity about what is returned (e.g., list of articles, snippets) and does not differentiate from sibling tools like 'search_within'. The purpose is clear but vague.

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

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

No guidance on when to use this tool versus alternatives like 'deep_research' or 'search_within'. The description does not mention use cases, prerequisites, or exclude scenarios.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate safety. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that passages return offsets for verification. No contradiction.

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

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

Concise yet richly informative. Front-loaded with purpose and key differentiator. Every sentence adds value: use case, pairing, technical detail. No wasted words.

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

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

Despite no output schema, description explains return format (passages with offsets and scores), cap behavior, and embedding model. For a 3-param tool, this is thorough. Also addresses sibling relationship and practical use case.

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

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

Schema covers all 3 parameters with descriptions. Description adds context by explaining how parameters affect the search (e.g., limit returns top-N passages with similarity scores). It also gives examples for query, enhancing usability. The repetition of char cap for text is acceptable reinforcement.

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 performs semantic search inside a fetched record. Distinguishes from siblings like 'ask_pipeworx_grounded' and provides concrete examples (SEC 10-K, article). The verb 'search within' plus resource 'source' is specific.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and pairs with 'ask_pipeworx_grounded'. No ambiguity about 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?

Discloses write operation (creates subscription), returns subscription id, details delivery channels with rate limits (SMS 10/day cap), webhook auto-disable after 10 failures, and OAuth requirement. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, etc.).

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

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

Description is well-structured and front-loaded with main purpose. While somewhat lengthy, every sentence adds value. Minor conciseness loss due to long sentences but overall efficient.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers all aspects: types, parameters, delivery, OAuth requirement, rate limits, and behavioral caveats. No apparent gaps.

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

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

With 100% schema coverage, description adds rich context: explains each type-specific params object with examples (sec_8k, polymarket_edge, fred_series) and delivery constraints (email, SMS, webhook with signatures). Provides far more than the schema alone.

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

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

Description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and lists supported types and delivery channels. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Describes when to use the tool (creating subscriptions) and mentions a prerequisite (Pipeworx OAuth account) and constraints (anonymous+BYO cannot persist). However, it does not explicitly compare with alternatives or say when not to use it.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds that results are 'drawn from live catalog' and 'category-bucketed', providing valuable behavioral context beyond annotations.

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

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

Well-structured with front-loaded examples and clear explanation. Slightly verbose but each sentence contributes value. No superfluous 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?

With one optional parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage, parameter behavior, and context. No gaps remain.

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

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

Schema has 100% coverage with a description for topic. Description clarifies the optional nature, lists example values, and explains behavior when omitted (full spread) vs. specified (focused). Adds meaning beyond bare schema.

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

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

The description clearly states the tool returns categorized example questions with exact tool+argument shapes, explicitly distinguishing it as the onboarding entry point from siblings like ask_pipeworx.

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

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

Explicitly states usage: 'Use this FIRST when you do not yet know what Pipeworx can do'. Provides clear context and optional topic argument, but lacks explicit when-not-to-use guidance.

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

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

Adds context beyond annotations: specifies API (Wiktionary REST), return fields (title, extract, thumbnail), and default language. Annotations already provide readOnlyHint, etc., and description does not contradict them.

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

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

Single sentence, front-loaded with main action, includes key details (language subdomain, default). No wasted words, highly efficient.

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

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

Given output schema exists, return values need not be detailed. Description covers purpose, parameters, and what is returned (title, extract, thumbnail) adequately for a simple 2-parameter 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?

Adds some meaning: 'lang' is described as language subdomain with default en, 'word' is the word to fetch. However, with 0% schema description coverage, it does not fully compensate; e.g., valid lang values or format are not specified.

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

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

Clearly states the verb 'fetch', resource 'Wiktionary REST page summary', and scope 'for a word on the specified language subdomain'. Distinguishes from sibling tools like 'definition' which likely provide full definitions.

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?

Indicates when to use: to get a summary with title, extract, thumbnail. Notes default language (en) and ability to specify language. Does not explicitly state when not to use, but context of siblings implies alternatives for full definitions.

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

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

The description adds significant behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the exact effect and side effects, which annotations (idempotentHint=true, destructiveHint=false) do not fully cover.

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

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

The description is extremely concise with two sentences that front-load the main action and then provide critical behavioral notes. No wasted words.

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

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

For a simple tool with one parameter, full annotation coverage, and no output schema, the description covers all necessary context: action, ownership constraint, and behavioral effect (deactivation vs deletion).

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

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

Schema description coverage is 100%, with the single parameter 'id' fully described in the schema. The description adds no further parameter details, so baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id.' This specifies a clear verb (cancel) and resource (subscription), and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly notes ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear guidance on when to use the tool, though it does not explicitly mention alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) plus description provide comprehensive behavioral context: describes return value (verdict types, structured form, actual value with citation, percent delta) and explains efficiency gains over sequential calls.

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-organized, starting with usage patterns followed by domain, return details, and efficiency note. It is slightly lengthy but every sentence adds value.

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

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

Given a single parameter, no output schema, and rich annotations, the description fully covers purpose, input format, domain, return values, and use cases, making it complete for effective tool selection and invocation.

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

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

Schema coverage is 100% with a single 'claim' parameter. The description adds value by providing natural-language examples (e.g., 'Apple's FY2024 revenue was $400 billion') that illustrate acceptable input 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 clearly defines the tool's purpose with natural-language examples ('Is it true that...', 'fact check'), specifies it verifies claims against authoritative sources, and narrows the domain to company-financial claims for US public companies. It differentiates from siblings by stating it replaces 4-6 sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain. While it does not list when NOT to use or provide explicit alternatives, the guidance is clear and sufficient.

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