nationalize

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context: the default Workers AI model is free, using Anthropic requires a BYO key ('you pay Anthropic directly'), and the tool returns a specific per-model structure plus a combined view. This goes beyond the annotation hints.

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

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

The description is three sentences, front-loaded with the core action, and includes only essential details about defaults, return format, and use cases. Every phrase earns its place with no fluff or redundancy.

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

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

Despite lacking an output schema, the description explicitly lists the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers purpose, defaults, usage scenarios, and cost implications, making it complete for a tool with four straightforward parameters and strong 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 description coverage is 100%, so the baseline is 3. The description restates defaults and the _apiKey relationship already documented in the schema ('workers-ai (free default)', 'anthropic (requires _apiKey)'), adding little new meaning. The only marginal addition is the cost caveat 'you pay Anthropic directly', which is already implied by BYO key.

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

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

The description clearly states the tool's purpose with specific verbs and resources: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' It distinguishes itself from siblings by focusing on model visibility scoring, not just asking questions, and mentions the default model and return structure.

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

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

The description provides explicit usage context with 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It gives clear when-to-use scenarios but does not explicitly mention alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds valuable behavioral context: it routes to one of 5,313 tools, returns 'the structured answer with stable pipeworx:// citation URIs', is 'one fast call', and works on every tier. It does not contradict the annotations.

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

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

The description is long but front-loaded with the most actionable directive ('PREFER OVER WEB SEARCH') and systematically covers purpose, examples, usage policy, and alternatives. Each sentence carries meaningful information, though a few could be tightened without losing value.

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

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

Without an output schema, the description compensates fully by explaining what the tool returns (structured answer with citation URIs), the scope of data sources, concrete usage examples, and step-up alternatives. It also clarifies that it works on all tiers and is the default entry point, giving an agent complete context for selection and invocation.

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

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

Schema description coverage is 100%, and the schema already documents six aliases and the natural-language format of 'question'. The description itself adds little parameter-specific detail beyond examples, but it does reinforce that the input is a natural-language question; this is adequate but not additive given the schema's thoroughness.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and enumerates specific domains (SEC filings, FDA drug data, economic statistics, etc.), making the tool's purpose unmistakable. It also distinguishes itself from siblings by explicitly positioning this as the default entry point versus ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'find', 'get the latest') and concrete examples. It also states when NOT to use it by pointing to alternatives: 'Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part questions use deep_research.'

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds valuable behavioral context: it is an experimental edge, candidates are enabled live when under test, currently no candidate is active so it matches ask_pipeworx, and it is a full working router. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core identity and status. It is slightly longer than needed and the final sentence about 'falls back to nothing' adds some clarification but also mild redundancy, yet all content is relevant.

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

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

For a simple single-question router with full schema and safe annotations, the description covers the current state, experimental behavior, and equivalence to ask_pipeworx. It does not describe the exact response shape, but references the same shape as ask_pipeworx, which is adequate given the shared contract.

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 'question' parameter and aliases fully documented. The description adds no real parameter-specific semantics beyond saying 'same arguments as ask_pipeworx', so the baseline 3 applies.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, describes its role as an identical universal router with the same 5,313 tools, and differentiates it from the stable router by mentioning candidate routing improvements and live comparison. This is specific and distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This provides clear usage context, though it does not state explicit exclusions or 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 mark it read-only and non-destructive. The description adds crucial behavior: it costs an extra LLM call, extracts only from tool result content, and returns explicit refusal reasons (not_in_source, no_tool_match, etc.). This goes well beyond annotation hints.

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

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

Every sentence earns its place: purpose, method, return behavior, usage guidance, and cost trade-off. Front-loaded with the core value proposition, followed by structured return/refusal details. No fluff or repetition.

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

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

Despite having no output schema, the description fully explains the return object, refusal reasons, and use cases. It also compares with the sibling tool and covers cost implications, making it self-sufficient for an agent to decide 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?

All six parameters are aliases for the same question field, and the schema already documents them with 100% coverage. The description adds no extra parameter-level meaning, only mentions that the tool 'fills arguments' internally, 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 uses a specific verb ('extracts the answer') and clearly identifies the resource ('tool result') and mode ('hallucination-resistant answer mode'). It explicitly distinguishes from ask_pipeworx by grounding answers in tool results and providing refusals.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' Directly names the alternative 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 readOnly and idempotent hints, so the description doesn't need to repeat safety. It adds valuable context beyond annotations: the return format ('country codes with probability scores') and the batch limit ('up to 10'), which help set expectations for the agent.

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

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

Two sentences with zero filler. The description front-loads the core purpose and adds the most important limitation (up to 10) and return format. 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?

With a single parameter, full schema coverage, a rich output schema, and annotations covering safety, the description provides enough context for the agent to invoke the tool correctly. It explains what the tool does, how to use it, and what the result contains.

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 parameter already described as 'Array of first names to predict nationality for (maximum 10).' The description essentially repeats this information without adding new meaning, so it stays at the baseline of 3.

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

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

The description uses a specific verb ('Predict') and clearly specifies the resource ('nationalities for multiple first names'). It explicitly distinguishes itself from the sibling tool predict_nationality by highlighting batch processing ('at once', 'up to 10').

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

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

The description states a clear use case: 'Use to process name lists efficiently.' This implies when to use it (multiple names) but does not explicitly mention alternatives or when not to use it. It falls short of a 5 because it lacks an explicit contrast with predict_nationality for single names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return 'market_closed_or_inactive', wide-spread markets are flagged as 'illiquid_wide_spread', and resolution-rule risk is parsed via cancellation_rule. It even warns about inspecting match confidence before trusting analysis. This goes far beyond the annotations.

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

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

The description is quite long but front-loaded with the core purpose and organized into clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds value for a complex tool, though some redundancy exists (e.g., market formats repeated in schema and description). For the complexity, it is well-structured.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly details response shapes (market, analysis, evidence), resolver contract fields, parent_event extraction, news fallback behavior, safety short-circuits, and resolution-rule risks. This is a remarkably complete description for a complex tool.

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

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

Schema description coverage is 100% and the schema itself already explains the market parameter formats, depth enum, and include_raw behavior. The description reinforces these but does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from sibling tools like polymarket_edges or polymarket_arbitrage, and outlines the input forms (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This is a precise, differentiated purpose statement.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear usage context. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, stopping short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds rich behavioral context: it pulls from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is information-dense but well-structured, opening with trigger phrases and then explaining behavior, data sources, output, and efficiency. Every sentence adds value without redundancy, making it appropriately sized 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 the two-type complexity and lack of output schema, the description covers all necessary aspects: use cases, data sources, sorting, output format, and entity limits. It provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description goes beyond by detailing what each type pulls (e.g., company: latest 10-K revenue, net income, cash, debt; drug: FAERS counts, FDA approvals, trial counts). It also provides concrete value examples (tickers/CIKs, drug names), adding useful semantics.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one call, with explicit trigger phrases like 'X vs Y'. It also distinguishes between company and drug types, and contrasts with sequential single-pack lookups, making its purpose unambiguous and differentiated from siblings.

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

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

The description explicitly says to ALWAYS prefer this tool over sequential single-pack lookups when comparing entities, providing clear when-to-use guidance. It also gives example queries and notes that it replaces 8-15 sequential lookups, reinforcing its intended use case.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses account requirements, depth-tier behaviors (gap recovery, lead chasing), gaps[] policy (never invented), contradictions[] output, semantic excerpting, and expected latency. No contradiction with annotations; this exceeds the bar.

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

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

The description is long but every clause adds behavioral or usage context. It is front-loaded with the account requirement and alternative, and the density of information justifies the length. Minor redundancy could be trimmed, but it remains effective.

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

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

With no output schema, the description thoroughly explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, citation_uri, and timing. This fully equips the agent to anticipate return values and nuances.

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?

Even though the schema covers 100% of parameters, the description adds substantial meaning: depth is explained with concrete behavior for each enum value, and question is contextualized as natural-language and broad/multi-part, which goes well beyond the schema text.

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 Pipeworx's 1392 STRUCTURED data sources' and explicitly says it is 'NOT open-web search.' It differentiates from siblings like ask_pipeworx by focusing on broad/multi-part queries and parallel tool routing.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), plus a fallback if not signed in. This is strong guidance 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 readOnly/idempotent safe, so the description adds return format (top-N relevant tools with full schemas and curated examples, no second lookup needed) and domain coverage. This is useful contextual behavior beyond the annotations, though no side effects or quirks are mentioned.

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 a lead sentence defining the action, followed by usage context, return behavior, and a directive to call first. The domain list is lengthy but serves as a concrete illustration of scope; no redundant filler 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?

Covers purpose, usage timing, return value, and domain scope in a compact description. Given the simple read-only nature and comprehensive schema, this is sufficient; minor gaps like no-result behavior or error handling are not critical for this tool type.

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

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

Schema covers 100% of parameters with descriptions, so baseline 3 is appropriate. The description adds no parameter-specific information beyond what the schema provides; it only mentions 'top-N' which relates to the limit parameter, but that's already documented.

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 a clear verb+resource ('Find tools by describing the data or task') and distinguishes from siblings by positioning as the meta-tool to call first when browsing available options, rather than a domain-specific tool. It also lists concrete domains, making its scope unambiguous.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available' – providing clear when-to-use context. However, it doesn't name specific alternatives or when-not-to-use cases, so it stops short of a full 5.

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

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

Beyond the read-only/idempotent annotations, the description discloses key behaviors: it fans out across multiple sources in parallel, returns a specific structure (cik, filings, fundamentals, patents, news, LEI), and includes failure/fallback behavior (patents soft-fail, GDELT→GNews). This is substantial context that helps the agent anticipate results and limitations.

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

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

The description is long but information-dense, with a clear structure: examples, primary directive, source list, returned fields, and parameter guidance. No filler words; every clause adds value. It is appropriately sized for a tool that aggregates many data sources, though it could be slightly tightened.

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

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

Given the tool has no output schema and high complexity, the description fully covers the return shape (fields, counts, URIs), edge cases (patents soft-fail, news fallback), and input constraints (ticker/CIK vs. names). It even mentions the use of resolve_entity for name-only requests, making it complete for the agent to invoke correctly.

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

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

The schema already covers both parameters fully, so a baseline of 3 applies. However, the description adds meaningful nuance by explaining the value parameter accepts ticker or zero-padded CIK, explicitly says names are not supported, and points to resolve_entity as a prerequisite for name-based queries. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool's function: building a full cross-source profile of a US public company. It provides multiple natural-language examples and explicitly differentiates from sibling tools by positioning it as the preferred holistic lookup over chaining single-source calls. It also mentions resolve_entity as the correct tool for name-only inputs, reinforcing its 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 gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion—names are not supported and resolve_entity should be used first—making the decision boundary unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context by explaining why deletion might be done (stale context, task complete, sensitive data) and that it targets 'previously stored memory', which complements the destructive hint without contradiction. It does not describe irreversible consequences explicitly, but the annotation covers the destructive nature—so the description adds useful contextual value beyond the annotation.

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

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

The description is two sentences, front-loaded with the core action, and every word earns its place. It includes both the purpose and usage guidance without unnecessary detail.

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

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

For a simple one-parameter tool with complete schema coverage and annotations, the description addresses purpose, usage, and alternative tools. No output schema is needed, and the description provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%; the schema already documents 'key' as the 'Memory key to delete'. The description reiterates 'by key' but adds no new detail about parameter format or behavior beyond the schema. Baseline 3 is appropriate since the schema fully handles semantics.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It names the specific resource (memory) and the key field, distinguishing it from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

Explicit when-to-use guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also gives pairing advice with 'remember and recall', making choices between sibling tools 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 valuable context by disclosing that the tool fetches the page, extracts content, and emits a markdown text blob. This goes beyond the annotations without contradicting them, providing insight into network usage 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 concise: it leads with the main purpose, briefly explains how it works, states the output format, and lists practical use cases. Every sentence contributes information, with no filler or redundancy.

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

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

Despite lacking an output schema, the description explicitly states the output is 'a single text blob ready to drop at site-root/llms.txt'. It covers the entire workflow (fetch, extract, emit), and, combined with the rich annotations and complete parameter schema, the description is comprehensive for a tool of this simplicity.

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

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

The input schema already provides 100% coverage for both parameters (url and max_links). The description adds minimal new meaning, merely implying 'any URL' and referencing key links. Since the schema documents the parameters thoroughly, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: generating a production-ready llms.txt file for any URL. It uses a specific verb ('generate') and resource ('llms.txt file'), and explains the context (AI crawlers indexing a site). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on other aspects.

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

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

The description provides concrete use cases ('getting a client's site indexed', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'). While it gives clear context for when to use the tool, it does not explicitly state when not to use it or mention alternative tools.

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

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

With readOnlyHint=true and destructiveHint=false, the annotations already establish the safe read-only nature. The description adds useful context beyond this, such as the returned fields (id, type, params, created_at, last_fired_at, fire_count) and the scoping to the caller's subscriptions, which is not in the annotations.

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

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

The description is two sentences: the first states the purpose and return fields, the second explains when to use it. Every sentence earns its place, with no fluff or redundancy, and it is front-loaded with the primary action.

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

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

Despite lacking an output schema, the description lists all returned fields, which is essential for a list tool. It also covers the key usage scenarios and the optional include_inactive flag is documented in the schema. The combination of annotations, schema, and description makes the tool fully understandable.

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

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

The schema has 100% coverage for the only parameter (include_inactive), with a clear description. The tool description adds no additional parameter-specific information, so the baseline of 3 is appropriate because the schema handles parameter semantics fully.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb ('List') and resource ('active subscriptions'). It further distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by noting its use for reviewing monitoring before adding more or finding an id to cancel.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly contrasts with subscribing/unsubscribing, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations provide no safety hints (all false), so the description carries the burden. It discloses rate limiting ('5 per identifier per day'), cost behavior ('Free; doesn't count against your tool-call quota'), and how feedback is consumed ('team reads digests daily', 'signal directly affects roadmap'). It does not describe what response to expect, but for a feedback submission tool this is acceptable. The description adds meaningful context beyond the bare annotations.

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

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

The description is four sentences, front-loaded with the purpose, and every sentence adds value: purpose, use-case examples, content guidelines, and operational characteristics. There is no fluff or redundant information. It is appropriately concise 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 the tool's low complexity, nested schema, and absence of an output schema, the description covers the necessary context: what to submit, how to phrase it, rate limits, and downstream impact. It could mention the return value or confirmation behavior, but that is not essential for a feedback tool. The description is sufficiently complete for this purpose.

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

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

Schema coverage is 100%, providing full descriptions for all parameters. The description adds supplementary guidance beyond the schema by instructing users to describe issues in terms of Pipeworx tools/packs and not to paste the end-user's prompt. It also reinforces the types of feedback mapped to the enum values. This extra context enriches parameter understanding without repeating the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the categories (bug, feature/data_gap, praise) and makes the tool's purpose distinct from sibling tools, which are research/query/memory utilities. This leaves no ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides crucial editorial guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and notes rate limits and cost (free, no quota). This is exemplary usage direction.

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, and non-destructive behavior. The description adds valuable context: it explains data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This goes beyond the annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by use cases and technical notes. Every sentence adds value, and there is no redundant fluff. The length is appropriate for the information conveyed.

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

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

Despite lacking an output schema, the description explains what is returned (top tools, top packs, total call volume) and provides important context like no PII and caching behavior. For a simple tool with one optional parameter, the description is fully complete.

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

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

Schema coverage is 100% and the schema already describes the 'window' parameter with an enum and detailed description. The tool description merely mentions the windows without adding substantially new semantic meaning. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume for what AI agents are calling on Pipeworx. It uses specific verb 'returns' and names the resource (Pipeworx), distinguishing it from sibling tools like ask_pipeworx or 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 'Useful for' scenarios, giving clear context on when to use the tool, such as discovering hot data sources and confirming canonical tools. It does not explicitly name alternative tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial behavioral context: threshold (>3pp), semantic anchor (Jaccard ≥0.30), placeholder filtering, null returns, live CLOB depth pricing, and the meaning of realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is long but well-organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the main call patterns. It is dense but not redundant; the length is justified by the tool's complexity, though a tighter edit could remove some elaboration without losing essential guidance.

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 explicitly lists the response fields: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context, and partition_check subfields. It covers edge cases like placeholder-overloaded partitions, low-similarity pair rejection, and book-vs-last-trade pricing, making the description self-sufficient for an agent to invoke and interpret results.

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

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

Schema coverage is 100% with both parameters already documented, but the description goes well beyond: provides example slugs, accepts full URLs, explains the difference between event and topic modes, and details the filtering logic (e.g., partition filter) that affects interpretation of the parameters. This transforms bare schema entries into actionable guidance.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk by naming the exact methodology and 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?

Explicitly states when to call with no args, when to use 'event', and when to use 'topic', including recommendations ('event (recommended for a specific market)'). It names the alternative tool polymarket_fill_risk for custom sizing and provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'). It also tells the agent when NOT to trade based on fill check results.

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?

Goes far beyond the readOnly/idempotent hints by explaining the response structure, model families, caveats (24h move warning, Fed signal unreliability), caching behavior, diagnostics for empty segments, and how filters affect output. No contradiction with annotations.

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

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

The description is extremely long and dense, mixing essential behavioral context with model internals that may not be needed for invocation. It uses all-caps section headings for organization but still forms a large block of text. While informative, it could be trimmed to improve readability.

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

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

There is no output schema, so the description fully compensates by detailing the response top-level, per-opportunity fields, diagnostics, and caveats. It covers all important aspects including caching and why segments may be empty, making it complete for a complex tool.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so the main description adds little unique meaning. It groups knobs under 'TRADEABLE-EDGE KNOBS' and restates the intent, but the schema already captures the semantics exhaustively.

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 top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes from siblings by focusing on Pipeworx disagreement rather than generic arbitrage or tracking.

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

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

Provides a clear use context: agents discover opportunities without paging hundreds of markets. It also gives configuration guidance (tradeable-edge knobs) and notes about Fed candidates being excluded. However, it does not explicitly name alternative tools or say when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive non-obvious behavioral context: snapshots are written on cache-miss (gaps mean 'nobody scanned that day'), history is bounded by a 60-day TTL, decay is computed from daily closes (not intraday), and net of default slippage. This goes well 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 dense yet well-organized, using labeled sections (Args, RESPONSE, LIMITS) to front-load the core question and then package response fields and constraints. Every sentence adds value—no filler. Length is justified by the complexity of the return structure and edge cases.

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

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

With no output schema, the description fully explains the return shape (tracked[], expired[], snapshot_dates[]) and their semantics, including trend classification (new | widening | stable | decaying) and the 'competition clock' metaphor for lifespan. It also covers limitations (TTL, snapshot availability, calculation basis). This is complete for a read-only telemetry 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 both parameters. The description adds meaningful context: 'days' is explained as lookback with defaults/maxs, and 'window' is clarified as a 'snapshot family' (24hr | 1wk | 1mo), which is not fully evident from the schema alone. It does not need to compensate for missing schema, but adds useful conceptual framing.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges (which likely provides current edges) by focusing on history/trend rather than point-in-time values.

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

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

The description implies when to use the tool by highlighting the difference between a 'fresh wide edge' and a '3-week-old wide edge' as different trades, signaling its value for assessing edge age/decay. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide. A slight deduction for not naming sibling tools explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes far beyond by disclosing detailed behavioral traits: walking the order-book ladder, returning specific fields like vwap_fill_price and slippage_pp, and warning about 'forced_directional_risk' from partial basket fills. It enriches the agent's understanding of side effects and risks 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?

The description is long but tightly structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence contributes necessary information about modes, parameters, return values, or usage context. Given the tool's complexity (two modes, many return fields, multiple risk warnings), the length is justified and the structure keeps it navigable.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so comprehensively: for single-market, it lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket, it lists theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers both modes and the risk scenario, making it complete for the 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%, but the description adds substantial meaning for each parameter. For example, it explains that `market` is for single-market mode, `event` is for basket mode, `side` has mode-specific default behavior, and `size_usd` means 'max spend' for buys vs 'target proceeds' for sells in single-market mode and 'settlement notional' in basket mode. These semantics go far 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 opens with a specific and vivid purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly naming polymarket_arbitrage and polymarket_edges and stating this tool should be used before those trades, establishing a unique role.

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

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

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround and describes the risk of partial basket fills, providing clear context for when to choose 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, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: compatibility_warning trigger conditions, temporal_alignment, matched_pairs and skipped_cross_type logic, and the practical caution that most pre-mapped topics are not tradeable. No contradiction with annotations.

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

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

The description is long but well-structured with TWO MODES, RESPONSE, and SAFETY FIELDS sections. Every part adds necessary context for a tool with no output schema; it is dense but not wasteful.

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

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

For a tool with no output schema, the description fully specifies the response shape (leg-by-leg prices, top_spreads_pp), defines safety fields with concrete trigger scenarios, explains temporal alignment, and covers skip counters. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description enriches parameter meaning by explaining how topic, kalshi_event_ticker, and polymarket_event_slug interact, including explicit override semantics. It also enumerates the topic enum values despite no enum field in 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 opening sentence precisely defines the tool as a cross-venue spread between Kalshi and Polymarket for the same resolving question, which clearly distinguishes it from sibling tools like polymarket_arbitrage. It specifies concrete resources (Kalshi/Polymarket venues) and enumerates two modes with named parameters.

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 vs explicit ticker/slug) and when custom pairings are used, and warns that most pre-mapped topics return compatibility_warning and pre-mapped ≠ tradeable. It does not explicitly name sibling alternatives, but it provides clear context for when the spread is meaningful.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the output format (ranked country codes with probability range), which is not captured by the annotations.

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

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

The description is two sentences, directly states the primary function, and includes critical output details. No unnecessary words or repetition.

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

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

Given the tool's simplicity (single parameter) and the presence of an output schema, the description is complete. It covers purpose, usage, and output format, while annotations cover safety. No additional context is needed.

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

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

Schema coverage is 100%, so the schema fully documents the 'name' parameter. The description does not add additional semantic meaning beyond the schema, but it does reinforce that the input is a first name, matching the schema description. This aligns with the baseline of 3 for full 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 tool's action ('Predict likely nationalities from a first name') and specifies the output (up to 5 country codes ranked by probability). This is a specific verb+resource combination that distinguishes it from other tools in the sibling list.

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 a direct usage instruction: 'Use when inferring someone's origin from their given name.' This provides clear context for when to use the tool, though it does not mention specific alternatives 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 declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it is scoped to the user's identifier and can list all keys if the key argument is omitted. This goes beyond what annotations provide and fully discloses the tool's behavior for a read operation.

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

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

The description is three sentences, immediately front-loaded with the main action, and every sentence adds value—covering retrieval, listing, scoping, and tool pairing. No redundancy or filler.

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

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

Given the tool's low complexity (one optional parameter), strong annotations, and absence of an output schema, the description fully covers what an agent needs to know: behavior, scoping, and relationships to sibling 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?

Schema description coverage is 100% (the only parameter 'key' is fully described as 'Memory key to retrieve (omit to list all keys)'). The description does not add significant new parameter meaning beyond restating the omission behavior, so a baseline score of 3 is appropriate.

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

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

The description clearly states the primary function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from siblings by explicitly pairing with 'remember' and 'forget' and by focusing on retrieval vs. saving or deleting.

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: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives ('Pair with remember to save, forget to delete'), making it clear when this tool is appropriate.

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

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

The description discloses a persistent side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotation readOnlyHint:true, which implies no state changes. The description is transparent about the behavior, but the annotation is misleading, so per the rules this is an annotation contradiction and must score 1.

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

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

The description is three sentences long, dense yet efficient. It front-loads the purpose, then covers return content, filtering, mark_read behavior, and an alternative access method without redundancy. Every sentence contributes unique value, making it concise and well-structured.

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

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

For a tool with no output schema and 5 optional parameters, the description covers all the essentials: return payload structure, filtering options, mark_read side effect, polling suitability, and an alternative endpoint. It is complete enough for an agent to know how to invoke it correctly, aside from the annotation contradiction already penalized.

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 meaningful semantics by giving a concrete type example ("sec_8k") and explaining the consequence of mark_read (affects subsequent calls), which goes beyond the schema's 'Flag the returned events read in the same call'. It does not cover all parameters, but the schema already documents them, so the additional context earns a 4.

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

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

The description opens with 'Pull fired events from your subscription feed', which clearly identifies the action (pull), resource (subscription feed events), and scope (fired events). It further distinguishes itself by detailing what the returned alerts carry (source, citation_uri, raw payload) and how they relate to the evaluator's persisted feed, making it unique among sibling tools like 'list_subscriptions' or 'recent_changes'.

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: it mentions filtering by type and/or since, and explicitly says 'Polls work fine', indicating it is suitable for polling scenarios. It also points to an alternative HTTP endpoint for scripts/dashboards, giving a sense of when this tool is the right choice, though it does not explicitly contrast it with sibling tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and returns pipeworx:// citation URIs. This goes well 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 dense and information-rich, front-loaded with query examples and structured with clauses for sources, fallbacks, and output. It's a long paragraph but every sentence adds value; slightly streamlined structure would earn a 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?

Given the tool's complexity (multi-source aggregation, fallbacks, soft-failures) and no output schema, the description thoroughly covers input syntax, data sources, failure handling, and output structure (changes[], total_changes, citation URIs). It also provides an explicit alternative tool, making it self-sufficient.

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

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

Schema descriptions cover all parameters, but the description adds valuable syntax details: accepted formats for `since` (ISO date or relative like '7d', '30d', '3m', '1y'), ticker vs. CIK for `value`, and the 'company' enum restriction. This enhances understanding beyond schema alone.

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

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

The description clearly specifies the tool returns a change feed for a company over a time window, with concrete natural-language examples ('What's new with X', 'updates on Acme'). It explicitly contrasts with entity_profile, making its purpose distinct from a key sibling.

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

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

It provides clear when-to-use context (recent changes, news, filings in a window) and explicitly names entity_profile as the alternative for static profiles. It also describes fallback behavior and time-window formats, guiding appropriate invocation.

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 (idempotent, non-destructive), the description discloses persistence differences between authenticated and anonymous sessions, and scoping by user identifier. It does not mention overwrite behavior, but this is acceptable for a simple store tool.

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

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

Three sentences, front-loaded with purpose, and each sentence earns its place by adding usage context, storage details, or related tools. No wasted words.

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

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

For a two-parameter tool with annotations, the description covers purpose, use cases, persistence, and related tools. No output schema is needed, and the description is sufficiently complete for an agent to invoke correctly.

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

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

Schema covers both parameters with descriptions and examples, so the description adds little extra. It reinforces key-value semantics but doesn't provide additional format or constraints, warranting the baseline 3.

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

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

Description states a specific verb ('Save') and resource ('data the agent will need to reuse later'), with concrete examples (ticker, address, preference). It distinguishes itself from sibling tools by explicitly mentioning recall and forget as companions, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with examples, and mentions pairing with recall for retrieval and forget for deletion, clarifying 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description adds behavioral context: each call 'cascades through several lookup endpoints internally' and supports 'auto-disambiguated' input. It also describes the output format and citation URIs. While it doesn't cover failure modes or rate limits, it provides substantial value 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 dense but well-structured, starting with example queries, then purpose, usage guidance, and detailed type information. It's longer than the ideal 2-3 sentences but every sentence adds necessary context for a multi-type resolver. Slightly less concise than the best examples, but not wasteful.

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

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

With no output schema, the description must cover return values, and it does: for company it lists ticker, CIK, company_name, and citation URI; for drug it lists RxCUI, ingredient, brand, and citation. It also covers supported input types and disambiguation behavior. The tool is well-scoped and the description adequately covers its context.

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

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

Schema coverage is 100%, but the description goes far beyond the schema. For 'type', it details what each enum value returns (company vs drug). For 'value', it explains accepted formats for each type (e.g., ticker, CIK, or name for company; brand or generic for drug) and gives examples. This significantly enriches parameter understanding 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's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It gives multiple example queries and explicitly distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource and differentiates from siblings.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it 'replaces 2-3 manual lookups,' implying it's preferred over doing lookups manually. However, it doesn't explicitly mention when-not-to-use or name alternative sibling tools, so it misses the full when-not/alternatives 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals process and output details: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds behavioral context not present in 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 three sentences, front-loaded with the primary purpose, then elaborating on workflow and use case. Every sentence contributes meaning without redundancy, making it highly efficient and well-structured.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description fully covers the operation, use case, and return format. It explains the ranking output and what metrics are returned, making the tool self-contained despite lacking an output schema.

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

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

Schema coverage is 100% for all parameters, so baseline is 3. The description adds semantic value by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not stated in the schema. This extra context helps the agent craft correct inputs.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the exact workflow (probes each entity with ai_visibility_check, ranks by score) and distinguishes it from the single-entity sibling ai_visibility_check and the generic compare_entities by focusing on AI visibility.

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

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

The description gives a concrete use case: 'competitive AI-marketing audits' with an example question. It implies the tool is for multi-entity comparison rather than single checks, but does not explicitly exclude alternatives or state when not to use it. This is clear context without formal 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 (readOnlyHint, idempotentHint, destructiveHint=false) already cover safety, but the description adds valuable behavioral context: partial failure degradation, potential 5-30s latency for bundlephobia's first measurement, and the existence of a sources_failed field. This exceeds the baseline and provides concrete operational expectations.

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

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

The description is dense yet well-structured: purpose → use-cases → output summary → ecosystem limitation → failure behavior. Every sentence carries informational weight, and the most important information (purpose) is front-loaded. No fluff or repetition of schema details.

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

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

For a composite tool with no output schema, this description is thorough: it names all 7 return fields, mentions per-advisory detail, links, and alternative versions, and covers edge cases (NPM-only, bundlephobia timeouts). The agent has enough context to set expectations and handle partial results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond the schema; it mentions 'lodash' as an example but does not elaborate on version formatting or edge cases. Since the schema already documents both parameters, no extra value is provided here.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly distinguishes the tool's scope (npm package evaluation) and lists concrete data sources (deps.dev and bundlephobia), making its purpose unmistakable and distinct from any sibling tool.

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

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

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the NPM-only limitation and directs users to deps.dev:version for other ecosystems, effectively acting as an exclusion clause and alternative.

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. The description adds behavioral specifics: overlap windows (500-char), embedding model BGE-base-en, and truncation cap at 200K with a flag. This exceeds what annotations cover, giving the agent expectations about performance and 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?

Four sentences, front-loaded with purpose, then usage, then technical details. No repetition of schema fields; every clause adds new information.

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

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

No output schema, so description explains return values (top-N passages, character offsets, similarity scores). It covers when to use, how it relates to sibling tools, and edge behavior (truncation). Safety profile is provided by annotations. Complete for a tool of this complexity.

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

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

Schema covers all 3 params with descriptions (100% coverage), so baseline is 3. The description adds useful context: clarifies 'text' is 'the text you already pulled', implies 'limit' via 'top-N passages', and reinforces query with examples. It also ties truncation behavior to the text param. This justifies a 4.

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

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

The description opens with 'Semantic search INSIDE a fetched record' – a specific verb+resource with clear scope. It explicitly contrasts with siblings by naming ask_pipeworx_grounded and positioning search_within as the passage-level search complement to whole-document grounding.

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

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

States a clear trigger: 'Use when the record is too big to cram into the prompt' and provides an explicit alternative/pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Also notes saves context and returns only passages that matter.

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=false and destructiveHint=false, so the write nature is known. The description adds useful behavioral details: OAuth account requirement, phone verification, 10/day SMS cap, feed always on, and webhook auto-disable after repeated failures. It does not address idempotency (idempotentHint=true) or duplicate behavior, but the added context goes beyond annotations.

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

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

The description is dense but well-organized: it starts with purpose and return value, then auth requirements, supported types with examples, and delivery channels. Each sentence contributes valuable information. It is longer than minimal, but the complexity of the tool (multiple types, delivery options) justifies the length. Front-loaded with essential facts.

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 (nested objects, 5 types, delivery channels) and no output schema, the description covers the key contextual aspects: return value (subscription id), auth prerequisites, and delivery options. It omits examples for patent_grant and clinical_trial, but these are documented in the schema's params description. The description could be more complete with idempotency details, but overall it is sufficient for a creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by giving concrete examples for types (e.g., items:["5.02"] = officer change, topic:"fed") and clarifying constraints like phone verification and 10/day cap. This adds meaning beyond the schema's enum and field descriptions, enhancing the agent's ability to construct valid parameters.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' which uses a specific verb ('Create') and a clear resource ('subscription'). It distinguishes from sibling tools like list_subscriptions and unsubscribe, and details supported types and delivery channels. This is unambiguous and immediately tells the agent what the tool does.

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

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

The description provides context on when to use the tool: for creating subscriptions, and explicitly notes that a Pipeworx OAuth account is required, with anonymous/BYO excluded. It also mentions pushing alerts via recent_alerts as an alternative consumption method, though it does not explicitly name alternative tools (e.g., list_subscriptions) or state 'when not to use.' This is clear context without explicit 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so safety is covered. The description adds useful context about drawing from a live catalog of thousands of tools and the structure of returned examples, but doesn't go into excessive detail about side effects or authentication, which is acceptable given 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 somewhat long but every sentence contributes useful information. It's front-loaded with common user queries, then explains the output, usage, and when to use. No redundant filler.

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

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

Given the simple schema (1 optional param) and no output schema, the description fully explains what the tool returns and how to use it. It covers the return format (category-bucketed questions with tool+argument shapes) and provides guidance on invocation, making it complete for the agent.

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

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

Schema coverage is 100% for the single optional 'topic' parameter. The description supplements by providing concrete example values ('finance', 'pharma', 'betting') and clarifies that omitting it returns a cross-category spread, adding value beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for suggesting questions about Pipeworx, with a specific list of example query phrasings and output categories. It distinguishes from siblings like ask_pipeworx by emphasizing it returns example questions with exact tool+argument shapes rather than answering directly.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear guidance on when to call with no arguments vs passing a topic, and mentions how it relates to 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavior: the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This adds meaningful context about side effects and data preservation that annotations alone do not provide.

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

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

The description is two sentences long, front-loaded with the primary action, and every phrase earns its place by adding operational detail. There is no wasted verbiage.

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 mutation tool with one parameter, no output schema, and solid annotations, the description covers the key contextual aspects: what it does, ownership, soft-delete semantics, and the relation to recent_alerts. It is fully sufficient for an agent to select and invoke this 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?

While the schema already documents the id parameter well (100% coverage), the description adds the crucial ownership constraint — you can only cancel your own subscriptions — which meaningfully clarifies the valid range of id values beyond the schema's 'returned by subscribe.'

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

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

The description opens with a specific verb+resource: 'Cancel a subscription by id.' This clearly distinguishes it from siblings like subscribe and list_subscriptions, and the added detail about ownership and deactivation further clarifies its exact function.

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

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

The description clearly implies when to use the tool (to cancel a subscription) and conveys the key constraint that you can only cancel your own subscriptions. It does not explicitly list alternative tools or when not to use it, but the context is clear given the sibling set.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description goes well beyond this by specifying the verdict categories (confirmed, approximately_correct, etc.), the tolerance override mechanism, the two execution paths (EDGAR fast path vs. grounded pipeline), and the citation format. This provides rich behavioral context that 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?

Though relatively long, every sentence serves a purpose: it gives trigger phrases, defines the use case, explains routing logic, describes the output, and highlights efficiency. The content is well-organized and front-loaded, with no extraneous or redundant 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 complex with multiple execution paths and a rich output type, and there is no output schema. The description fully compensates by enumerating the possible verdicts, mentioning the citation format, and describing the two routes (structured vs. grounded). It is self-sufficient for an agent to understand what the tool returns and when to use it.

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

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

The schema already provides 100% coverage of both parameters with detailed descriptions. The description adds extra value by giving concrete example claims and explaining tolerance_pct's role in overriding the claim wording, including the suggestion to set 1–2 for hallucination detection. This goes beyond mere schema repetition.

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 natural-language claim verification against authoritative sources, with specific trigger phrases and a defined verdict output. It distinguishes itself from generic research or search tools by focusing on fact-checking and mentioning two distinct routing paths for company-financial versus other claims.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and explains how different claim types are routed internally. However, it does not name alternative sibling tools (e.g., ask_pipeworx_grounded) to use for other scenarios, so there's no 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.