Overpass

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

The description adds significant behavioral information beyond the annotations: it states the default model, the requirement for '_apiKey' to probe Anthropic, the BYO key model, and the return structure (per-model score, confidence, signals, raw_response). Annotations already indicate read-only and idempotent behavior, and the description reinforces this 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 concise (three sentences) and front-loaded with the core action. Every sentence adds value—from the primary function to use cases to the API key requirement. No extraneous information.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is complete: it explains the main function, optional probing, model selection, return structure, and use cases. The lack of output schema is compensated by the explicit mention of return fields.

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 minimal value beyond the schema: it mentions the default model (workers-ai) and notes that context helps disambiguate, but these are already implied or stated in the 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 uses a specific verb ('probe') and describes the resource ('LLMs for what they know about a business/brand/product/topic') with a clear output ('score 0-100 per model'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on general visibility scoring rather than competitor-specific scanning.

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

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

The description explicitly states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context. It does not exclude alternative tools or specify when not to use, but the given guidance is sufficient for most use cases.

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

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

Annotations already indicate readOnly and idempotent behavior. Description adds that it routes to one of many tools, fills arguments, and returns structured answers with citation URIs. This gives operational 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?

The description front-loads key information and is well-organized, but is somewhat verbose. Each sentence adds value, but it 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?

Given the tool's complexity and lack of output schema, the description provides sufficient context about its operation and use cases, though it omits details about error handling or response 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?

Schema coverage is 100% and description adds minimal value beyond the schema, merely restating that the input is a natural language question. 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 many sources and returns structured answers with citations, explicitly contrasting with web search. However, it does not differentiate from its sibling ask_pipeworx_grounded, which could cause confusion.

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 this tool over web search, listing specific types of questions and query phrases, even stating to use it when web search could also answer. This is highly actionable.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: it uses routing, extracts answer only from tool result, returns explicit refusal reasons, and costs an extra LLM call. No contradiction exists; the description enriches the safety profile.

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 well-structured: first sentence states purpose, second explains routing and extraction, third defines return format and refusal reasons, fourth gives usage guidance, fifth cost comparison. It is front-loaded with purpose but could be slightly more concise; still earns its place.

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

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

Given the complexity of the tool (multi-step routing, extraction, explicit refusals), the description covers routing behavior, extraction constraints, return format with all fields, use cases, and cost. No output schema exists, so description must explain return values, which it does in detail. Contextually complete.

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

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

Schema coverage is 100% with descriptions for all parameters, so baseline is 3. The description adds only 'Your question in natural language' and lists aliases, which adds minimal semantics beyond the schema. No extra value beyond what the schema provides.

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

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

The description clearly states the tool is 'hallucination-resistant answer mode for high-stakes reads' and explains its process: routes to the right tool, fetches data, and extracts answer using only the tool result. It distinguishes from sibling 'ask_pipeworx' by noting the extra cost and use case, showing a specific verb+resource and sibling 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 explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and provides examples like financial verdicts, legal claims, medical lookups, public statements. It also says 'prefer ask_pipeworx for casual lookups,' giving clear when-to-use and when-not-to-use guidance with an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds extensive behavioral details: resolution confidence levels, parent event extraction, news error handling, safety short-circuits for low confidence and closed markets, spread liquidity checks, cancellation rule parsing. 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?

Front-loads main purpose and usage, but becomes very detailed with classifiers, examples, response shapes, and edge cases. While every sentence adds value, the density could be better organized. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (3 params, many classifiers, fan-out logic, response fields, safety mechanisms), the description covers all necessary aspects: input formats, behavior variations, response structure with evidence, analysis, market match confidence, parent events, news error handling, resolution rules. No output schema, so description fully compensates.

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%. Description adds extra context: explains market input can be slug, URL, or question text; depth options (quick vs thorough) with default; include_raw behavior and response size implications. This goes 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?

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. Specific verb 'research' and resource 'Polymarket bet' with input types (slug, URL, question text). Distinguishes from siblings like polymarket_edges which scans multiple bets.

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 cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and fan-out examples. Does not explicitly exclude cases where siblings might be better, but context is clear enough for an agent to decide.

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 details beyond the annotations, such as handling off-calendar fiscal years correctly, returning paired data with citation URIs, and sorting results by primary metric. Annotations already declare it as read-only and idempotent, so the description complements without contradiction. Minor gap: no mention of potential rate limits 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 relatively long but well-structured, starting with example queries and then detailing behavior per type. Every sentence adds value, explaining when to use, what data is pulled, and results. Could be slightly more condensed, but overall efficient.

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

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

Given no output schema, the description explains that the tool returns 'paired data + pipeworx:// citation URIs per entity' and that results are sorted by primary metric. For a comparison tool with moderate complexity, this provides sufficient completeness. Minor gap: exact format of output is not detailed, but the behavioral notes are 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 the description elaborates on both parameters: for 'type' it specifies the data sources (10-K for company, FAERS/FDA/trials for drug), and for 'values' it explains constraints (2–5 items, tickers/CIKs vs drug names) and provides examples. This adds meaningful context beyond the schema.

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

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

The description clearly states that the tool performs a side-by-side comparison of 2–5 companies or drugs. It provides specific examples of queries that trigger the tool and explicitly describes the data pulled for each entity type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs). This distinguishes it from siblings like entity_profile which 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes that it replaces 8–15 sequential lookups. This provides clear guidance on when to use the tool. However, it does not explicitly mention scenarios where this tool should not be used compared to other sibling tools, such as entity_profile for single entities.

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 behavioral context: the tool never invents facts, returns explicit gaps[], and provides pre-verified findings with citations. Also mentions latency and plan restrictions.

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 the core value proposition. While somewhat long, every sentence adds meaningful information such as prerequisites, latency, and output details.

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

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

For a complex tool with 2 parameters and no output schema, the description covers purpose, usage guidance, behavior, prerequisites, and output format (structured findings packet with gaps). It is fully 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% with descriptions for both parameters. The description adds value by explaining depth values (quick=3, standard=5, thorough=8) and clarifying the question parameter can be broad/multi-part.

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 performs grounded multi-source research by decomposing questions into sub-questions and routing to 3,745 tools. It distinguishes itself from ask_pipeworx by specifying it's for broad/multi-part questions vs. single lookups.

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

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

Explicitly says 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups'. Also specifies prerequisites: Pipeworx account, paid plan for thorough depth, and expected latency of 15-60s.

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 value beyond annotations: specifies that results include full schemas with curated examples and are ready to call directly. Annotations already indicate read-only and idempotent, so description complements well.

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

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

Description is packed with useful information but slightly longer than necessary. Front-loaded with core purpose, but could be trimmed slightly for even better 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 is a discovery tool with no output schema, the description covers input usage, return content (tool names, descriptions, schemas, examples), and strategic 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%, and description explains that 'query' is the natural language input and lists accepted aliases (task, q, search, description). Adds meaningful context about alias acceptance and example queries.

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 'Find tools by describing the data or task', with specific verb 'discover' and resource 'tools'. Lists multiple domains and distinguishes this as a discovery tool among many sibling tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Provides clear context but no explicit when-not-to-use 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant value by detailing the cross-source fan-out behavior, specific return fields (CIK, filings, fundamentals, patents, news, LEI), and limitations (e.g., patents sunset May 2025, names not supported). 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 front-loads example queries and states the main purpose succinctly. However, it is somewhat verbose with detailed enumerations of return fields and sources. Still, it maintains a logical flow and contains no wasted sentences.

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 2 params, no output schema, but rich annotations, the description fully covers what the tool does, what it returns (with specific fields and sources), limitations, and prerequisites (e.g., ticker or CIK only). It leaves no significant gaps for the agent.

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

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

Schema coverage is 100% with enum for type and description for value. The description reinforces this with concrete examples (e.g., 'AAPL', '0000320193') and reiterates that names are not supported. While it adds clarity, it does not introduce new constraints 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 starts with example natural language queries and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly indicates the tool's primary function and distinguishes it from sibling tools by advising to prefer over chaining single-source lookups and referencing resolve_entity for name resolution.

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

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

The description explicitly states when to use this tool (holistic view requests) and when not (if only a name is available, use resolve_entity first). It also provides behavioral context like patents soft-failing and names not supported, giving clear guidance for agent decision-making.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description reinforces the destructive nature ('Delete', 'clear sensitive data') and adds context about what gets destroyed (memories). No contradictions, and the description adds useful behavioral context beyond the annotations.

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

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

The description is very concise: two sentences. The first sentence states the core purpose, the second provides usage context. No redundant or unnecessary information, and it is front-loaded with the most important 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 tool with one parameter and no output schema, the description covers the purpose, context of use, and sibling relationships. It could optionally mention behavior on missing keys or confirmation, but given the tool's simplicity and annotations covering destructive behavior, it is adequately 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?

Only one parameter 'key' with schema description 'Memory key to delete'. The description also mentions 'by key', but does not add new information beyond what the schema already provides. Since schema coverage is 100%, baseline of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and resource ('a previously stored memory by key'). It distinguishes itself from sibling tools by mentioning pairing with 'remember' and 'recall', making its unique role evident.

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 context is stale, the task is done, or you want to clear sensitive data'. Implicitly contrasts with siblings (remember for storing, recall for retrieving), providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds process details (fetches, extracts, emits) and output format (text blob). It does not contradict annotations. Missing details on error handling or rate limits, but overall transparent.

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), front-loaded with the core purpose, and contains no redundant information. Every sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all essential aspects: what it does, how it works, output format, and use cases. The mention of specific AI crawlers adds helpful 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 description coverage is 100%, so baseline 3. The description does not add additional semantics for 'url' or 'max_links' beyond what the schema provides. No extra guidance on valid values or formatting.

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 'generate' and the resource 'llms.txt file'. It specifies the action: fetching a page, extracting title/description/key links, and producing a standard format. The purpose is distinct from sibling tools, as none perform this specific function.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). However, it does not mention when not to use or provide alternatives. Given the tool's uniqueness among siblings, this is a minor gap.

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

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

Annotations already declare readOnlyHint and destructiveHint, so description adds value by listing return fields (id, type, params, etc.) and scope ('active'). 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?

Two succinct sentences: first communicates purpose and output, second provides usage guidance. No redundant information.

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

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

For a simple, optional-parameter tool with no output schema, the description adequately covers return fields and usage context. Minor omission: no mention of pagination or default limit, but acceptable for this level of 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 documentation covers the only parameter (include_inactive) fully. Description adds no additional semantics beyond baseline, which is 3 when coverage is 100%.

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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from siblings like 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 the tool to review monitored subscriptions before adding more or to find an ID to cancel, indicating when-not-to-use and alternatives.

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

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

Discloses key behaviors beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and feedback signals directly affect roadmap. Annotations (readOnlyHint=false) are consistent; 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) and front-loaded: first sentence states purpose, then usage, then behavioral notes. No wasted words, each sentence adds 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?

Given the simple tool (3 params, nested object, no output schema), the description covers all necessary aspects: what it does, when to use, how to format feedback, limitations, and impact. No gaps.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds value by advising on message content ('don't paste the end-user's prompt') and contextualizing the feedback type enum. Slightly above baseline due to this extra guidance.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/send feedback) and resource (Pipeworx team). It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback, not queries.

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: for bugs, features/data gaps, or praise. Also provides exclusions ('don't paste the end-user's prompt') and mentions rate limits and quota. This gives clear guidance on selection vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds: self-aggregating from CF analytics-engine, no PII, and caching (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?

Three sentences, front-loaded with purpose, then details. 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?

No output schema, so description should explain return format more. It only says 'top tools, top packs, and total call volume' but not structure (e.g., list of objects, counts). Adequate but not complete.

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

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

Schema coverage is 100% with one parameter described. The description adds context on window behavior (shorter = hot, longer = steady-state), going beyond the schema's enum list.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with three specific use cases. It distinguishes from siblings like discover_tools by focusing on trending data.

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

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

The description explicitly lists three use cases when to use this tool (discovering hot sources, confirming canonical tools, aligning use cases). It provides window guidance but lacks explicit 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns OSM POIs and clarifies the bounding box coordinate order (south, west, north, east). This adds useful behavioral context without contradicting the annotations.

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

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

The description is concise with three sentences. The first sentence states the purpose, the second gives usage examples, and the third clarifies coordinate order. No unnecessary words, well-structured.

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

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

Given the moderate complexity, full schema coverage, and presence of an output schema, the description is sufficient. It provides usage examples and coordinate order. It could mention the limit parameter briefly, but the schema covers that. Overall, it meets the needs 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the bounding box coordinate order (south, west, north, east) which is not explicitly stated in the schema descriptions. The examples in the schema also help, but the description reinforces the usage.

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 'Find OSM POIs inside a bounding box,' which is a specific verb+resource. It provides concrete examples like 'every park in this area' or 'all restaurants in this neighborhood,' clearly distinguishing it from sibling tools like pois_near which likely do point-based searches.

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

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

The description explicitly says 'Use for...' with examples, giving clear context on when to use this tool. While it does not explicitly mention when not to use it, the examples and the existence of sibling tools like pois_near imply the alternatives. The guidance is adequate but could be more explicit about exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds beyond annotations by stating that the tool returns nodes with names, tags, and coordinates. This provides useful behavioral context about the output, though it does not mention potential issues like rate limits or pagination.

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

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

The description is extremely concise, consisting of two sentences that convey all necessary information without redundancy. It is front-loaded with the core action and follows with essential details. Every sentence earns its place.

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

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

Given the presence of an output schema, the description does not need to detail return values. It adequately covers the primary use case of finding POIs by tag and radius. However, it could mention limitations like OSM data freshness or coordinate system, but overall it is complete for a simple tool.

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

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

Input schema has 100% coverage with descriptions for all parameters. The description adds value by providing concrete examples and clarifying the tag syntax (e.g., 'amenity=cafe' or just 'amenity'). This helps the agent understand how to construct valid tag filters beyond the schema's generic 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 specifies the verb 'Find', the resource 'OSM points of interest', and the mechanism 'within a radius of a lat/lon'. It provides specific tag examples, making the purpose immediately clear and differentiating from sibling tools like places_in_bbox which likely uses a bounding box.

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 clear usage guidance by explaining the tag parameter and providing example values. However, it does not explicitly state when not to use this tool or mention alternatives like places_in_bbox for rectangular areas. Sibling differentiation is implied but not explicit.

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

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

Annotations already declare the tool as read-only and idempotent, so no mutation concerns. The description adds substantial behavioral context: it walks child markets, applies Jaccard similarity and placeholder filters, and includes a fill check against live book depth. It discloses that calling with no args fails. No contradictions with annotations.

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

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

The description is dense and informative but lacks conciseness and structured formatting (e.g., bullet points). It contains multiple sections and technical details that are valuable but could be more efficiently organized. It is not tautological, but every sentence earns its place, making it adequate but not optimally 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 and lack of output schema, the description thoroughly explains the return values (opportunities array with gap_pp, suggested_trade, etc.) and the partition_check object. It also covers edge cases like the fill check and Jaccard similarity. The description is complete for an AI agent to understand what the tool does and how to interpret results.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: for event it specifies slug format and URL acceptance; for topic it explains seed question interpretation and cross-event scanning behavior. It also mentions semantic anchor and partition filter, enriching parameter semantics beyond the schema.

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

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

The description clearly explains that the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with distinct event and topic modes. It is specific about what it does, but lacks explicit differentiation from sibling tools like polymarket_edges or polymarket_fill_risk, leaving some ambiguity.

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 guidance on when to use event mode (specific market) vs topic mode (cross-event scanning), recommends event mode for specific markets, and notes that calling with no arguments fails. It also points to polymarket_fill_risk for custom sizing, offering an alternative. However, it does not explicitly state when not to use the tool beyond the fill check condition.

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, idempotentHint, and non-destructive. The description adds extensive behavioral context: cached 1h at KV level, diagnostics structure, Fed data unreliability note, and detailed model assumptions. 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 very dense and includes technical model details (e.g., 'lognormal barrier from 90d FRED log-returns') that may not be essential for tool selection. While well-structured with segments and diagnostics, it 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?

Given the complexity (9 parameters, no output schema), the description is exceptionally complete. It explains output structure (by_segment, diagnostics), caching behavior, all parameters, and model families. It provides everything an agent needs to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and providing usage guidance for min_partition_leg_kelly and slippage_pp. This extra context justifies a higher score.

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 verb (scan, return) and resource (top Polymarket markets, opportunities where Pipeworx data disagrees with market price). It also specifies the use case 'what should I bet on today'. The detailed explanation of model families and segments distinguishes it from siblings like polymarket_arbitrage.

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 when to use: 'agents discover opportunities without paging hundreds of markets'. It also provides context for tradeable-edge knobs (min_liquidity, max_spread_pp) and format filters. However, it does not explicitly state when not to use or compare directly with alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it reads from daily snapshots, snapshots are written on cache-miss, gaps mean no scan, and history is limited by 60-day TTL. No contradictions with annotations.

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

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

The description is detailed and well-structured, front-loading the purpose. It is slightly verbose but every sentence adds value. Could be more concise without losing clarity.

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 exhaustively explains the response structure including tracked[], expired[], and snapshot_dates[] with subfields. This covers all necessary context for a complex telemetry tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters (days, window). The description repeats defaults but adds no 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?

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by adding time-series analysis, making the purpose specific and actionable.

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 the use case by contrasting fresh vs. old edges, implying when to use it to assess edge quality. It also notes limitations (decay from daily closes, not intraday). However, it does not explicitly list 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral context: requires one of market/event, walks ladder, returns fields (top_of_book, vwap_fill_price, etc.), warns about basket fill risk and directional risk. No contradictions.

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

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

Front-loaded with core purpose, well-structured with line breaks and capitalization for modes. Some verbosity but every sentence adds value. Efficient for the complexity.

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

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

No output schema, but description comprehensively lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), covers warnings about partial fills and directional risk. Complete for a complex tool.

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

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

Schema coverage 100% with descriptions. Description adds meaning beyond schema: clarifies size_usd as 'settlement notional' for basket, side default 'auto' for basket, and explains how each parameter is used in modes (walks ladder, per-leg detail). Baseline 3, plus extra value gives 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?

States specific action: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes between single-market and basket modes. Differentiates from siblings by explicitly recommending use before polymarket_arbitrage or polymarket_edges signals.

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

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

Explicit when-to-use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Implies when not: small trades below $500. Explains risks of partial fills converting arb to directional position.

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

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

Annotations already mark it as readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: detailed compatibility warnings, skipped cross counters, temporal alignment checks. No contradictions with annotations.

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

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

The description is dense but every sentence adds value. It is front-loaded with purpose and modes. Could be slightly more structured (e.g., bullet points for modes), but not overly verbose. Efficiently communicates complex behavior.

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

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

Given no output schema, the description thoroughly explains response fields, edge cases, and safety signals. It covers leg shape mismatches, temporal alignment, and compatibility warnings. Comprehensive for a complex tool with many nuances.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context (e.g., topic shortcuts list, override logic) but does not add essential meaning beyond the schema for understanding the parameters. 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 computes a cross-venue spread between Kalshi and Polymarket. It specifies the verb 'cross-venue spread' and the resource (two prediction markets). It distinguishes from siblings like 'polymarket_arbitrage' by focusing on cross-venue vs intra-venue. Not a tautology.

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 explains two modes (topic vs explicit) and when to use each. It warns about compatibility_warning cases and states 'pre-mapped ≠ tradeable'. It does not directly name alternatives but gives clear context for when spreads are meaningless.

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 confirm read-only, idempotent, non-destructive behavior. The description adds context on raw query execution and return format, enriching transparency beyond 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?

Two clear sentences plus an example, no fluff. The key action and use case are front-loaded, making it efficient for an agent to process.

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 (one parameter), annotations covering safety, and an existing output schema, the description sufficiently covers purpose, usage, and expected output. No gaps remain for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already describes the qql parameter format. The description adds an example but does not introduce new parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it runs a raw Overpass QL query against OpenStreetMap, with a specific verb and resource. It distinguishes itself from sibling helper tools by targeting complex queries they can't express.

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 use when helper tools are insufficient, provides a concrete example, and notes the raw JSON return. This gives clear when-to-use and when-not-to-use context relative to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping context ('Scoped to your identifier') and behavior when key omitted. 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?

Two sentences, front-loaded with main action. Every sentence adds value. No fluff.

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

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

Given low complexity (1 optional param) and annotations, description covers retrieval, listing, scoping, and tool relationships. Complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining that omitting key lists all saved keys and relates to remember/forget pairing, enhancing 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?

Description starts with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' Clearly states the tool's capability and distinguishes 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 use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also pairs with remember/forget. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining that alerts carry source, citation_uri, and raw payload, and that mark_read flags events as read for subsequent calls. 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 concise at four sentences, front-loaded with the main purpose, and includes essential details 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 no output schema, the description explains the return shape (source, citation_uri, raw payload), covers all parameters, discusses mark_read behavior, and mentions an alternative access method. It is comprehensive for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema for 'type' (example 'sec_8k'), 'since' (ISO timestamp), and explains the behavior of 'mark_read' (flags returned events read). Does not add for 'limit' or 'unread_only', but overall adds useful context.

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

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

The description clearly states the verb 'pull' and resource 'fired events from your subscription feed', and specifies what each alert carries. It distinguishes from sibling tools like list_subscriptions by focusing on retrieving events rather than managing subscriptions.

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

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

The description provides guidance on filtering by type and since, setting mark_read, and mentions that polling works fine. It also gives an alternative endpoint for scripts, but does not explicitly state when not to use this tool or compare to siblings.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral details: parallel calls across sources, fallback logic, soft-fail for USPTO, and the return structure with citations. 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 purpose, but it is somewhat lengthy. It could be slightly more concise without losing important details. However, 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?

Despite lacking an output schema, the description fully describes the return format (structured changes[], total_changes, citation URIs). It covers all relevant aspects: sources, fallbacks, parameter formats, limitations (company only, USPTO soft-fail), and distinguishes from sibling tools.

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

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

Schema coverage is 100% with descriptions. The description further clarifies parameter semantics: it explains that 'since' accepts ISO dates or relative shorthand (with examples like '7d', '30d', '3m', '1y'), that 'value' can be ticker or CIK, and recommends '30d' or '1m' for typical monitoring. This adds significant 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 purpose: providing a change feed for a company over a time window by fanning out to multiple sources (SEC filings, news, patents). It distinguishes itself from the sibling tool 'entity_profile' by specifying when to use the latter 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?

Explicit usage examples are provided (e.g., 'What's new with X'), along with guidance on when to use alternatives ('Use entity_profile instead for static profile'). It also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO, giving clear context for appropriate invocation.

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

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

The description adds context beyond annotations: it explains the key-value nature, scoping, and expiration behavior. Annotations already indicate idempotent and non-destructive, which aligns with the description's implication of overwriting on same key.

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 sentence states purpose, second gives usage context, third provides technical details. It is concise, front-loaded, and contains no filler.

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

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

The tool is simple and the description covers key aspects: purpose, usage, scoping, persistence. However, it does not explicitly state that setting the same key overwrites the value (implied by idempotent). Overall adequate for a write-only 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 description coverage is 100% for both key and value, so the baseline is 3. The description does not add additional meaning beyond what the schema provides.

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

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

The description clearly states that the tool saves data for reuse across conversations or sessions, and provides concrete examples like resolved tickers and user preferences. It distinguishes itself from siblings recall and forget by explicitly naming them as complementary tools.

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

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

The description explicitly says to use the tool when discovering something worth carrying forward, notes scoping by identifier, and clarifies persistence differences between authenticated and anonymous sessions. It also advises pairing with recall and forget.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds value by revealing internal cascading lookups and that it replaces 2-3 manual steps. 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 well-structured with examples, supported types, and a behavioral note. It front-loads common queries. While slightly long, 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?

Without an output schema, the description fully details return values for both entity types, including citation URIs. It also explains the cascading behavior, making the tool's behavior fully predictable.

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 enhances understanding by specifying accepted input formats for each entity type (e.g., ticker, CIK, name for company; brand/generic for drug), going beyond the schema's descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with examples of common queries. It distinguishes from sibling tools like entity_profile by emphasizing it's the first step for ID 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID,' which provides clear context. Lacks explicit when-not-to-use guidance but implies the primary use case.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint but the description adds value by explaining the internal mechanism (probes with ai_visibility_check), the ranking logic, and the returned fields (score, confidence, signal density). 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-4 sentences, front-loaded with the core purpose, and no superfluous 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers probe method and shared context. Lacks error handling details but that is acceptable given the annotations indicate safe, open-world behavior.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds a few nuances (e.g., first entity treated as 'subject', context shared across probes) but these are minor; the schema already conveys core meaning. Baseline 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes from the sibling tool 'ai_visibility_check' which checks a single entity. It directly states the tool's function: 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 explicitly states the tool is useful for 'competitive AI-marketing audits' and provides an example question. It implies when to use it (when comparing multiple entities) but does not explicitly state when not to use it or mention alternatives beyond the single-entity check.

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

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

The description adds significant behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia may timeout (5-30s), sources_failed lists timed-out sources, and return structure includes summary, advisories, links, and alternative versions. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description enriches with real-world behavior.

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

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

The description is a single paragraph but well-structured: purpose, what it fans out, usage context, return format, ecosystem scope, and failure behavior. Each sentence provides necessary information; no fluff. Slightly longer due to detail, but every sentence earns its place for a composite 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?

Despite lacking an output schema, the description thoroughly explains the return format (summary block fields, per-advisory detail, links, alternative versions). It also addresses constraints (NPM only v1, partial failures) and expected behavior, making the tool fully understandable for invocation.

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

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

Schema coverage is 100% (both params described). The description adds value by clarifying that scoped packages (e.g., @types/node) are accepted for the package parameter and that version defaults to latest published when omitted. This helps the agent understand parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools (no other dependency scan tool exists) and uses specific verbs like 'scan' and 'check' with the resource 'npm package'.

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 this tool: when an agent asks about safety, popularity, size, or cost of adding an npm package. It also clarifies what not to use it for (PyPI, Maven, etc.) and directs to deps.dev directly, providing clear exclusions.

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

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

Discloses embedding model (BGE-base-en), similarity (cosine), window size (500-char overlapping), and character cap (200K chars with truncation flag). Adds significant context beyond annotations which only indicate read-only, idempotent, etc.

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

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

Front-loaded with core purpose, then usage guidance, then technical details. Every sentence adds value. No verbose or redundant phrasing.

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 explains what is returned (passages with offsets and scores) and behavior on truncation. Covers input limits, use case, and integration. Complete for a tool of this complexity.

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

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

Schema already covers all parameters with descriptions. Description adds usage context: text should be 'already pulled', query examples, and default limit of 5. Good complement but schema was already thorough.

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 action (semantic search inside a fetched record), resource (text), and output (top-N passages with offsets/scores). Distinguishes from siblings by specifying it's for large records and pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions pairing with ask_pipeworx_grounded, providing clear alternative guidance.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds value beyond these by explaining that the tool returns the new subscription ID, details account requirements, describes delivery channel behaviors (SMS cap, webhook auto-disable), and gives per-type specifics. However, the idempotentHint annotation is not clarified (e.g., whether creating the same subscription twice returns the same ID or errors), which is a minor gap.

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 front-loaded main purpose and return type, followed by requirements, types, and delivery details. Every sentence adds value. While it is relatively long, the length is justified by the complexity. Minor redundancy in the delivery channel descriptions could be tightened, but overall it is efficient.

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

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

Given the tool's complexity (3 parameters including nested objects, no output schema), the description covers purpose, prerequisites, all supported types with examples, and delivery options with constraints. It lacks explicit mention of error handling or rate limits beyond the SMS cap, but it provides sufficient information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description provides extensive additional meaning. It explains each type's purpose, gives concrete parameter examples for 'sec_8k', 'polymarket_edge', 'fred_series', and others, and details the delivery object with constraints, verification requirements, and webhook signing. This transforms the schema from a list of properties into actionable guidance.

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

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

The description starts with a clear verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create) and resource (subscription), and it distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation. The purpose is 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 the tool (to create a subscription) and provides prerequisites (requires Pipeworx OAuth account, anonymous/BYO not supported). It does not explicitly state when not to use it or mention alternatives, but the context is clear enough given the tool's specific creation role. The examples for each type give practical 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 provide readOnlyHint, openWorldHint, idempotentHint. The description adds behavior: returns category-bucketed example questions with tool+argument shapes, drawn from a live catalog. It details call modes (no args for full spread, topic to focus) and output structure, adding significant value beyond annotations.

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

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

The description is front-loaded with example queries and well-structured, but slightly verbose. It efficiently covers purpose, usage, and output without redundancy, but could be trimmed 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 simplicity (one optional param, no output schema), the description is fully adequate. It explains output format, usage patterns, and integration with other tools, leaving no gaps for an agent to interpret its behavior.

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

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

Schema description coverage is 100% (the 'topic' parameter description lists possible values and behavior). The tool description restates the same information without adding new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool is an onboarding entry point that suggests example questions. It specifies the resource (Pipeworx) and the action (suggest questions), and distinguishes from siblings like ask_pipeworx and discover_tools by noting it returns example questions with tool+argument shapes.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools like ask_pipeworx. It implies when to use but does not explicitly exclude 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?

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability. This complements the annotations, which already indicate non-destructive and idempotent 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?

Two sentences, 34 words, front-loaded with the primary action. No redundant or extraneous information. Every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully addresses purpose, usage constraints, and behavioral effects. 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?

With 100% schema description coverage and a single 'id' parameter already well-described in the schema, the description adds no additional meaning to the parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description 'Cancel a subscription by id' clearly states the action and resource. It further distinguishes itself by specifying ownership enforcement and deactivation behavior, which differentiates it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states 'you can only cancel your own subscriptions', providing clear when-to-use context. It also explains the deactivation effect, but does not provide explicit when-not-to-use or alternative tool references.

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. The description adds substantial behavioral context: it returns a verdict with five categories, a structured form, actual value with citation, and percent delta. It also discloses that v1 supports only company-financial claims, setting clear expectations.

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

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

The description is a single paragraph that efficiently conveys all necessary information. While somewhat long, it is well-organized and front-loaded with purpose and examples. Every sentence adds value, but it could be slightly more structured.

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

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

Given the tool's complexity (claim verification), the description comprehensively covers input, output (verdict categories, structured form, citation, delta), scope, and benefits. No output schema exists, so the description rightly explains what the tool returns.

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 parameter 'claim' is fully described in the input schema with examples. The description further enriches this by explaining it accepts natural-language factual claims and providing concrete examples, adding value beyond the schema.

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

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

The description clearly states it verifies natural-language claims against authoritative sources, with specific examples and scope (company-financial claims via SEC EDGAR + XBRL). It uses strong verb phrases and sample queries, making the tool's 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?

The description explicitly advises using the tool when the agent needs to check factual correctness of user statements. It mentions replacing multiple sequential calls, but does not explicitly state when not to use it or list alternatives among siblings.

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