Outlook Mail

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable context: it specifies the default model (Workers AI Llama-3.3-70b), that Anthropic probing requires an API key paid by the user, and that the key is passed to api.anthropic.com. 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 concise (3 sentences) and front-loaded with the core purpose. Every sentence adds essential information 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?

Despite no output schema, the description clearly states the return format: per-model {score, confidence, signals, raw_response} plus a combined view. It covers input, behavior, and output adequately for an AI agent to understand 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?

All 4 parameters have descriptions in the schema (100% coverage). The description adds extra value beyond the schema by explaining the default model for 'models', that '_apiKey' is passed straight through to Anthropic, and that 'context' helps disambiguate common names.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It uses specific verbs and resources (probe, LLMs, score visibility) and distinguishes itself from siblings like scan_competitor_ai_presence by focusing on multi-model probing and scoring.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional parameters (_apiKey). However, it does not explicitly mention when not to use the tool or compare it directly to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it routes to the right tool, works on every tier with one fast call, and returns structured answers with citation URIs. Minor gap: no mention of failure modes or error handling.

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

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

The description is well-structured with clear sections: when to use, examples, alternatives. It is slightly long but each sentence adds value. Could be tightened slightly.

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 (many sources) and lack of output schema, the description adequately explains its function, return format (structured answer with citation URIs), and usage context. It covers purpose, alternatives, and examples comprehensively.

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

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

Schema coverage is 100% (all parameters documented via aliases for the question field). The description does not add significant meaning beyond the schema, only stating that it 'fills arguments'. 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 that the tool routes questions to a vast set of authoritative sources (4,476 tools across 1,127 sources) and returns structured answers with citations. It distinguishes from sibling tools like ask_pipeworx_grounded and deep_research by noting different use cases.

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

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

Explicit guidance on when to use this tool over alternatives, including specific query types (e.g., 'what is', 'look up') and examples. It advises starting here for most questions and stepping up to grounded or deep_research only when needed.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals the hallucination-resistant behavior, the extraction process using 'ONLY what the tool result contains', and the explicit refusal reasons. It also describes the return format including fields like evidence, confidence, and source, adding substantial behavioral context.

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

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

The description is well-structured: it starts with the core purpose, then explains the mechanism, return format, use cases, and trade-off. Every sentence provides necessary information without verbosity. It is front-loaded with the most critical identifier ('Hallucination-resistant answer mode').

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 among 4,476 tools, refusal reasons), the description is remarkably complete. It explains the behavior, return format, and usage constraints. Although there is no output schema, the description lists the return fields. The parameter aliases are covered in the schema, and the description adds sufficient context for an agent to use the tool correctly.

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

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

The schema has 100% coverage, listing the required 'question' parameter with multiple aliases. The description adds context that the question is used for routing and argument filling, but does not explain what constitutes a good question beyond natural language. This is slightly above the baseline of 3 for high schema coverage.

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

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

The description explicitly states that the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and functions similarly to ask_pipeworx but with grounded extraction. It clearly distinguishes itself by emphasizing that it extracts the answer using only the tool result, preventing invention. Specific use cases (financial verdicts, legal claims, medical lookups) are provided.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also states the cost trade-off ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'), making it clear when to use which 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?

Extensive disclosure of behavior beyond annotations: classifier fan-out, response shapes, resolver contract, parent event extraction, safety mechanisms, and resolution rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections. Some redundancy could be trimmed, but it remains understandable.

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 output fields extensively, including resolver confidence, parent events, news fallback, safety short-circuits, and cancellation rules. Very complete for a tool without 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 descriptions already explain parameters. The tool description adds context like depth effect (quick vs thorough) and include_raw behavior (size trade-offs), which 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 it researches Polymarket bets by pulling Pipeworx data, accepts various input formats, and returns an evidence packet. It is specific and covers the purpose thoroughly.

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

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

Provides explicit use cases like 'should I bet on X' and gives examples of blocking conditions. Does not explicitly contrast with sibling tools, but the context is self-contained.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds critical details: for company type, it pulls specific financials from SEC EDGAR/XBRL with correct off-calendar handling; for drug type, it pulls adverse events, approvals, trials. Also notes sorting by primary metric and return of citation URIs.

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

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

Single dense paragraph with key information front-loaded. Every sentence adds value, no redundancy. Uses bold for emphasis.

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?

Though no output schema, description briefly mentions return format ('paired data + pipeworx:// citation URIs'), which is sufficient. Could elaborate on data structure, but not essential for agent usage.

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

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

Schema coverage is 100% and description enriches parameters: explains that 'values' are tickers/CIKs for company or drug names, and constraints (2-5 items). Adds meaning beyond schema property 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 explicitly states the tool compares 2-5 entities side-by-side, with clear examples like 'Compare X and Y' and details the specific data pulled per entity type. It distinguishes from sibling tools like 'entity_profile' which likely handles single 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 advises 'ALWAYS PREFER over sequential single-pack lookups' and describes when to use (comparisons, rankings, etc.). Lacks explicit when-not-to-use, but the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable behavioral context: expected 15-60s response time, returns gaps[] for unanswered facets, never invents data, and requires account sign-in. 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?

Description is lengthy but well-structured with clear sections. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given no output schema, description fully explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]). Covers prerequisites, alternatives, edge cases (empty gaps for non-structured topics), and limitations.

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. Description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8 paid) and clarifies that question is natural language and broad/multi-part is fine.

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

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

The description clearly states the tool performs grounded multi-source research across 1127 structured data sources by decomposing questions into facets and returning a findings packet. It distinguishes itself from siblings like ask_pipeworx by emphasizing it is not open-web search and is best for broad/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?

Explicitly tells when to use (broad/multi-part questions over structured data) and when not (single lookup use ask_pipeworx, breaking news use ask_pipeworx). Also notes account requirements and that 'thorough' depth needs a paid plan.

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

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

Annotations declare readOnlyHint and idempotentHint as true, confirming safe, non-destructive behavior. The description adds behavioral context that results are 'ready to call directly, no second schema lookup needed,' which enhances transparency beyond annotations. No contradiction found.

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: first states purpose, second lists supported domains, third explains return value and usage guidance. Every sentence adds distinct value, no fluff. Front-loaded with the core verb and resource.

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 explains what is returned (names, descriptions, full input schemas with curated examples). It covers the tool's scope, usage context, and return structure. Could mention pagination or rate limits, but as a search tool for tool discovery, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description provides natural language examples for the required 'query' parameter (e.g., 'analyze housing market trends') and explains that multiple aliases (q, task, search, description) are accepted. It also notes the default and max for 'limit', adding value beyond the schema.

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

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

The description starts with a specific verb+resource ('Find tools by describing the data or task') and lists concrete use cases (SEC filings, FDA drugs, etc.). It explicitly states 'Call this FIRST' to differentiate from sibling tools that perform specific tasks, making its purpose unambiguous.

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

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

The description clearly states when to use ('when you need to browse, search, look up, or discover what tools exist') and provides a usage instruction ('Call this FIRST when you have many tools available'). It does not explicitly mention when not to use or name alternatives, but the context makes it clear this is for discovery before selecting a specific 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?

Discloses parallel fan-out across multiple sources, patents may soft-fail due to USPTO sunset, and returns specific fields. Annotations (readOnly, idempotent, not destructive) are consistent and description adds valuable context beyond annotations.

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

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

Description is detailed but front-loaded with trigger phrases and usage guidance. Every sentence adds value, though slightly lengthy. Efficient packaging of many details.

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

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

With no output schema, description fully explains return content (cik, filings, fundamentals, patents, news, LEI) and their sources. Covers edge cases like soft-fail. Complete enough for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100%, but description reinforces meaning of 'value' parameter (ticker vs CIK, names not supported) and 'type' (only company). Adds value by clarifying constraints and examples beyond schema.

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

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

Description clearly states it provides a full cross-source profile of US public companies. Lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and output fields. Distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also states names not supported, directing to use resolve_entity first. Provides clear 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 aligns with annotations (destructiveHint=true) and adds context about why to delete (sensitive data, stale context), though it could mention error behavior or confirmation of deletion.

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

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

Three concise sentences: action, usage guidelines, and pairing advice. 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 deletion tool with one parameter and no output schema, the description adequately covers purpose, usage, and relationships to siblings.

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

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

The schema already provides 100% coverage for the single parameter 'key' with description 'Memory key to delete'. The description adds 'by key' but no additional semantic details beyond the schema.

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

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

The description explicitly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes itself from sibling tools 'remember' and 'recall'.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with 'remember' and 'recall'.

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 nature. The description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard markdown. This complements the 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 three sentences with no fluff. The first sentence states the purpose, the second explains the process, and the third lists use cases. Every sentence contributes value.

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

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

Given two simple parameters, no output schema, and comprehensive annotations, the description covers the tool's functionality well. It explains the output format (standard llms.txt markdown) and destination (site-root/llms.txt). Minor gap: no discussion of error handling or URL validation, but not critical for this tool.

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

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

Schema coverage is 100% with both parameters well-described in the schema. The description does not add new information beyond what the schema provides, so it meets the baseline expectation but does not exceed it.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It also lists specific use cases (indexing client sites, drafting own project, auditing competitor) which distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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 for when to use the tool (e.g., getting a client's site indexed, drafting llms.txt, auditing competitors). It does not specify when not to use it or mention alternatives, but the context is clear enough for most scenarios.

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

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

Annotations already declare readOnly=true, idempotent, non-destructive. Description adds return fields and parameter behavior, providing useful context beyond annotations.

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

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

Two sentences, front-loaded with main purpose, 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?

Tool is simple; description explains return fields, default behavior, and usage scenario. No output schema needed given field list in description.

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

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

Only one parameter, schema coverage 100% includes description. Description implies the parameter's effect but doesn't add significant meaning 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 'List the caller's active subscriptions' and enumerates return fields. Distinct from siblings subscribe/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?

Explicitly advises using to review monitoring before adding or to find an id to cancel. Could name subscribe/unsubscribe as alternatives, 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 adds behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. 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 appropriately sized, front-loaded with purpose, and every sentence is informative. No wasted words; structure is 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?

Despite no output schema, the description fully covers purpose, usage, constraints, and parameter guidance. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining enum values, specifying message requirements, and clarifying that context is optional. Adds value beyond the schema.

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

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

The description clearly states the tool is for sending feedback about bugs, missing features, data gaps, or praise. It defines each type and distinguishes the tool from siblings, which are all unrelated to feedback.

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 tells when to use: for bugs, features/data gaps, or praise. It advises against pasting the end-user's prompt and mentions rate limits and quota exemption, providing complete guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context: it is a self-aggregating signal, derived from CF analytics-engine, no PII, and caching details (5min-1h). 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 (4 sentences), well-structured with bullet points, and front-loaded with the core purpose. 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 has only one optional parameter and no output schema, the description adequately explains what is returned (top tools, top packs, total call volume) and caching policy. It is complete for this low-complexity tool.

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

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

Schema coverage is 100% with enum descriptions. The description adds behavioral context for each window (e.g., 'shorter windows surface what is hot right now; longer windows show steady-state demand'), enhancing meaning 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 returns top tools, top packs, and total call volume over a time window. It lists specific use cases, making the purpose unmistakable.

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

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

Three explicit use cases are provided, and guidance on window selection is given. However, it does not explicitly contrast with sibling tools like 'discover_tools' to guide when to use this over others.

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, and destructiveHint. The description adds extensive behavioral context: the two modes, algorithmic steps (Jaccard similarity, placeholder filtering, partition checks), and importantly the 'FILL CHECK' detail about realizable edges requiring live book depth. This goes well beyond annotations.

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

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

The description is detailed and well-structured with clear sections (requirements, modes, algorithms, response, fill check). It is front-loaded with the requirement. While lengthy for some agents, every sentence adds necessary information for correct invocation.

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 (2 modes, multiple algorithms, response format, fill check), the description is comprehensive. It covers prerequisites, mode selection, algorithmic details, response structure, and a critical caveat about realizable trades. No output schema is needed due to detailed textual explanation.

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 valuable context: examples of event slugs and topic phrases, accepted URL format, and the distinction between single-event and cross-event modes. This enhances 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage opportunities) and the method, distinguishing it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit usage guidance: requires one of `event` or `topic`, recommends `event` for specific markets and `topic` for cross-event scanning, and mentions custom sizing via `polymarket_fill_risk`. However, it does not compare directly to other arbitrage-related sibling tools or give when-not-to-use advice.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses extensive behavioral traits: data sources (FRED, GDELT), model families, edge calculation details, Kelly fractions, tradeable-edge knobs, response structure (by_segment), diagnostics, and caching behavior ('Cached 1h at the KV level'). This far exceeds what annotations provide and fully informs agents of tool 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 but well-structured. It front-loads the core purpose and usage, then breaks down model families and response segments. Every sentence adds value given the tool's complexity (9 parameters, multiple segments). While not maximally concise, the density of information is justified, and the structure (sections, bullet-like details) aids readability.

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

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

The description is exceptionally complete given the tool's complexity and lack of output schema. It explains the response structure (by_segment, fed_candidates, diagnostics), why Fed bets are excluded, caching behavior, and even provides details on filter skips in diagnostics. Nothing critical is omitted for an agent to understand what the tool returns and how to interpret it.

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

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

The input schema has 100% coverage, but the description adds significant meaning beyond the schema. It explains the role of parameters as 'tradeable-edge filters' (min_liquidity, max_spread_pp), provides example values (5000, 2), and clarifies nuanced interactions (e.g., min_partition_leg_kelly vs min_kelly). This helps agents understand how to configure parameters effectively.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the use case ('what should I bet on today') and implicitly differentiates from sibling tools like polymarket_arbitrage by focusing on model-based edge detection. The verb 'scan' and resource 'Polymarket markets' are specific, and the scope ('top markets') is defined.

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

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

The description provides strong usage context: agents should call this tool to discover bet opportunities without paging through hundreds of markets. It explicitly notes when NOT to rely on certain outputs (e.g., Fed bets are excluded due to unreliable signals). However, it lacks direct comparison to sibling tools (e.g., polymarket_arbitrage) to guide selection between them.

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

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

The description discloses multiple behavioral traits beyond annotations: history limited by 60-day TTL, data gaps when no scan, decay computed from daily closes not intraday, and the open-world hint is elaborated with 'snapshots written on cache-miss' and 'gaps mean nobody scanned'. No contradictions with readOnlyHint, idempotentHint, or destructiveHint.

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: purpose, args, response format, and limits. Every sentence adds value without redundancy. It is appropriately sized for the complexity of the tool.

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

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

Given the absence of an output schema, the description fully explains the return value structure (tracked, expired, snapshot_dates) and their fields. It also covers limits and caveats. Combined with annotations providing safety profile, the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the output structure and clarifies that 'days' is a lookback with a max of 30, but the schema already describes clamping. The description does not add significant new 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?

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs like 'answers' and gives a concrete example differentiating fresh vs aged edges. It distinguishes from sibling polymarket_edges by stating it is built from those snapshots.

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 context for when to use the tool (to understand how long an edge has existed and if it's shrinking) and gives a motivating example. It does not explicitly state when not to use it or name alternatives, but the context is clear.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already confirm safe read-only behavior. Description adds extra context: walks the order-book ladder, returns verdict categories (clean/degraded/cannot_fill), and warns about forced directional risk from thin legs.

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 sections for mode modes, but verbose. Could be trimmed without losing meaning. Front-loaded with purpose and requirements, but the detailed return field list could be 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?

No output schema, but description compensates by listing return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explaining risk modes. Adequately covers edge cases (thin legs, partial fills). Leaves no major gaps for a risk-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% so baseline 3. Description adds value beyond schema: explains single-market vs basket modes, clarifies size_usd semantics (max spend on buys, target proceeds on sells, settlement notional for basket). Adds meaning 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?

Opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb-resource pair. Clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by framing as a pre-trade risk assessment.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides reasoning: theoretical overround on thin books is not capturable, partial fills convert arb into unhedged directional positions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds critical behavioral context: compatibility_warning for non-equivalent bet shapes or unrelated events, temporal_alignment constraints, and detailed skipped_cross_type counters. It discloses when spreads are mathematically meaningless, going well beyond annotations.

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

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

The description is long but well-organized into sections: cross-venue spread explanation, two modes, response fields, and safety fields. It is front-loaded with core purpose. Some redundancy (e.g., repeating 'pre-mapped ≠ tradeable') could be trimmed, but overall it is efficiently 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?

Despite lacking an output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases and provides sufficient detail for an AI agent to understand outputs without a 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?

Parameter schema coverage is 100% with individual descriptions. The description adds rich context by explaining the two modes, providing examples, and detailing how topic shortcuts map to events. This extra guidance aids correct parameter selection.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit) and explains what the response contains, distinguishing it from related sibling tools like polymarket_arbitrage and compare_entities.

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

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

The description explains when to use each mode, and warns that real spreads are rarer than pre-mapped topics suggest, advising caution. It also notes that temporal_alignment must be true for meaningful spreads. However, it does not explicitly name alternative tools or provide direct 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping details (by identifier) and pairing behavior, enhancing transparency.

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

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

Three sentences each serve a purpose: core function, usage context, and scoping/pairing. No fluff; front-loaded with action.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers core functionality, use cases, scoping, and related tools comprehensively.

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

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

Schema coverage is 100%, but the description adds value by explaining the effect of omitting the key parameter (lists all keys), which is not in the schema.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys when the key argument is omitted. It distinguishes its purpose from sibling tools like 'remember' and 'forget'.

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

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

It provides explicit use cases (retrieve stored context like ticker, address, research notes) and recommends pairing with 'remember' and 'forget'. It lacks explicit 'when not to use' but offers strong guidance overall.

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

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

The description adds behavioral context beyond annotations, such as the ability to mark events read and the effect on subsequent calls. Annotations indicate readOnlyHint and idempotentHint, but the description reveals a non-read side effect (mark_read), which is a minor inconsistency but not a contradiction as the primary operation remains read.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence contributes meaningful information without redundancy.

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

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

The description explains what returned fields to expect (source, citation_uri, raw event payload), but lacks details on limit handling or pagination. For a tool with no output schema, this is adequate but could be more thorough.

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

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

The schema already provides parameter descriptions (100% coverage). The description adds value by providing a concrete example for the 'type' parameter ('sec_8k') and clarifying the expected format for 'since' (ISO timestamp) and the effect of 'mark_read'.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool returns (alerts with source, citation_uri, raw payload) and distinguishes it from siblings like list_subscriptions by focusing on event data retrieval.

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 that 'Polls work fine' and provides an alternative endpoint for scripts/dashboards, giving context on usage. However, it does not explicitly state when to use this tool versus other tools or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral detail: fan-out to multiple sources, GDELT→GNews fallback logic, PatentsView API sunset (soft-fail), return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions.

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

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

The description is relatively long but front-loaded with natural language query patterns. Every sentence adds necessary detail (sources, fallback, parameter formats, return structure). Could be slightly more streamlined, but the density of information is appropriate for a complex tool.

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

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

Given the tool's complexity (multiple sources, fallback logic, window parameter, no output schema), the description is remarkably complete. It covers all input variations, explains the output structure, and provides usage boundaries. No gaps remain for an AI agent to infer.

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

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

Schema coverage is 100%, but description adds meaningful context beyond schema: explains accepted formats for 'since' (ISO or relative), gives example values ('3m', '1y'), clarifies 'value' can be ticker or CIK, and confirms 'type' is limited to 'company'. This enriches parameter understanding.

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

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

The description clearly explains the tool as a change feed for companies, with concrete query examples ('What's new with X', 'updates on Acme'). It distinguishes from the sibling tool entity_profile by stating when to use the alternative, making the purpose unambiguous.

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

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

Explicitly states when to use this tool vs entity_profile ('Use entity_profile instead when you want the static profile...'). Also provides contextual guidance: 'Fans out to SEC EDGAR, GDELT→GNews fallback, USPTO' and explains parameter formats (ISO date or relative shorthand).

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: scoped by identifier, persistent for authenticated users vs 24-hour retention for anonymous sessions. 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?

Four sentences, front-loaded with main purpose and examples, no wasted words. Efficiently communicates all essential 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?

For a simple 2-param tool with no output schema, the description covers purpose, when to use, behavioral traits, and links to sibling tools. Nothing missing.

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

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

Schema descriptions cover both parameters fully (100% coverage). The description adds no new semantic detail beyond the schema, so baseline score applies.

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

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

Clearly states the tool saves data for later reuse, gives concrete examples (ticker, address, preference), and explicitly differentiates from sibling tools 'recall' and 'forget'.

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

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

Provides clear when-to-use guidance ('when you discover something worth carrying forward') and mentions pairing with recall/forget, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it cascades through multiple lookups and replaces 2-3 manual steps, and details what each type returns (e.g., ticker+CIK+company_name for company). 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?

Efficiently written with clear examples, a 'Use FIRST' directive, and no wasted words. Information is front-loaded with the question-phrase pattern.

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

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

Covers all essential aspects: supported types, input variations, return format (canonical IDs), internal cascading behavior, and how it simplifies workflows. No output schema, but description adequately explains return values.

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

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

Schema coverage is 100%, but description adds significant meaning: explains that 'company' accepts ticker, CIK, or name, and that 'drug' accepts brand or generic name. Also describes the output format for each type.

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 resolves names to canonical IDs, with specific examples (ticker, CIK, RxCUI). It distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and lists supported types. 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 that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also mentions the optional API key requirement for Anthropic model. These details add behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.), which only confirm safety and idempotency. The description could further clarify if calls are sequential or parallel.

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 (5 sentences) and front-loaded with the main purpose. Every sentence adds value: purpose, process, use case, and return format. No unnecessary words or repetition.

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

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

Given the tool's complexity (4 parameters, no output schema), the description covers the main behavior and returned data. It explains the probing, ranking, and output fields (score, confidence, signal density). However, it does not describe error handling or edge cases (e.g., entities not found). The presence of annotations for safety and idempotency helps, but the description is still slightly incomplete.

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% (all 4 parameters described). The description adds semantics not present in the schema: it explains that the first entity in the array is treated as the subject and the rest as competitors, and that the context is applied to every probe. This goes beyond the schema's 'Array of 2-8 entities to compare' and 'Optional shared context applied to every probe.'

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and the resource 'AI visibility'. It distinguishes from siblings by explicitly mentioning it uses ai_visibility_check per entity and ranks results, which is different from tools like ai_visibility_check (single entity) or compare_entities (general comparison).

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use (multi-entity comparison) and explains that the first entity is the subject and the rest competitors. However, it does not explicitly state when not to use (e.g., for single-entity checks, use ai_visibility_check instead).

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 read-only, open-world, idempotent, non-destructive. Description adds that the tool fans out across deps.dev and bundlephobia, explains graceful degradation with partial failures, potential 5-30s delay for first measurement, and lists return fields. 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?

Description is informative and well-structured, front-loading the primary purpose. While comprehensive, it remains focused and avoids unnecessary verbiage.

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

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

Although there is no output schema, the description thoroughly details the return data including summary block, per-advisory details, links, and alternative versions. It also addresses partial failure behavior, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that scoped packages are accepted and the version defaults to latest when omitted, improving clarity beyond the schema.

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

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

The description uses a specific verb ('scan') and resource ('dependency'), defines the tool as a composite check for npm packages covering licenses, advisories, and bundle size. It clearly distinguishes from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, or cost of adding an npm package. Also specifies limitations (NPM only in v1) and directs other ecosystems to deps.dev:version directly.

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, etc. Description adds valuable behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), cosine similarity over 500-char windows, and that every passage has an offset. No contradiction with annotations.

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

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

Description is fairly long but well-structured with key information front-loaded. Each sentence adds value, covering purpose, usage, technical details, and limits. Could be slightly more concise, but no wasted text.

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?

Tool is moderately complex with semantic search, embedding parameters, and truncation. Description covers all necessary aspects: input constraints, output format (passages, offsets, scores), and integration hints. No output schema exists, but description adequately explains return value.

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%: all three parameters have descriptions. Description adds examples for query and clarifies limit range (1-20, default 5). This provides marginal extra value beyond schema, justifying slightly above baseline.

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

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

Description clearly states it performs semantic search inside a fetched record. It specifies the verb 'search within', the resource (a record), and adds concrete details like returning passages with character offsets and similarity scores. It distinguishes from sibling 'ask_pipeworx_grounded' by describing a paired workflow.

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

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

Explicitly says when to use: when the record is too large for the prompt. Also describes integration with ask_pipeworx_grounded, implying an alternative. No 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?

Beyond annotations (idempotentHint=true, readOnlyHint=false), the description adds significant behavioral details: requires OAuth account, type-specific params, delivery constraints (sms cap of 10/day, webhook auto-disabled after 10 failures, signing secret returned once per webhook). This provides a comprehensive picture for the AI agent.

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

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

The description is efficiently structured, starting with the primary purpose, then listing types and delivery channels. It is moderately concise, with each sentence contributing meaningful information. Slightly verbose in the webhook details, 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?

Given the complexity (3 params, nested objects, no output schema), the description covers prerequisites, types, delivery options, and limitations (sms cap, webhook auto-disable). It lacks explicit mention of error responses or idempotency semantics, but the return value (subscription id) is stated, making it largely complete.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with concrete examples (e.g., sec_8k: {ticker:"AAPL", items:["5.02"]}) and detailed constraints (e.g., sms must be verified phone, webhook signing details). This adds substantial value beyond the schema.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specific verb-resource pair distinguishes it from sibling tools like list_subscriptions (listing) and unsubscribe (removing).

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

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

The description provides context on when to use the tool, such as the requirement for a Pipeworx OAuth account (anonymous/BYO cannot persist), and lists supported types with examples. It indirectly references alternatives like recent_alerts for pulling the feed, but does not explicitly state when not to use this tool beyond the account requirement.

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?

All annotations indicate a safe, read-only, idempotent operation. The description adds transparency by detailing the output format (category-bucketed questions with tool shapes) and that it's drawn from a live catalog. 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?

Front-loaded with common entry-point queries, then concise statements of output and usage. Every sentence is informative and necessary. No fluff.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed examples with tool+argument shapes). Covers all aspects: purpose, usage, parameters, and result structure.

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

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

The single optional parameter topic is explained with examples in the description (e.g., 'finance', 'pharma'), adding value beyond the schema description. Schema coverage is 100% and the description complements it 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 starts with common user queries, then clearly states it returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly instructs to use this FIRST when the agent does not know what Pipeworx can do, and provides guidance on using the topic parameter to focus. No alternatives needed.

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

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

The description adds significant behavioral detail beyond annotations: it explains that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. This aligns with 'destructiveHint: false' and 'idempotentHint: true'.

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

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

Two sentences, front-loaded with the main action, no wasted words. 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?

For a simple mutation tool with a single parameter and no output schema, the description covers ownership, the deactivation behavior, and the link to 'recent_alerts', providing complete context for correct invocation.

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

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

The input schema describes the single parameter 'id' with a clear description ('uuid returned by subscribe'), and schema coverage is 100%. The description adds no further semantic meaning beyond 'by id'.

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 'Cancel' and the resource 'subscription by id', and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement.

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 that only own subscriptions can be canceled, implying the user must have the subscription id from 'subscribe'. It lacks explicit when-not or alternative tools, but the sibling list includes no other cancel 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 indicate safe, non-destructive, idempotent behavior. The description adds behavioral context: returns a verdict with structured output, actual value, citation, and delta, and explains data sources (SEC EDGAR + XBRL). 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 front-loaded with example queries and is concise overall, though slightly lengthy in explaining replacements. Every sentence provides meaningful information without redundancy.

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

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

For a tool with one parameter, no output schema, but clear annotations, the description fully explains its purpose, usage, scope, and outputs. It is self-contained and sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The description adds value by providing real-world examples and clarifying supported claim types (company-financial claims for public US companies), which goes beyond the schema's minimal description.

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

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

The description starts with clear examples of natural-language queries, explicitly states it is for 'natural-language claim verification against authoritative sources', and specifies the verb 'validate' and resource 'claim'. It distinguishes itself by mentioning it replaces multiple sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', providing clear context. It also notes the current scope (v1 supports company-financial claims) but does not explicitly mention when not to use it or list alternatives beyond the sibling tools present.

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