Monday

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

The description discloses critical behavioral traits beyond annotations: the default free model, the requirement of a paid API key for Anthropic, the per-model response structure (score, confidence, signals, raw_response), and a combined view. This adds significant value over the readOnlyHint, idempotentHint, and openWorldHint 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 long, front-loaded with the main action and outcome. Every sentence adds distinct value: purpose, default behavior, optional parameter behavior, and use 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?

The description covers purpose, usage, parameters, costs, and output structure. It lacks explicit error handling or rate limits, but given the tool's simplicity and read-only nature, the provided information is sufficient for an agent to use it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context: which models are available, that workers-ai is free, that Anthropic requires _apiKey, and that context helps disambiguate. This enhances 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 probes LLMs for knowledge about an entity and returns a visibility score (0-100). It specifies the default model and optional Anthropic model, distinguishing it from sibling tools like ask_pipeworx or compare_entities that serve different purposes.

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

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

The description explicitly states the tool is useful for 'AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear usage context. However, it does not explicitly exclude scenarios where alternatives might be better, but the sibling list and tool purpose naturally differentiate it.

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

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

Annotations already declare readOnlyHint and destructiveHint, but description adds behavioral context: routes to 3,751 tools, fills arguments, returns structured answers with stable citation URIs. No contradictions.

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

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

Well-structured with key message front-loaded, includes examples and domain list. Slightly long but every sentence adds value. Could be tighter but 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?

For a tool with no output schema, description explains return format (structured answer with citation URIs) and routing behavior. Missing error handling, but overall adequate for its complexity.

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

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

Schema coverage is 100% with all 7 parameters described. Description does not add additional semantics beyond what the schema provides, so baseline of 3 applies.

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

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

Clearly states the tool is for factual questions about current/historical data from many sources, gives specific verb phrases like 'routes the question' and 'returns structured answer', and distinguishes from siblings by being a general question-answering router.

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 'PREFER OVER WEB SEARCH' and lists many use cases and example queries. Provides strong positive guidance, but does not explicitly exclude when not to use or differentiate from ask_pipeworx_grounded.

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

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

The description adds behavioral context beyond annotations: it costs one extra LLM call, returns structured responses with refusal reasons, and only uses tool result content. Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description does not contradict annotations and provides useful details, though it could mention rate limits or authentication needs.

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

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

The description is moderately lengthy but every sentence adds value: it states purpose, process, output format, use cases, and cost trade-off. It could be slightly more concise but is well-structured with no fluff.

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

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

Given the tool's complexity (routing across many tools/sources), the description explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal reasons, compensating for the lack of output schema. It also differentiates from the sibling 'ask_pipeworx'. It does not fully detail when data truncation occurs, but overall complete for high-stakes scenarios.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters with aliases. The description adds no additional parameter semantics beyond noting that the routing is 'same as ask_pipeworx', which implies similar parameter handling. Baseline 3 is appropriate as 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 defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb ('ask') and resource ('Pipeworx Grounded'). It explains the process of routing, argument filling, and answer extraction using only tool result content, distinguishing it from the sibling 'ask_pipeworx' by emphasizing the grounded nature and refusal mechanisms.

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 usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also states when to prefer the alternative 'ask_pipeworx' ('prefer ask_pipeworx for casual lookups'), making the decision context 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?

The description goes far beyond annotations, detailing low-confidence match handling, closed market responses, wide spread warnings, cancellation rule parsing, and fallback behavior for news sources. It instructs the agent to inspect resolver fields before trusting analysis, showing high transparency.

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 sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the main purpose. Every sentence adds value given the tool's complexity, though slightly more conciseness could be achieved.

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 (result.market, result.analysis, result.evidence, resolver fields, parent_event, news fields, safety blocks). It covers all edge cases and necessary details for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, and the description adds significant meaning: examples for market input, explanation of depth enum (quick vs thorough), and include_raw behavior (default false to keep responses small, true for full payloads). This exceeds what the schema alone provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies verb (research), resource (Polymarket bet), and action (resolve, classify, fan-out, return evidence). It distinguishes from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) which focus on other aspects.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear use cases. It also gives classifier examples and fan-out examples, but does not explicitly state when not to use it or list alternatives.

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

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

Annotations already indicate read-only, open world, idempotent, non-destructive. Description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), special handling of fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is fairly long but every sentence adds value. It front-loads the core purpose and usage examples. Could be slightly more concise (e.g., combine some examples), but overall efficient 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?

Given no output schema, the description explains the return format ('paired data + pipeworx:// citation URIs per entity'). It covers both entity types thoroughly, including revenue/numerical data for companies and adverse event counts for drugs. Completes the picture for agent decision-making.

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

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

Schema coverage is 100%, but description adds meaning beyond enum constraints: e.g., 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt' and 'type="drug" pulls FAERS adverse-event counts'. This clarifies the data returned for each parameter.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, listing specific data pulled (financials for companies, adverse events for drugs). It uses concrete verb phrases like 'ALWAYS PREFER' and distinguishes from sibling tools like entity_profile by emphasizing efficiency.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides clear when-to-use context (comparison, ranking) and implies alternatives (sequential lookups). No exclusions needed.

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 crucial context: decomposition, parallel execution, grounded answers with citations, explicit 'gaps' for unanswered facets, and no invented data. It also discloses authentication needs and plan tiers.

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, starting with the core value proposition, followed by mechanics, examples, and prerequisites. While slightly verbose, every sentence adds value. Could be trimmed slightly, but remains clear and 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?

Given the tool's complexity and lack of output schema, the description thoroughly explains what the tool returns: a structured findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, plus explicit gaps. It covers all behavioral aspects for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining the depth values (quick=3, standard=5, thorough=8) and that the question can be broad/multi-part. This clarifies parameter semantics 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 performs 'Grounded multi-source research in ONE call' and explains how it decomposes questions into sub-questions, routes them to thousands of tools in parallel, and returns structured findings. It distinguishes itself from sibling 'ask_pipeworx' by specifying use cases.

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 advises using this tool for broad or multi-part questions, and directs users to 'ask_pipeworx' for single lookups. Also mentions prerequisites (Pipeworx account) and plan limitations ('thorough' depth requires paid plan).

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, destructiveHint=false. Description adds that returns top-N relevant tools with full schemas, ready to call directly. Adds useful behavioral context beyond annotations.

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

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

Description is front-loaded with purpose and usage, each sentence adds value. Slightly verbose but efficient overall. No wasted words given the amount of 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 no output schema, description covers when, how, and what to expect. Annotations provide safety. For a discovery tool this is complete and enables correct invocation.

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

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

Schema coverage is 100%, so baseline 3. Description adds no additional meaning about parameters beyond what schema provides; it mentions aliases but that is redundant. No compensation needed.

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

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

The description uses a specific verb 'Find tools by describing the data or task' and clearly distinguishes from sibling tools by stating it is for browsing/searching the tool set, not for answering directly. It lists many example domains.

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

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

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and alternatives.

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

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

While annotations provide readOnlyHint, openWorldHint, etc., the description adds extensive behavioral details: it fans out across SEC, XBRL, USPTO, news, GLEIF; mentions patent API sunset and soft-fail behavior; describes return structure with specific fields and URIs. This goes well beyond annotations.

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

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

The description is long but front-loaded with examples and structured logically. Every sentence adds value, though it could be slightly more concise without losing necessary 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?

Given no output schema, the description thoroughly explains the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers all major components needed 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%, so baseline is 3. The description reiterates the schema's parameter constraints (type: only 'company', value: ticker or CIK) but adds no new information beyond what the schema already provides.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and gives example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings by explicitly advising to prefer this over chaining single lookups.

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

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

Provides explicit when to use: 'when the user asks for a holistic view'. Also gives when-not-to-use: 'ALWAYS PREFER over chaining single-pack lookups', and alternative: 'use resolve_entity first if you only have a name'. Clear exclusions and context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and handling stale context, which goes beyond the annotations without contradicting them.

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

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

Two sentences with no fluff. The first sentence states the core functionality, the second provides usage guidance. Every sentence adds value.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description is complete. It covers purpose, usage, and relationships with siblings.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete.' The description does not add additional parameter details beyond what the schema provides, 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 action ('Delete'), the resource ('a previously stored memory'), and the method ('by key'). It differentiates itself from siblings like 'remember' and 'recall' by indicating a delete operation.

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

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

Explicitly provides use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall', guiding when to use 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?

Description discloses fetching, extraction, and emission behavior. Annotations already indicate safety; description adds no contradictions.

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

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

Five concise sentences with no wasted text. Purpose is front-loaded; every sentence adds value.

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

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

Adequately explains output (text blob) and typical usage. No output schema needed; description is self-contained.

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

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

Adds examples and defaults beyond schema (e.g., max_links default 25, max 50). Schema coverage is 100%, so description provides useful extra context.

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

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

Clearly states it generates llms.txt files for AI crawlers. Specifies the output format and distinguishes from sibling tools like scan_competitor_ai_presence.

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 lists use cases: indexing client sites, personal projects, competitor auditing. Could improve by stating when not to use, but current guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and scope (caller's subscriptions), which is useful context.

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

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

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

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

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

For a simple list tool with no output schema, description covers purpose, return fields, and usage context comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning for the single parameter beyond schema.

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

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

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

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

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

Provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use but context is clear.

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

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

Annotations indicate the tool is writable (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description confirms the write operation and adds that it returns the created item's ID and name. No contradictions; the description enhances the behavioral understanding 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 a single sentence that front-loads the action, includes an example, and specifies return value. No extraneous text; every phrase is purposeful. It is concise and easy to parse.

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

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

Given the tool's simplicity (create operation with 5 parameters, all described in schema), the description covers the essential behavior and return value. It does not detail error conditions or rate limits, but for a straightforward create API, it is sufficiently complete. The presence of an output schema (implied) further reduces the need to describe returns in depth.

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

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

Schema coverage is 100%, with each parameter having a description in the schema. The tool description provides examples but does not add significant new semantics beyond the schema definitions. The baseline for full schema coverage is 3, and the description does not elevate it further.

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 (create a new item), the target resource (a board), provides concrete examples (board ID '12345', name 'New Task'), and specifies the return value (created item ID and name). This distinguishes it cleanly from sibling tools like monday_get_board or monday_list_items.

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 does not explicitly state when to use this tool versus alternatives or mention prerequisites beyond the required parameters. The usage context is implied by the required fields (_apiKey, board_id, group_id, item_name), but no guidance on when not to use or which sibling to prefer is given. This is adequate but lacks proactive differentiation.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds the return content but does not disclose additional behavioral traits beyond what annotations provide. It is consistent without contradiction.

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

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

The description is a single, front-loaded sentence with no wasted words. It clearly communicates the tool's purpose and output.

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

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

Given the tool has only 2 required parameters, no enums, and an output schema exists, the description provides adequate context about the return values (name, columns, groups, item count). It is complete enough for a simple read operation.

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 both _apiKey and board_id described. The description adds an example ('board ID \"12345\"') but does not provide new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves board structure and metadata, specifying the resource (board) and action (get). It lists returned data (name, columns, groups, item count), which distinguishes it from sibling tools like monday_list_boards that list all boards.

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 does not explicitly state when to use this tool versus alternatives like monday_list_boards or monday_list_items. Usage is implied by the name and description but not directly guided.

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 and non-destructive. The description adds the specific returned fields (board ID, name, state, item count), providing useful behavioral context beyond annotations.

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

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

Two concise sentences, front-loaded with the action, no filler.

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

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

With output schema present, the description still includes return fields, which is helpful. Minor inconsistency: states 'all boards' but there is a limit parameter, but overall adequate for a simple listing tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new information about parameters beyond what the schema provides.

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

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

The description clearly states the action ('list all boards') and the resource ('boards in your account'), and distinguishes from sibling tools like 'monday_get_board' (specific board) and 'monday_list_items' (items on a board).

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

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

No guidance on when to use this tool versus alternatives (e.g., monday_get_board for a single board) or any prerequisites beyond the API key.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds return field details but does not disclose additional behavioral traits such as pagination limits or rate limiting beyond the schema parameter for limit.

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

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

The description is a single, front-loaded sentence with an example and a clear list of return fields. Every part earns its place with no unnecessary 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?

The description explains the action and return fields, and the output schema is present to detail return structure. However, it does not clarify whether the tool returns all items or a subset (limit default 20 suggests subset), which could be ambiguous. This is a minor gap given the schema covers the limit parameter.

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 description adds limited new meaning. It reinforces the board_id parameter with an example and lists return values, but does not enhance parameter semantics significantly 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 action 'List items in a board' with a concrete example (board ID '12345') and specifies the returned fields. It implicitly distinguishes from sibling tools like monday_search_items or monday_list_boards by focusing on listing items within a given board.

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

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

The description implies usage for listing items in a board but does not explicitly state when to use this tool versus alternatives like monday_search_items. No guidance on when not to use it or exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, establishing the tool as safe and idempotent. The description adds the return format but does not disclose additional behavioral traits like rate limits, pagination, or requirements beyond the _apiKey parameter. Since annotations carry the burden, a 3 is appropriate.

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

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

The description is a single concise sentence that directly states the tool's purpose and output. No redundant information, front-loaded with key details.

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

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

Given the existence of an output schema, annotations covering behavior, and full parameter descriptions, the description is largely complete. It adds the specific return fields, which is helpful. However, it could mention ordering or result limitations not covered elsewhere.

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

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

The input schema has 100% coverage: each parameter (limit, query, _apiKey) has a clear description. The tool description does not add extra meaning beyond the schema, so baseline 3 is given.

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 action ('search for items across all boards by keyword') and the return fields ('ID, name, board name, and column values'). It distinguishes from sibling tools like monday_list_items which likely list items without searching, and monday_create_item which creates.

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

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

The description implies usage for keyword searches but does not explicitly state when to prefer this over similar tools like monday_list_items or monday_get_board. No alternative names are given, leaving the agent to infer the appropriate context.

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

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

The description discloses rate-limiting ('5 per identifier per day'), cost (free, no quota), and impact (digests, roadmap influence). Annotations are minimal but not contradicted; description adds substantial behavioral context.

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

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

A single, well-structured paragraph that front-loads purpose, then usage, then exclusions, then operational details. Every sentence is informative; 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?

No output schema, but feedback tool requires minimal output. The description covers all necessary context: what the tool does, when to use it, how to formulate feedback, limitations (rate limit, free), and team response. Fully adequate for a simple 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 adds value by clarifying the 'type' enum with actionable definitions and recommending message length ('1-2 sentences typical'). Context parameter is well-explained in schema, no extra needed. Overall, description enhances parameter understanding beyond schema.

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

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

The description explicitly states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates specific use cases (bug, feature/data_gap, praise). There are no sibling feedback tools, so it is clearly distinguishable.

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 is clearly specified: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion: 'don't paste the end-user's prompt.'

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds valuable behavioral context: it's aggregated, no PII, caching dynamics (5min-1h depending on window), and derived from CF analytics-engine. These details go beyond annotations without contradiction.

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

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

The description is 5-6 sentences, well-structured with a bullet-like list of use cases. It front-loads the main output and then provides deeper context. Every sentence adds value with no redundancy or filler.

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

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

Given no output schema, the description adequately explains the return structure: 'just (pack, tool, count)' implying a list of items. It covers data source, aggregation method, privacy, and caching. For a simple tool with one optional parameter, the description is comprehensive and leaves no major gaps.

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

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

Schema description coverage is 100%, with the parameter 'window' already well-described in the schema's description field. The tool description does not add new semantics about the parameter beyond mentioning caching dependent on window, which is already implied. Baseline 3 is appropriate.

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

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

The description clearly states it returns top tools, packs, and call volume over a window. It specifies the data source (other AI agents calling on Pipeworx) and differentiates from sibling tools like discover_tools, which is about listing available tools rather than trending usage.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming canonical choice, and seeing alignment with most agents' needs. While it doesn't explicitly say when not to use, the context implies it's for trending information. No alternatives are mentioned, but the use cases provide clear guidance.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: the requirement for one parameter, the two operating modes, monotonicity and partition checks, similarity filtering, placeholder handling, and fill check against the order book. No contradictions with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, event mode, topic mode, details on semantic anchor, partition filter, response, fill check). While lengthy, every sentence contributes value. It is slightly verbose but appropriate for the tool's complexity.

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

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

Despite no output schema, the description details the response structure (opportunities[], partition_check object) and explains the fill check. It covers input modes, algorithm overview, edge cases (placeholders, similarity), and references a sibling tool for custom sizing. The description is comprehensive for the tool's complexity.

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

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

Both parameters are described in the schema with 100% coverage. The description adds meaning by providing examples of event slugs, explaining that full URLs are accepted, and clarifying how topic is used as a seed question for cross-event scanning. It also describes the mode of operation for each parameter, going beyond the schema.

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

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

The description clearly states the tool's purpose: identifying arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and uses specific verbs like 'find', 'checks', 'computes'. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage logic.

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

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

The description explicitly requires one of event or topic, warns that calling with no args fails, recommends event for specific markets and topic for cross-event scanning, and mentions alternative tools (polymarket_fill_risk for custom sizing). It provides conditions like Jaccard similarity threshold and placeholder filtering, and advises not to trade when realizable edge ≤ 0.

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

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

The description goes far beyond the annotations (readOnly, idempotent, non-destructive) to disclose intricate details: model families (crypto_price with lognormal barrier from FRED data, news_momentum with GDELT, partition_overround with sport-specific bias correction, concentrated_longshot conditions), edge calculation (edge_pp_net after slippage, Kelly fractions capped at 0.25), diagnostic output fields, caching behavior, and caveats like Fed bets reliability issues. No contradictions with annotations.

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

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

The description is lengthy but well-structured: starts with purpose, then segments into model families, response structure, tradeable-edge knobs, and diagnostics. Every sentence provides meaningful detail. While dense, it is appropriately sized for the tool's complexity and avoids 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 the lack of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and every field like edge_pp_net, kelly_fraction, and 24h-move warning. It covers filtering, caching, and edge cases (e.g., why Fed bets are excluded). For a tool with 9 parameters and no output schema, this is exceptionally 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?

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra value by explaining the rationale behind defaults, usage scenarios (e.g., 'Set to 2 to require tight books'), and interactions between parameters (e.g., min_partition_leg_kelly vs min_kelly for partitions). This justifies a score above baseline.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting the specific use case 'what should I bet on today'. It distinguishes itself from sibling tools by describing its unique model-driven, structural arbitrage, and concentrated longshot segments.

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

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

The description explicitly states the tool is built for discovering opportunities without paging hundreds of markets and provides tradeable-edge knobs for filtering. It explains when to adjust parameters like slippage and liquidity. However, it does not explicitly state when not to use it or mention alternative tools for other purposes, slightly reducing clarity.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable details: reads from daily snapshots, 60-day TTL, decay computed from daily closes (not intraday), and describes the response structure. No contradictions.

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

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

The description is somewhat long but efficiently packed with essential information. It is front-loaded with the central question. Every sentence adds value, though it could be slightly more structured with bullet points.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, daily vs intraday). All aspects are covered.

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

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

Schema coverage is 100% with descriptions. The description adds context: default for days is 14 with max 30, window explained as 'snapshot family' with examples. This enhances understanding beyond the schema.

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

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

The description clearly states that the tool provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?' This differentiates it from sibling tool 'polymarket_edges' which likely provides raw edge data.

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

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

The description gives a concrete use case: assessing whether an edge is fresh or old, explaining that a 3-week-old wide edge is different from a fresh one. It does not explicitly state when not to use the tool, but context implies using 'polymarket_edges' for current edges without history.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds behavioral details beyond annotations: it returns a verdict (clean|degraded|cannot_fill), explains partial basket fills convert arb to directional position, and identifies thin_legs and forced_directional_risk. No contradictions.

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

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

Well-structured with clear sections for single-market and basket modes. Front-loaded with purpose. Some redundancy could be trimmed, but the complexity justifies the length.

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

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

Despite no output schema, the description comprehensively lists all return fields and explains their meaning. Covers edge cases like thin books and partial fills. For a tool with 4 parameters and two modes, it provides complete context for agent invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds value by explaining default values, default behavior for side in basket mode, interpretation of size_usd, and mutual exclusivity of market vs event.

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

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

The description explicitly states the tool checks realizable vs. theoretical edge against live order-book depth. It defines two modes (single-market and basket) and lists return fields. It distinguishes from sibling tools by referencing specific use cases (arbitrage signals, edges trades).

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains when not to rely on theoretical overround and warns about partial fill risks.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior, so the bar is lower. The description goes beyond by detailing response fields (spread, compatibility_warning, temporal_alignment, skipped counters) and explaining when results are meaningless (e.g., incompatible bet shapes, temporal gap). This provides comprehensive behavioral context.

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

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

The description is a single paragraph of moderate length, but every sentence adds value. It front-loads the core purpose and sequentially covers modes, output, and safety fields. While structured, it could benefit from bullet points for readability, but it remains concise given the complexity.

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

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

Given no output schema, the description must explain both input modes and output structure. It does so thoroughly, covering leg-by-leg prices, spreads, compatibility warnings, temporal alignment, and skipped leg counters. It also addresses edge cases and limitations, making it fully informative for an agent.

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

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

Schema coverage is 100% with adequate parameter descriptions. The description adds significant operational context: lists the exact topic shortcuts, explains the override mechanism, and clarifies the interaction between mode selection. This elevates clarity beyond the schema alone.

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

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

The description immediately states the core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (computes spread) and resource (two prediction markets), and distinguishes itself from siblings by detailing unique modes and output 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 clearly explains two modes (topic shortcuts and explicit tickers) and provides context on when the output is meaningful, including compatibility warnings and temporal alignment. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or provide direct when-not-to-use guidance, but the detailed caveats sufficiently guide usage.

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

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

Annotations already declare read-only and idempotent behavior. The description adds scoping information (by identifier) and the ability to list all keys when omitting the argument, which supplements the annotations well without contradiction.

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

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

Three concise sentences with the main action front-loaded. No wasted words—each sentence adds distinct value: what it does, when to use it, and how it pairs with related tools.

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 low complexity and rich annotations, the description is complete enough. It could optionally mention the return format, but existing information suffices for correct tool invocation.

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

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

Schema coverage is 100% and the description explains the 'key' parameter's role, including the effect of omitting it (list all keys). It also gives examples of stored values (ticker, address, notes), adding contextual meaning beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with a specific verb ('retrieve'/'list') and resource ('value saved via remember'), and distinguishes it from sibling tools 'remember' and 'forget'.

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

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

Explicitly describes when to use (look up context stored earlier) and contrasts with re-deriving from scratch. Also mentions pairing with remember and forget for save/delete actions, providing clear usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations, such as the effect of mark_read (flagging events as read to filter future calls) and that it returns raw event payloads. This enriches the agent's understanding without contradicting annotations.

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

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

The description is concise at 3 sentences, covering purpose, return fields, filtering, and an alternative access method. It is front-loaded and efficient, though slightly dense; bullet points could improve scannability.

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

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

The description provides complete context: it explains the tool's function, return fields, parameter usage, and even mentions an alternative endpoint. Given the absence of an output schema, it sufficiently covers what the agent needs to know to invoke the tool correctly.

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

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

The input schema already describes all 5 parameters with 100% coverage. The description adds value by giving examples (e.g., 'sec_8k' for type) and explaining the behavior of mark_read in context, which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, raw payload) and distinguishes itself from sibling tools like list_subscriptions by focusing on retrieving actual events rather than managing subscriptions.

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

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

The description provides usage guidance by noting that polling works fine and mentions an alternative HTTP endpoint for scripts and dashboards. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Description discloses fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, soft-fail for patents, and return format (structured changes grouped by source, total_changes count, URIs). Annotations already mark readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, which align with the description.

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

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

Description is detailed but front-loaded with examples and each sentence adds value. Could be slightly more concise, but no waste.

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

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

Given tool complexity (multiple sources, fallback, parameter formats, no output schema), the description fully covers return structure, parameter details, and alternative tool. Annotations provide additional behavioral hints.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains since formats (ISO date or relative like '7d', '30d', '1y') with recommended defaults, clarifies type is only 'company', and explains value can be ticker or CIK with examples.

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

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

Description clearly states the tool provides a change feed for a company over a window, with specific example queries. It distinguishes from sibling entity_profile by noting that tool is for static profiles.

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

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

Provides explicit example queries, recommends when to use (recent changes) and when to use entity_profile instead. Also explains fallback behavior and soft-fail for patents.

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 idempotentHint=true and destructiveHint=false. The description adds useful context beyond annotations: key-value scoping by identifier, persistence time (24h for anonymous, persistent for authenticated), and pairing behavior. It doesn't mention overwrite semantics or size limits, but adds significant value to the agent's understanding.

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 approximately 100 words, front-loaded with purpose, uses bullet-like examples, and ends with pairing guidance. Every sentence contributes value without redundancy or fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavior, and pairing. It does not explicitly explain overwrite behavior when storing an existing key, but the idempotent hint partially covers this. The description is largely complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description adds minimal extra meaning beyond stating 'key-value pair' and 'scoped by your identifier'. The schema already carries the semantic load, 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 tool saves data for reuse across conversations/sessions, uses a verb ('Save') and defines the resource as 'data the agent will need to reuse later'. It distinguishes from siblings by naming 'recall' and 'forget' as partners, and provides concrete examples of when to use (resolved ticker, target address, user preference).

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and positions the tool as a way to avoid re-lookup. It pairs with recall and forget, giving clear context. However, it does not explicitly state when not to use or contrast with alternatives beyond the named siblings.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral detail: it explains that each call cascades through multiple lookup endpoints and describes the exact return values (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). This goes well beyond annotations.

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

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

The description is well-structured, starting with engaging example queries, then a usage directive, followed by detailed type breakdowns. Every sentence adds value, though it is slightly verbose. Still, it's appropriately front-loaded and earns its length.

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

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

Given the tool's complexity (two entity types, multiple input formats, no output schema), the description covers all necessary aspects: usage scenario, input variations, return values, and even includes citation URI information. An agent can fully understand how to use the tool without ambiguity.

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 enhances both parameters: for 'type', it explains what each enum value returns and provides examples; for 'value', it clarifies acceptable inputs (ticker, CIK, name for company; brand/generic for drug) and mentions auto-disambiguation, adding meaning beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers. It provides multiple example queries ('What's the ticker for...', 'find the CIK for...') and lists supported entity types with specific details, making the purpose unmistakable and distinct from sibling tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear guidance on when to invoke. It does not state exclusions or alternatives, but the context is sufficient given the tool's unique role among siblings.

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

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

Annotations already mark the tool as read-only, idempotent, and open-world. The description adds value by explaining the internal mechanism ('probes each entity... with ai_visibility_check') and the output structure ('ranked list with score, confidence, signal density'). 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 two sentences plus an example question, front-loaded with the core purpose. Every sentence adds value: the first states the action, the second gives the method and use case. 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?

With 4 parameters, no output schema, and good annotations, the description covers the tool's purpose, method, output structure, and parameter roles. The only minor gap is the exact format of the ranked list (e.g., JSON vs table), but the stated fields (score, confidence, signal density) are sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning beyond the schema: it clarifies that the first entity is treated as subject, that 'workers-ai' is the default model, and that '_apiKey' is only needed for the 'anthropic' model. This enhances parameter understanding.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from the sibling tool ai_visibility_check by emphasizing the comparative, multi-entity nature, and explicitly mentions the output (ranked list with score, confidence, signal density).

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 a clear use case ('competitive AI-marketing audits') and an illustrative question. While it implies when to use (multi-entity comparison), it does not explicitly state when not to use it (e.g., single entity queries) or directly compare to siblings like compare_entities. However, the context is sufficient for an agent to infer appropriate usage.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: first bundlephobia measurement takes 5-30s, partial failures gracefully degrade with sources_failed field. No contradiction with annotations.

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

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

Description is front-loaded with purpose and usage, then covers limitations and fallback. A few phrases could be tightened (e.g., 'Composite...check in ONE call'), but every sentence adds value. Not perfectly concise but close.

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

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

Given no output schema, description covers key return fields: summary block, per-advisory detail, links, recent alternatives. Also addresses ecosystem scope, partial failure behavior, and timing of bundlephobia. Completeness is high for the tool's complexity.

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

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

Schema covers both parameters at 100% coverage. Description adds practical details: scoped packages accepted, version defaults to latest when omitted. This adds useful semantic context beyond schema.

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

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

Description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia data, addressing 'is X safe/popular/small' queries. It distinguishes from siblings by specifying NPM-only scope and mentioning fallback for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks...' and provides specific query examples. Also states when not to use: non-NPM packages should use deps.dev:version directly. This gives clear context and alternatives.

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

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

Adds significant behavioral details beyond annotations: embedding model, window size, character cap with truncation and flagging, and that passages include character offsets for verification. Annotations already indicate readOnlyHint, etc., but description enriches context.

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

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

Single dense paragraph with front-loaded purpose. Nearly all sentences are informative, but slight density from technical details could be better structured. Still very efficient.

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

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

Covers all essential aspects: what it does, input constraints (200K chars), output format (passages with offsets/scores), and technical details. No gaps given the absence of 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%, so baseline is 3. Description adds value with query examples and text truncation details, justifying 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 clearly states 'Semantic search INSIDE a fetched record,' specifying the verb and resource. It distinguishes from siblings like ask_pipeworx_grounded by explaining the paired workflow.

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 the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, providing clear context for when to use versus alternatives.

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

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

Adds rich details beyond annotations: requires authenticated account, delivery channels with caps and verification, webhook signing secret, auto-disable after failures. No contradiction with annotations (readOnlyHint false, destructiveHint false, idempotentHint true, openWorldHint true).

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 provides unique value; the description is front-loaded with the purpose. However, it is dense and could benefit from bullet points for easier parsing by an AI agent. Still, it remains efficient and structured chronologically.

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 3 parameters, nested objects, and multiple types, the description fully covers all aspects: purpose, prerequisites, type-specific filters, delivery options, return value, and behavioral traits. No output schema exists, but the description adequately explains returns and side effects.

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, such as specific per-type parameters (e.g., items codes, fx:topic) and delivery constraints (phone verification, SMS cap, webhook auto-disable). This goes well 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?

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinctly separates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and offering specific type details.

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

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

Provides clear context on when to use (creating a subscription) and prerequisites (requires Pipeworx OAuth account). However, it does not explicitly state when not to use or direct users to alternative tools for other actions.

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 context about the output being category-bucketed example questions with tool+argument shapes, but does not disclose additional behavioral traits 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 front-loaded with trigger phrases and structured clearly, but the lengthy list of categories could be omitted since it's duplicated in the schema. It remains informative without excessive verbosity.

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 tool (one optional parameter, no output schema), the description fully covers what the tool does, how to use it, and what it returns. It explains the return format and usage context adequately.

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

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

Schema coverage is 100% for the single optional parameter 'topic', with both schema and description providing the same list of focus areas. The description does not add new meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns example questions and tool suggestions. It lists specific categories and distinguishes from siblings by positioning itself as the first tool to use before exploring meta-tools.

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

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

Explicitly describes when to use (first connection, unsure what to ask), how to call (with or without topic parameter), and mentions alternative tools (meta-tools like ask_pipeworx, entity_profile) for learning how to use them.

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

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

Beyond annotations (which indicate non-readOnly, non-destructive, idempotent), the description adds key behavioral details: ownership enforcement, deactivation instead of deletion, and preservation of historical events.

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

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

Two concise, front-loaded sentences with no redundant information. Every sentence adds essential value.

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

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

Given the simple tool (1 param, no output schema, annotations present), the description fully covers ownership, behavior, and data persistence, leaving no gaps.

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

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

With 100% schema coverage and a single parameter 'id', the schema already describes it. The description's mention of 'by id' adds no new semantics, meeting the baseline.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 (to cancel own subscriptions) and mentions ownership enforcement. It does not explicitly list alternatives but the context of siblings makes it clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds detail about returning a verdict with structured output, actual value, citation, and percent delta, and mentions data source (SEC EDGAR + XBRL), enhancing transparency.

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

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

Front-loaded with query patterns and purpose. Slightly long but every sentence adds value, including examples and replacement claim. Could be trimmed slightly without losing key information.

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

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

Given the single parameter and no output schema, the description adequately covers the return structure (verdict, actual value, delta, citation) and scope. May be slightly incomplete about edge cases or error handling, but sufficient for the tool's simplicity.

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

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

Parameter 'claim' has 100% schema coverage with a description. The tool description adds examples and clarifies the natural-language aspect, providing additional semantic context beyond the schema.

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

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

The description uses specific verbs and noun phrases like 'natural-language claim verification' and provides example queries. It clearly distinguishes itself from siblings by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use ('whenever the agent needs to check...') and specifies the domain (company-financial claims for public US companies). Does not explicitly state when not to use, but the scope is clear.

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