Noaa

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: the default free model, the need for a personal API key for Anthropic, and the return structure (per-model score, confidence, signals, raw_response plus combined view). 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 two sentences with additional details in bullet-like form. It is front-loaded with the core action and key details (scoring, default model). Every sentence adds value, with no wasted words.

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

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

Despite no output schema, the description adequately explains the return format and covers all parameters. The complexity is moderate, and the description ensures the agent knows what to expect for inputs and outputs.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema for all four parameters. It explains that 'models' defaults to 'workers-ai', that '_apiKey' is passed straight through to Anthropic, and that 'context' helps disambiguate. This helps the agent understand parameter use without reading 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 probes LLMs for visibility on a given entity and scores it 0-100. The verb 'probe' and resource 'LLMs for visibility' are specific, and the use case (AI-marketing audits, brand checks) distinguishes it from sibling tools like 'bet_research' or 'compare_entities'.

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

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

The description mentions when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and the condition for using Anthropic with an API key. It does not explicitly state when not to use, but the context is clear enough.

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

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

Description explains that the tool internally 'picks the right tool, fills the arguments, and returns the result', revealing its orchestration behavior. With no annotations provided, this transparency about internal logic is valuable and sets correct expectations.

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

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

Description is concise at about 60 words, with key information front-loaded. The first sentence immediately states the tool's purpose, followed by how it works and examples. 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?

For a simple question-answering tool with one parameter, the description is complete. It explains the tool's behavior, gives examples, and sets expectations. No output schema exists, but the description implies a natural language answer, which is 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?

Input schema has only one parameter 'question' with 100% description coverage ('Your question or request in natural language'). The description adds context by showing example questions, which is helpful but not strictly required since the schema already covers the parameter's purpose.

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 accepts plain English questions and returns answers by selecting the best data source. Provides concrete examples like 'What is the US trade deficit with China?' which clarifies scope and distinguishes 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?

Description explicitly says to 'just describe what you need' and gives examples, providing clear usage guidance. Does not explicitly mention when NOT to use it or suggest alternatives, but the context of sibling tools like 'discover_tools' and 'get_stations' implies this is the general-purpose Q&A tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: uses only tool result, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and costs an extra LLM call. No contradiction.

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

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

The description is concise yet comprehensive, with key information front-loaded. Each sentence adds value: purpose, behavior, use cases, cost trade-off. No wasted words.

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

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

Given the tool's complexity (routing, extraction, refusal reasons), the description covers what it returns (answer, evidence, confidence, source, etc.), refusal reasons, and when to use. It is fully complete for an agent to use correctly, despite no output schema.

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

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

Schema coverage is 100% and all parameters are aliases for 'question'. The description adds minimal extra value (e.g., 'Your question in natural language'), but it does not enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies that it extracts answers using ONLY the tool result, distinguishing it from ask_pipeworx by noting the extra LLM call and explicit refusals.

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

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

Explicit usage guidelines: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts... prefer ask_pipeworx for casual lookups.' This clearly indicates when to use and when not, and references the sibling 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses rich behavioral details: resolver contract with confidence levels, parent_event extraction, news fallback handling, safety measures for low-confidence and closed markets, and tradeability warnings. 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 comprehensive but overly long (600+ words). It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with the main purpose, but the verbosity impacts conciseness.

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

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

With no output schema, the description fully compensates by detailing response shapes, classifier categories, resolver contract, parent_event extractor, news fields, and safety measures. It leaves little ambiguity about the tool's behavior and output.

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

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

The input schema already covers parameters well (100% description coverage). The description adds value by explaining the depth parameter's impact (quick vs thorough) and include_raw's effect on response size, but these are minor augmentations 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details what it does (resolve, classify, fan out, return evidence) and distinguishes from sibling tools like polymarket_edges by its comprehensive scope.

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

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

The description explicitly suggests use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context with examples but does not explicitly list when not to use or compare to alternatives, which would make it a 5.

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

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

Describes return data (paired data + resource URIs). Discloses no destructive actions. With no annotations, description adequately covers behavioral traits.

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

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

Four sentences, each with unique information. No redundancy. Well-structured.

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

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

Covers purpose, parameters, return format, efficiency benefit. For a tool with no output schema, description provides sufficient context.

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

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

Schema already covers parameters (type with enum, values with min/max). Description adds specific fields compared for each type, adding value beyond schema.

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

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

Clearly states verb 'compare' and resource 'entities'. Distinguishes from sibling tools by specifying it does side-by-side comparison, not single entity lookup.

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

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

Provides explicit scenarios: company vs drug. Mentions efficiency gain (replaces 8-15 calls). Lacks 'when not to use', but sufficient for this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details such as the parallel execution, inclusion of verbatim evidence, confidence scores, source, fetched_at, pipeworx:// citations, and explicit gaps array. It also mentions the expected time range (15-60s) and auth requirements, going beyond what annotations provide.

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

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

The description is fairly long but well-structured and front-loaded with the core action. Every sentence adds value, though some details about account requirements could be separated or shortened slightly. Overall, it is informative without being overly verbose.

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

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

Despite lacking an output schema, the description thoroughly explains the output format: a structured findings packet with verbatim evidence, confidence, source, fetched_at, citations, and gaps. It covers the tool's complexity, parallel execution, and the type of results the agent can expect. This makes the description complete for effective use.

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

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

Schema coverage is 100% with both parameters described. The description adds context: it explains each depth value's meaning (quick=3, standard=5, thorough=8) and clarifies that the 'question' parameter accepts broad or multi-part input, which is not explicit in the schema. This adds significant value 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 this tool does 'Grounded multi-source research in ONE call' and explains how it decomposes questions, routes to multiple sources, and returns structured findings. It distinguishes itself from sibling tools like ask_pipeworx by noting that deep_research is for broad or multi-part questions.

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

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

The description explicitly says to use for broad/multi-part questions and contrasts with ask_pipeworx for single lookups. It also mentions prerequisites (Pipeworx account) and plan limitations (paid plan for 'thorough' depth). This provides clear when-to-use and when-not-to-use guidance.

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

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

Without annotations, the description explains that it returns the most relevant tools with names and descriptions, which is sufficient for an agent to understand behavior. It doesn't mention edge cases like empty results or performance, but is clear enough.

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

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

Three sentences, each adding value: purpose, return type, and usage context. No wasted words, though slightly more verbose than strictly necessary.

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 (2 params, no output schema, no nested objects), the description covers its role and usage adequately. Could mention if results are ordered by relevance, but not essential.

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 does not add extra semantics beyond the schema's parameter descriptions, but the schema already provides adequate detail.

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

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

The description clearly states the tool's purpose: searching the Pipeworx tool catalog by describing needs, and it distinguishes itself from siblings by instructing to call it FIRST when many tools are available.

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

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

Provides explicit usage guidance: 'Call this FIRST when you have 500+ tools available' indicates when to use it, and suggests it helps find the right tools, distinguishing from sibling tools like ask_pipeworx.

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. Description adds rich behavioral context: parallel fan-out across multiple sources, specific return fields, patent soft-fail fallback, and that results include pipeworx 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 example queries first, then functionality, then return details, then constraints. Every sentence adds value but could be slightly more concise. Still highly 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?

Despite no output schema, description fully documents return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with specifics like pipeworx URIs and sorting. It also covers limitations (patent API sunset) and prerequisites (names require resolve_entity). Complete for a 2-param 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 describes both params fully (100% coverage). Description adds extra meaning by clarifying input formats (ticker or zero-padded CIK), reiterating that names are not supported, and noting the type enum is currently limited to 'company'. This goes beyond the schema descriptions.

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

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

Explicitly states it creates a full cross-source profile of a US public company using specific inputs (ticker/CIK). Differentiates from siblings by recommending over chaining single-pack lookups and referencing resolve_entity for names.

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 when-to-use ('holistic view', 'ALWAYS PREFER') and when-not-to-use ('names not supported', use resolve_entity first). Includes specific examples of user queries that trigger 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?

No annotations are provided, so the description carries the full burden. It states the action 'delete' but does not disclose whether deletion is permanent, requires confirmation, or any side effects. The description is minimal.

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 with no wasted words, perfectly concise for a simple delete operation.

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

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

Given the tool's simplicity (1 required param, no output schema), the description is adequate but lacks behavioral context such as permanence of deletion or error handling. For a simple tool, it's minimally complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema provides for the single 'key' 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 'Delete a stored memory by key' clearly states the verb 'Delete' and the resource 'stored memory', and specifies the parameter 'key'. It distinguishes itself from siblings like 'recall' (retrieve) and 'remember' (store).

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 no guidance on when to use this tool vs alternatives like 'forget' vs 'remember' or 'recall'. There is no mention of prerequisites or contexts where deletion is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the process (fetches page, extracts title/description/links) and output format (standard markdown ready for site-root). No contradiction.

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

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

Three sentences covering purpose, process, output, and use cases. No fluff, well-organized, front-loaded with 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 simplicity (2 params, no output schema), the description adequately covers what the tool does, how it works, and when to use it. It does not mention error handling or limitations, but this is acceptable for a straightforward tool.

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

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

Schema description coverage is 100% with both parameters (url, max_links) described. The description does not add new information beyond the schema, so 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 generates a production-ready llms.txt file, specifying the action (generate), resource (llms.txt file), and target (any URL). It distinguishes itself from sibling tools by focusing on llms.txt generation.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor AI visibility). However, it does not mention when not to use this tool or suggest alternatives, though siblings like scan_competitor_ai_presence exist.

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?

No annotations provided, so description carries burden. Describes scope (currently active, US state) but doesn't disclose rate limits, data freshness, or return format. Adequate but minimal.

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, clear sentence front-loads key information (verb, resource, scope) with examples. 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?

Simple tool with 1 parameter and no output schema. Description covers purpose and parameter usage. Missing details like data source, update frequency, or response structure, but given simplicity, it's adequate.

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 description reinforces the parameter format ('e.g. CA, NY, TX') and purpose. No additional meaning beyond schema, so baseline 3 is appropriate.

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

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

Clearly states verb 'Get', resource 'weather alerts', and scope 'currently active for a US state'. Distinguishes from sibling tools like get_forecast and get_stations.

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?

Implies usage context (US states, active alerts) but provides no explicit when-to-use or alternatives. Could benefit from noting that this is for current alerts only, not historical.

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?

No annotations are provided, so the description carries the full burden. It discloses the data source (National Weather Service) and that it returns a multi-day forecast. However, it does not mention rate limits, data freshness, or whether the forecast is text-based or data-structured. With no annotations, a score of 3 is adequate but has gaps.

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, concise and front-loaded. It contains no unnecessary words and clearly conveys the tool's purpose. It earns its place without 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 the tool's low complexity (2 simple parameters, no output schema, no nested objects), the description is reasonably complete. It explains the tool's purpose and data source. It could mention that it returns a forecast (but that is implied by 'forecast'). No output schema exists, so return format is not documented, but for a forecast tool, a 4 is acceptable.

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

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

The schema has 100% coverage with descriptions for both parameters (lat and lon). The description adds no extra meaning beyond what the schema provides (e.g., doesn't mention valid ranges for lat/lon). Baseline 3 is appropriate since schema already documents the parameters well.

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 'Get a multi-day weather forecast' for a latitude/longitude location using the National Weather Service. It specifies the verb 'get', the resource 'forecast', and the data source. However, it does not differentiate from siblings like 'get_alerts' or 'get_stations', but the sibling names are distinct enough.

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 obtaining a forecast given lat/lon, which is clear. However, it provides no guidance on when to use this tool vs alternatives (e.g., 'get_alerts') or any prerequisites like API key requirements. Usage is implied but not explicitly stated.

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

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

With no annotations provided, the description carries full burden. It correctly identifies a read operation but does not disclose any additional behavioral traits such as pagination, rate limits, or whether it returns current vs historical data.

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

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

Single sentence, zero waste, front-loaded with the action and resource. Perfectly concise.

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

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

The tool has 2 parameters (1 required), no output schema, and no annotations. The description is minimal but sufficient for a straightforward listing tool. However, it could benefit from mentioning that stations are for weather observation or that state is required.

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 does not add additional meaning beyond the schema's parameter descriptions. Both parameters are well-documented in the schema itself.

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 verb 'List' and resource 'weather observation stations' with a specific geographic scope 'for a US state'. This distinguishes it from siblings like get_alerts or get_forecast.

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 stations by state, but provides no explicit guidance on when to use this vs alternatives like get_alerts or get_forecast. There are no exclusions or prerequisites mentioned.

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, destructiveHint. The description adds value by specifying default behavior (active subscriptions only) and the exact return fields, which is useful 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: first stating functionality and return fields, second giving usage guidance. No superfluous information.

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

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

Given the simplicity of the tool (one optional boolean parameter), the description covers purpose, return fields, and usage guidance comprehensively. No output schema exists, but return fields are explained.

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 one parameter well-documented. The description adds no new information about the parameter beyond what the schema already provides. 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 verb 'list' and resource 'subscriptions', specifies the scope as 'caller's active subscriptions', and lists the return fields. It is distinct 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 guidance on when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. Does not mention when not to use, but context is clear enough.

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?

No annotations provided, but description discloses rate limits and content constraints well. It doesn't detail confidentiality or response expectations, but this is reasonable for a feedback tool.

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

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

Description is three sentences, front-loaded with purpose, and all information is relevant without redundancy. Efficient use of space.

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 (no output schema, few params) the description covers purpose, usage, constraints, and rate limits. Lacks details on feedback confirmation or privacy, but generally 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 coverage is 100%, so description adds limited value beyond schema. The message constraint about not including user prompt is additional, but the schema already details parameter enums and structure.

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's purpose: sending feedback to the Pipeworx team, listing specific categories (bug reports, feature requests, etc.). It distinguishes itself from sibling tools by being the only feedback tool.

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

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

Provides explicit guidance on when to use (for feedback), what to include (describe what you tried, avoid user's prompt verbatim), and rate limits (5/day). Sibling tools are unrelated, so no confusion.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: derived from CF analytics-engine, no PII, cached 5min-1h, confirming safety and aggregate nature.

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 concise, well-structured with bullet points, and front-loads the purpose. 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 aggregation tool with no output schema, the description explains return content (top tools, packs, call volume) and caching behavior. Missing output format details but adequate.

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

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

Schema coverage is 100% with a clear description for the single parameter. The main description reiterates the window options but adds minimal new 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?

Description explicitly states the tool returns 'top tools, top packs, and total call volume over a recent window', using specific verbs and resources. It clearly distinguishes from sibling tools by focusing on trending activity.

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

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

Description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use cases). However, it does not explicitly state when not to use or mention alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical context: the requirement for either event or topic, the monotonicity and partition-sum check logic, the Jaccard similarity threshold, placeholder filtering, and the response structure. This fully discloses behavior.

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

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

The description is verbose and packed with technical details in a dense paragraph. While well-structured with labels and examples, it could be more concise. Every sentence adds value, but the length may hinder quick scanning.

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

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

Given the tool's complexity (two modes, semantic matching, partition checks) and lack of output schema, the description thoroughly explains return values (opportunities array with fields, partition_check object). No gaps remain.

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

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

Schema coverage is 100% with descriptions, but the description adds semantic value by providing examples ('fed-decision-may-2026'), recommending event mode, and explaining the internal use of parameters. This exceeds bare schema information.

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 goal: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with specific use cases, differentiating it from siblings like polymarket_edges or polymarket_kalshi_spread.

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

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

The description explains when to use each mode: event mode for a specific market (recommended) and topic mode for cross-event scanning. It also notes that calling with no args fails. However, it does not explicitly contrast with sibling tools or provide when-not-to-use guidance.

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

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

The description discloses extensive behavioral traits beyond annotations: it explains caching (1h at KV level keyed on all knobs), response structure (by_segment, fed_candidates, diagnostics), and internal filters (placeholder-slug filter, Fed exclusion). It details the three model families and their formulas, revealing non-obvious behaviors like 'partition_arbs always return kelly_fraction_half=0 at the parent level' and 'Run 8 from prior 85%/5%/50:1'. Annotations are readOnlyHint=true, etc., and the description does not contradict them.

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

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

The description is well-structured with clear sections (segments, knobs, response) but is verbose (over 500 words). While front-loaded with purpose, it includes extensive technical details that could be condensed. For an AI agent, the length may be acceptable given the complexity, but it is not concise.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally complete. It describes the response format including fields like edge_pp_net, kelly_fraction, and 24h-move warning. It explains caching, diagnostics, and edge cases (Fed bets excluded). All aspects needed for correct invocation 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 description coverage is 100%, so the baseline is 3. The description adds value by explaining the rationale behind parameters (e.g., 'min_partition_leg_kelly' notes that 'min_kelly never filters them' and explains why). It also clarifies interactions, such as 'slippage_pp subtracted from raw |edge| before ranking'. This extra context merits 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 states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx data disagreement. The intended use case ('what should I bet on today') is explicit, and the three segments (model_driven, structural_arbitrage, concentrated_longshot) are enumerated, leaving no ambiguity about what the tool does.

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

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

The tool explicitly states its use case: 'built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides detailed guidance on tradeable-edge knobs (min_liquidity, max_spread_pp, etc.) and explains when to adjust each parameter. However, it does not explicitly state when to use an alternative sibling tool (e.g., polymarket_arbitrage), though the purpose differentiates it sufficiently.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant context: it reads snapshot data, returns time-series, expired opportunities with lifespan, and snapshot gaps. It also clarifies that decay numbers come from daily closes, not intraday, providing valuable behavioral details beyond annotations.

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

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

The description is dense with useful information and front-loaded with the core purpose. However, it is somewhat lengthy and could be slightly more concise while retaining all necessary details. Every sentence adds value, but the length is near the threshold for conciseness.

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

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

Given the tool has no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their fields. It also covers limitations (TTL, snapshot gaps, intraday vs daily) and edge cases, making it complete for an agent to understand the output without additional documentation.

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

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

Both parameters have descriptions in the schema (100% coverage). The description adds context: default values (days=14, window='1wk'), clamp range for days (2-30), and explains the window family options (24hr, 1wk, 1mo). This adds 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes from sibling tools like polymarket_edges by focusing on how long an edge has existed and whether it is shrinking.

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 differentiate fresh edges from old ones. It mentions limits like 60-day TTL and daily close data. However, it does not explicitly state when not to use this tool or name alternative sibling tools for different purposes.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes beyond by explaining internal behavior: walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk from partial basket fills. This adds valuable behavioral context 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 long but well-structured with distinct sections for single-market and basket modes, bullet-pointed return fields, and warnings. It is front-loaded with purpose and usage guidelines. While every sentence adds value, it could be slightly more concise, but the structure is clear and efficient for the complexity involved.

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 4 parameters, no output schema, and no enums or nested objects, the description thoroughly covers both operational modes, return values, and critical behavioral warnings (e.g., forced directional risk). It provides enough context for an agent to understand inputs, outputs, and risks, making it complete for the tool's purpose.

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

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

Schema coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds extra meaning by explaining the different interpretations in single-market vs basket modes (e.g., size_usd as spend vs settlement notional) and default side behavior (auto for basket). This adds semantic value beyond the schema.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check' against live order-book depth, with explicit differentiation between single-market and basket modes. It distinguishes itself from sibling tools polymarket_arbitrage and polymarket_edges by stating it should be used before acting on their signals, providing clear purpose and differentiation.

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

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

The description provides explicit guidance on when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the consequence of not using it (partial basket fills convert arb into unhedged position), and states the requirement of either `market` or `event` parameter, giving clear context for usage.

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

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

Adds extensive detail beyond annotations: compatibility_warning, temporal_alignment, skipped_cross counters. Annotations already indicate safe read-only operation, so description enhances understanding of output and edge cases.

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?

Relatively long but well-structured with clear sections (purpose, modes, response, safety). Every sentence adds value; brevity is sacrificed for completeness.

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

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

No output schema, but description thoroughly explains return structure (leg prices, top_spreads_pp, safety fields) and edge cases. Fully sufficient for agent to understand behavior.

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

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

100% schema coverage, but description adds how parameters interact (overrides) and explains topic shortcuts. Provides value beyond 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and explains two modes. It distinguishes from sibling tools like polymarket_arbitrage and compare_entities by focusing on specific venues.

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 topic vs explicit tickers and provides warnings about compatibility and temporal alignment. Lacks explicit 'when not to use' but strong guidance is implied.

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?

No annotations provided, so description carries full burden. It mentions retrieval and listing, but does not disclose if retrieval is destructive or has any side effects. However, given the simple read nature, this is adequate but not exceptional.

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 action and conditions. No wasted words.

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

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

For a simple tool with no required params and no output schema, the description is complete enough. It explains the two use cases and hints at the tool's role in cross-session memory. Could be improved by noting that memories are persistent, but not required.

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% (one parameter 'key' with description). The description adds context that omitting key lists all memories, which aligns with schema's 'omit to list all keys' but is essentially restating. 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?

Clearly states the tool retrieves a memory by key or lists all memories, distinguishing between two modes. The verb 'retrieve' and resource 'memory' are specific and distinct from siblings like 'remember' and 'forget'.

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

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

Explicitly states when to omit key (to list all) and when to provide key (to retrieve specific memory). Provides context on retrieving 'context you saved earlier', which guides usage relative to session 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?

The description states that setting mark_read:true flags events as read, modifying state. However, annotations declare readOnlyHint=true, which indicates no modifications. This is a direct contradiction, making the description unreliable for understanding side effects.

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

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

The description is three well-structured sentences. It starts with the main purpose, details the returned fields, explains filtering and mark_read behavior, and ends with a note on alternatives. No wasted words.

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

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

Despite no output schema, the description thoroughly explains the returned fields (source, citation_uri, raw payload) and covers all key behaviors: filtering, mark_read, unread_only, and polling. It also mentions an alternative access method, making it self-contained.

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

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

Schema coverage is 100%, so parameters are documented. The description adds meaning by providing examples for type (e.g. 'sec_8k'), explaining the ISO timestamp format for since, and clarifying the effect of mark_read and limit defaults. This goes beyond schema definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies what each alert carries (source, citation_uri, raw payload). It is specific about the resource and action.

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

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

The description provides clear context on usage, such as filtering by type and since, and mentions that polling works fine. It also gives an alternative access method (GET endpoint), but does not explicitly state when not to use this tool versus siblings like 'get_alerts'.

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 context beyond annotations: fans out to multiple APIs, fallback logic (GDELT→GNews), USPTO soft-fail, return format (changes[], total_changes, 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?

Six sentences, dense but clear, front-loaded purpose, no redundant information. Every sentence serves a purpose.

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

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

For a tool with 3 parameters and no output schema, the description covers purpose, parameters, behavior, output format, and alternative tool. Fully adequate.

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: explains 'since' accepts ISO or relative shorthand, gives typical use ('30d' for monitoring), clarifies 'value' as ticker or CIK, and confirms 'type' only company. Adds value beyond schema.

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

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

The description clearly states it is a 'change feed for a company' that fans out to multiple sources. It distinguishes from sibling tool 'entity_profile' which 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 numerous usage examples ('What's new with X', etc.) and explicitly directs to use entity_profile for static profiles. Implicitly covers when to use but lacks explicit 'when not to use' beyond the alternative.

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

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

Discloses behavioral traits such as persistence behavior (authenticated vs anonymous sessions) and purpose. With no annotations provided, the description carries the full burden and does well, though it could mention potential overwrite behavior or storage limits.

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

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

Concise two-sentence description. First sentence defines purpose, second adds context on persistence. No wasted words.

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

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

Given low complexity (2 parameters, no nested objects, no output schema), the description is nearly complete. Could optionally mention overwrite behavior or memory limits, but not essential.

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 context beyond schema by explaining what to store (findings, preferences, notes) but does not add meaning beyond the schema's parameter 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 the verb ('store') and resource ('key-value pair in session memory'), and distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning memory persistence and session context.

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

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

Explicitly states when to use ('save intermediate findings, user preferences, or context across tool calls') and provides persistence differences (authenticated vs anonymous). However, no explicit mention of when not to use or alternatives.

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

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

No annotations are present, so the description must cover behavior. It discloses the operation is a single call and lists return values, but does not discuss failure modes, rate limits, or idempotency.

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

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

The description is three sentences with no wasted words. It front-loads the purpose and then efficiently covers input, output, and value proposition.

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 values. It also notes the efficiency benefit. Could mention error handling for completeness, but overall satisfactory.

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

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

Schema coverage is 100%, and the description adds value by providing specific examples (AAPL, 0000320193, Apple) and noting version support, which goes beyond the schema's simple type and enum.

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 an entity to canonical IDs and provides specific details for v1 (company type). It is a specific verb+resource combination, but does not explicitly differentiate itself from sibling tools, though it implies it replaces multiple lookup 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?

The description indicates when to use the tool (when needing canonical IDs) and provides accepted input formats, but lacks explicit when-not-to-use scenarios or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. It does not mention any side effects beyond normal API usage, which is consistent with annotations.

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

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

The description is three sentences, front-loading the core purpose, then mechanism, use case, and output format. No redundant words; 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?

The tool has 4 parameters, no output schema, and the description explains the output fields (score, confidence, signal density). It covers the purpose, inputs, and outputs sufficiently, though it could mention pagination or limits on entities array size (the schema says 2-8).

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 parameters. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and that the default model is workers-ai if no models array provided. This context is not in the schema and enhances 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 clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the multi-entity side-by-side comparison with ranking.

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 example question. It implies usage when comparing multiple entities, but does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entity. The sibling list includes that tool, making it implicit.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals fan-out behavior across multiple sources, return structure (summary block, advisories, links, alternatives), and partial failure mode with timeout details for bundlephobia. 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 a single paragraph but packs dense, useful information. It front-loads the core purpose, then covers usage, return, limitations, and failure handling. Slightly verbose toward the end but overall efficient. Could be structured into bullets for easier parsing.

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

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

Despite no output schema, the description fully explains the return structure (summary block fields, per-advisory details, links, alternative versions) and handles edge cases like partial failures and timeout scenarios. Complete for a composite check 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% and already describes parameters clearly. Description adds only minor extra detail (scoped packages accepted). Baseline 3 is appropriate; does not significantly enhance 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 clearly states the tool performs a composite check for adding npm packages, covering license, advisories, version history, bundle size, and tree-shaking support. It specifies the question it answers and distinguishes from siblings by focusing on npm and naming the specific sources.

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: 'use whenever an agent asks...' and provides a clear alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives strong guidance on when and when not to use.

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

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

Discloses embedding model (BGE-base-en), window size (500-char overlapping), cap (200K chars), truncation flagging, and that results include offsets and similarity scores. Adds significant 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?

Single paragraph, front-loaded with core purpose. Every sentence adds value. Could be slightly more structured (e.g., bullet points) but remains concise and informative.

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

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

Covers purpose, usage, behavioral details, limitations (cap), and pairing with sibling. No output schema, but the description provides enough context for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100% so baseline is 3. The description enriches with examples for text (SEC 10-K body) and query (supply-chain risk), and notes default for limit. Adds meaningful context 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 'Semantic search INSIDE a fetched record' with a specific verb (search) and resource (fetched record). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with full record fetching.

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: 'Use when the record is too big to cram into the prompt' and explains that it saves context. Mentions pairing with ask_pipeworx_grounded. 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?

The description discloses important behaviors beyond annotations: OAuth requirement, always-on feed, optional delivery with limits (10/day sms), webhook signing, and auto-disable. 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 well-structured and front-loaded with the main action and return value. It is moderately long but each sentence adds necessary detail; could be slightly more concise.

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

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

The description is highly complete: it covers prerequisites, types, parameters, delivery channels with limits and behavior, and states the return value. No output schema needed.

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

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

With 100% schema coverage, the description adds substantial value by explaining each subscription type with examples and detailing delivery channel options, going well beyond the schema definitions.

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

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

The description uses a specific verb ('Create a proactive monitoring subscription') and resource ('live-data event stream'), and returns the new subscription id. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and get_alerts.

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

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

The description provides clear context for when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). It details supported types and delivery channels, but does not explicitly contrast with alternatives or state when not to use.

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

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

Annotations already declare readOnly, non-destructive, idempotent. The description adds behavioral context by clarifying it returns example questions with tool signatures from a live catalog, and that it's purely informational with no side effects.

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

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

The description is front-loaded with example user queries, then explains functionality. It is moderately verbose but each sentence adds value, and the structure is logical with usage instructions at the end.

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 an onboarding tool with one optional parameter and no output schema, the description adequately explains what it returns and how to use it. It provides enough context for an agent to understand its role as a discovery tool.

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

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

Schema description coverage is 100% for the single parameter. The description adds value by enumerating the category values (finance, pharma, etc.) and their thematic contents (company financials, drugs, etc.), which goes beyond the schema's listing.

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 starts with clear user intents and explicitly states it's the onboarding entry point for a new agent, providing category-bucketed example questions. It distinguishes from sibling tools like ask_pipeworx by positioning as the first tool to use when uncertain about capabilities.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to use (no args vs. topic filter) and implies it precedes the use of other tools.

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

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

Description adds significant behavioral context beyond annotations: ownership enforcement, row deactivation (not deletion), and preservation of historical events. Annotations only indicate non-readOnly, non-destructive, idempotent.

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

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

Three sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

For a tool with one parameter and no output schema, the description fully covers functionality, ownership, 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 has 100% coverage with a description for 'id'. The tool description adds that the id comes from 'subscribe', but this is implicit. No additional semantic clarification 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 the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Provides ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation vs deletion). However, it does not explicitly mention when to use this tool instead of 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, idempotent, and nondestructive behavior. The description adds context about the return type (verdict, structured form, actual value with citation, percent delta) and the data source, exceeding what annotations provide.

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

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

Description is a single paragraph that is concise and front-loaded with usage examples. It efficiently covers purpose, domain, and return details. Minor improvement could be structuring return types, but overall well-organized.

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 single-parameter tool with no output schema, the description sufficiently explains the return value (verdict, structured form, actual value, citation, delta) and the source (SEC EDGAR + XBRL). It also notes efficiency gains by replacing multiple calls.

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

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

Schema coverage is 100% with a single claim parameter described. The description adds example claims but no new semantics beyond the schema. Baseline of 3 is appropriate as schema already handles parameter documentation.

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

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

The description clearly defines the tool as a claim verification tool against authoritative sources, specifically for company-financial claims using SEC EDGAR + XBRL. It provides query examples that distinguish it from sibling tools like ask_pipeworx or compare_entities.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' and specifies domain (company-financial claims). While no alternatives are named, the context is clear and the tool's specialized scope guides when to use it.

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