Opentopography

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

Annotations already convey read-only, idempotent, non-destructive nature. Description adds value by detailing model defaults, cost implications (free vs BYO key), and return structure, beyond what annotations provide.

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

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

Every sentence adds value; front-loaded with main purpose, followed by model details, return structure, and use cases. No wasted words.

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

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

Despite lacking an output schema, the description explicitly states the return structure (per-model score, confidence, etc.) and combined view. With clear parameters and usage context, the tool is fully understood.

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 clarifies that '_apiKey' is only needed for Anthropic, explains default model, and adds context for 'context' parameter, improving 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?

Clearly states the tool probes LLMs and scores visibility (0-100) per model. Differentiates from siblings like 'scan_competitor_ai_presence' by focusing on scoring rather than mere presence detection.

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

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

Explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Lacks explicit when-not-to-use or alternatives, but context is strong.

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, and idempotentHint. The description adds valuable behavioral context: the tool routes queries to 3,826 tools across 912 sources, automatically fills arguments, and returns stable citation URIs. This goes well beyond the annotations, making the agent fully aware of the tool's operation. No contradictions.

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

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

The description is front-loaded with the key recommendation 'PREFER OVER WEB SEARCH' and efficiently covers purpose and usage in two sentences. The list of domains and examples is helpful but slightly verbose; still, it is well-structured and concise overall.

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 read-only query tool with no output schema, the description provides sufficient context: it explains what the tool does, when to use it, how it works internally (routes to many tools), and what the output includes (structured answer with citations). No gaps evident.

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

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

Schema description coverage is 100% with detailed aliases for the question parameter. The description adds example questions but no additional constraints or formatting guidance. Baseline 3 is appropriate as the schema already fully documents the parameters.

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

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

The description clearly states the tool routes factual questions to a vast set of authoritative sources and returns structured answers with citations. It distinguishes itself from web search, but does not explicitly differentiate from the sibling 'ask_pipeworx_grounded', so it slightly misses the 'distinguishes from siblings' standard for a 5.

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 'PREFER OVER WEB SEARCH' and lists specific query types and examples (e.g., 'current US unemployment rate'), providing clear context for when to use. However, it does not state when not to use or name alternative tools, which prevents a score of 5.

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

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

Discloses extraction-only behavior, refusal reasons, and extra LLM call cost. Annotations already indicate read-only and idempotent, but description adds critical safety mechanisms 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?

Well-structured with front-loaded purpose and logical flow. Each sentence adds value; could be slightly tighter but overall efficient for the detail provided.

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 lack of output schema, description fully explains return format and refusal reasons. For a complex tool, all necessary context is present.

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 aliases clearly documented. Description adds minimal extra meaning beyond 'your question in natural language', so baseline 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, with explicit output format and refusal reasons. Distinguishes from sibling ask_pipeworx by noting extra cost and use case.

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

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

Provides explicit when-to-use ('answer will be quoted, cited, or acted on') and when-not ('prefer ask_pipeworx for casual lookups'), naming the alternative.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral details: resolution, classification, fan-out, response structure, safety mechanisms (low_confidence_match short-circuit, market_closed_or_inactive handling), wide-spread illiquidity notes, 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?

Well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). Front-loaded main purpose. However, it is verbose with extensive fan-out examples and details that could be condensed 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?

Given no output schema, description thoroughly explains response shape (result.market, result.analysis, result.evidence), resolver contract, parent event extractor, news field fallbacks, safety checks, and cancellation rule handling. Covers all essential 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% with clear descriptions. Description adds value by explaining market input types (slug, URL, question text), depth options with defaults, and include_raw recommendation. Examples further clarify 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 starts with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it', clearly stating the verb (Research) and resource (Polymarket bet via Pipeworx). It distinguishes from sibling tools like polymarket_edges by focusing on a single bet's comprehensive data pull.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides context for when to use, but does not explicitly state when not to use or list alternatives, though the sibling tools are differentiated.

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 (readOnlyHint, idempotentHint, etc.), the description reveals data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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?

Well-structured with query examples first, then explanation. Slightly lengthy but every sentence adds value. Could be marginally tighter, but effective.

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

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

Covers all essential aspects: data sources, entity types, sorting, citation URIs. No output schema but return format is described. Completes the picture for an AI 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%, but description adds significant meaning: explains what data is fetched for each type value and gives examples for values array. Enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It gives concrete example queries and distinguishes from sequential single-pack lookups, making the purpose unmistakable.

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

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

Explicitly advises to prefer over sequential lookups, provides example use cases, and explains behavior per entity type. Lacks explicit when-not-to-use scenarios, but guidance is strong.

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 nature. Description adds minimal behavioral context beyond the list action. For a simple tool with no side effects, this is adequate but not rich.

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

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

Single sentence, front-loaded with key verb and resource. No wasted words; efficient and direct.

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

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

For a tool with no parameters and a simple list action, the description is sufficient. It doesn't mention output schema or provide additional context, but the presence of an output schema reduces the burden. Minor gap: no statement on whether the list is static or dynamic.

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?

No parameters exist (schema coverage 100%), so description cannot add param details. Baseline for 0 params is 4. Description is appropriately silent since no params to explain.

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 uses a specific verb 'List' and resource 'DEM datasets', making the tool's function clear. It distinguishes from sibling tools like 'dem' or 'point_elevation' by focusing on listing available datasets.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., 'dem', 'point_elevation'). The context of listing datasets is implicit, but no when-not-to-use or comparison is provided.

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

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

Adds significant context beyond annotations: mentions parallel execution, evidence with citations, confidence, source, and gaps for unanswered facets. Clarifies it never invents facts. Annotations already declare idempotent and read-only, and description aligns.

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 length is reasonable given tool complexity. Every sentence provides value, though slightly verbose. Well-structured: purpose, process, usage, constraints.

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

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

Covers what the tool does, how it works, when to use, output structure (findings packet with evidence, gaps, etc.), and constraints (account, payment). No output schema, but description adequately replaces it.

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

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

Schema coverage is 100%, but description adds meaning: explains depth values (quick=3, standard=5, thorough=8), and that broad questions are fine. Enhances understanding beyond schema.

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

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

The description clearly states the tool performs multi-source research in one call, decomposing questions into sub-questions. It distinguishes itself from sibling 'ask_pipeworx' which is for 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 advises use for broad or multi-part questions and recommends 'ask_pipeworx' for single lookups. Provides context on depth levels and account requirements.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds that it returns a URL to GeoTIFF, which aligns with readOnly, but does not disclose error handling or behavior for invalid inputs.

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

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

The description is a single, front-loaded sentence, efficient and to the point. However, it could include a bit more detail without becoming verbose.

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

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

Given 6 parameters (5 required), no enum constraints, and low schema coverage, the description lacks critical context such as coordinate system, dataset variations, and output format nuances. It does not leverage the existing output schema to explain return values.

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

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

With only 17% schema description coverage, the description fails to explain most parameters. It mentions bounding box and dataset implicitly via examples, but does not define latitude/longitude order, dataset options, or format meaning.

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 a DEM raster for a bounding box as a GeoTIFF URL. It distinguishes from siblings like 'point_elevation' (point) and 'datasets' (listing), though it could be more specific about available datasets.

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

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

The description implies the tool is for area-based elevation data retrieval, contrasting with point-based alternatives, but lacks explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds value beyond these. It discloses that the tool returns top-N relevant tools with names, descriptions, full schemas, and curated examples, and that results are ready to call directly. 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 approximately 80 words, front-loads the key purpose, and each sentence adds value. It could be slightly more concise but is well-structured and 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?

Although there is no output schema, the description explains what is returned (names, descriptions, schemas, examples) and that results are ready to call. The tool is complex as a discovery tool, and the description covers the key behavioral aspects without being overly extensive.

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

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

Schema description coverage is 100%, so the schema already fully documents all 6 parameters including aliases and the limit parameter. The description does not add additional parameter-level semantics beyond reinforcing the tool's purpose. 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 explicitly states 'Find tools by describing the data or task' with a specific verb (discover) and resource (tools). It distinguishes from sibling tools by positioning this as the initial browsing/search tool, listing example domains like SEC filings, FDA drugs, etc. This clearly differentiates it from other 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. However, it does not explicitly state when not to use or name specific alternatives, though the context of sibling tools implies a discovery role.

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 safety (readOnlyHint, idempotentHint, non-destructive). Description adds valuable behavioral context: fans across multiple sources, soft-fails for patents, specifics of return data (filings with URIs, fundamentals, etc.). No contradiction with annotations.

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

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

Description is informative but somewhat verbose; however, it is well-structured with examples and clear sections. Could be slightly trimmed but still effective.

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

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

Despite no output schema, the description details all return fields (CIK, filings, fundamentals, patents, news, LEI) and notes limitations. Complete enough for an agent to understand the tool's capabilities and outputs.

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

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

Schema coverage is 100% and describes both parameters. Description adds practical context (e.g., zero-padded CIK format, unsupported names), which enhances understanding beyond the schema alone.

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

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

Description clearly defines the tool as providing a holistic cross-source profile of a US public company, with example queries and explicit listing of data sources. It distinguishes itself from sibling tools like resolve_entity by specifying its scope.

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

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

Explicitly states when to prefer this tool over chaining single-pack lookups, and provides alternative (resolve_entity) for name inputs. Clear constraints: names not supported, only ticker or CIK.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds practical context about clearing sensitive data and pairing, but does not contradict annotations. Slight extra 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?

Two sentences, front-loaded with main action, efficient and no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage guidelines, and behavioral context.

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

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

Schema coverage is 100% with a clear description for the parameter. The description repeats 'by key' but adds no substantial meaning beyond the schema.

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

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

Description clearly states the action ('Delete') and resource ('previously stored memory by key'), and distinguishes itself from sibling tools by naming 'remember' and 'recall' as paired operations.

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

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

Explicitly provides when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions alternatives by naming paired 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?

The description discloses key behaviors: fetching the page, extracting title/description/key links, emitting standard format. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent, and the description adds context like output being a single text blob.

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?

Each of the four sentences adds unique value: purpose, process, output format, and use cases. Front-loaded with the main action, no wasted words.

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

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

For a tool with two well-documented parameters and rich annotations, the description covers the process and return format. Could mention possible errors or timeouts, but the core functionality is fully described.

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

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

Schema coverage is 100%, so the schema already documents both parameters adequately. The description does not add additional meaning beyond the schema definitions, which is the baseline expectation.

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' with specific context 'for any URL'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on generating the file rather than scanning presence.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't state when not to use, the examples provide sufficient guidance for appropriate contexts.

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, idempotent, non-destructive nature. The description adds return fields and default behavior (only active unless include_inactive), providing extra context 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 sentences: first states purpose, second adds usage guidance and return fields. No unnecessary words.

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

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

Given no required params and no output schema, the description covers what the tool does, its return fields, and typical use case. Could mention default parameter behavior more explicitly, but it's implied.

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?

One optional boolean parameter is fully described in schema. The description does not add much beyond the schema, but schema coverage is 100%, so baseline 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 lists the caller's active subscriptions, specifying verb, resource, and scope. It distinguishes from siblings like subscribe and unsubscribe.

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

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

It provides context: use it to review monitoring before adding more subscriptions or to find an id to cancel. This helps the agent decide when to invoke it.

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

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

Discloses non-obvious behaviors: rate-limited to 5 per identifier per day, free, not counted against tool-call quota, and that team reads digests daily with roadmap impact. This goes beyond annotations which only show readOnlyHint=false 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?

Single paragraph with no wasted words. Front-loaded with purpose and clear action items. 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 covers usage, behavior, and outcome (team reads, roadmap impact). Complete for a feedback tool with clear expectations.

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

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

Schema coverage is 100%, and the description adds meaningful guidance: explains enum values further, advises to describe in terms of Pipeworx tools/packs, and sets expectations for message length.

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

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

The description clearly identifies the tool as a feedback mechanism for Pipeworx, specifying types like bug, feature, data_gap, praise. It distinguishes from siblings by being the only feedback tool among query/data 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 states when to use (bug, missing tool, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and quota, providing comprehensive usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' 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?

Three sentences: first states output, second lists use cases, third adds behavioral details (source, PII, caching). Efficient, front-loaded, no wasted words.

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

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

For a simple read-only tool with one parameter, the description covers purpose, usage, and caching. Lacking explicit response format, but 'top tools, top packs, and total call volume' is sufficient. Could mention if response is sorted or includes counts.

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 description already explains the 'window' parameter well. The tool description reinforces window semantics by connecting window length to 'hot now' vs 'steady-state', adding contextual value.

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, top packs, and total call volume' over a window, with specific use cases. It distinguishes nicely from siblings like ask_pipeworx and 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?

Explicitly lists three use cases (discovering hot data, confirming popular tool, seeing alignment). Lacks explicit 'when not to use' or alternative tool names, but the context is clear and 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns a 1-pixel raster URL, which is behavioral context beyond annotations. No contradictions are present.

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

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

The description is a single sentence with no wasted words. It is front-loaded and efficiently conveys the core behavior and usage guidance.

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

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

While the output schema exists and annotations are rich, the description fails to cover parameter semantics. For a tool with 3 parameters and no schema parameter descriptions, the description should explain what each parameter does. It is minimally adequate but has a clear gap.

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 0% schema description coverage, the description must compensate but does not mention any parameters. It only implies lat/lon via 'point' but gives no details on the dataset parameter or format constraints. This is insufficient for a 3-parameter tool.

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 elevation at a point, specifying the output is a 1-pixel raster URL, and distinguishes from opentopodata for direct values. The verb 'returns' and resource 'elevation at a point' are specific and unambiguous.

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

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

Explicitly advises to use opentopodata for direct point values, providing a clear when-not-to-use alternative. The description implies when to use this tool (when a raster URL is acceptable) without ambiguity.

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 critical behavioral details: the requirement for one parameter, the monotonicity/partition checks, Jaccard similarity filter, placeholder filtering, fill check against live CLOB depth, and when not to trade. This far exceeds what annotations provide.

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

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

The description is verbose but almost every sentence adds value. It is front-loaded with the requirement and core purpose. A minor reduction in detail could improve conciseness without loss of clarity, but overall it is well-structured for an agent.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill check) and covers edge cases. It also references a sibling tool for custom sizing. The description is complete given 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 description coverage is 100%, but the description adds extensive meaning beyond the schema: explains the difference between event and topic modes, provides example slugs, describes the semantic anchor and partition filter, and clarifies constraints. This significantly aids correct parameter 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 clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, specifying two modes (event and topic) with examples. It distinguishes itself from siblings like polymarket_fill_risk by noting that tool is for custom sizing, thus providing clear purpose and differentiation.

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

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

The description gives explicit guidance on when to use each mode (event vs topic) and recommends event mode for specific markets. It cross-references polymarket_fill_risk for custom sizing, but does not comprehensively cover when not to use this tool or alternatives like polymarket_edges. Still, it provides useful context.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description reveals caching behavior (cached 1h at KV level), detailed edge computation for each segment (lognormal barrier, GDELT momentum, partition overround with per-sport alpha, concentrated longshot gates), and response structure including diagnostics for empty segments. Fully informs agent of behavioral traits.

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

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

Description is verbose but well-structured, using section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and clear segmentation of response fields. While dense, each sentence serves a purpose; however, it could be slightly more front-loaded with the core purpose before diving into technical specifics.

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, description fully compensates by detailing response structure: by_segment segments, top-level fields (fed_candidates, _diagnostics), and explanation of each segment's composition. Covers all aspects a caller needs: what opportunities look like, how to use knobs, and how to interpret empty segments.

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

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

Schema coverage is 100% but description adds significant nuance: e.g., slippage_pp explains Polymarket bid/ask depth, min_partition_leg_kelly clarifies interaction with partition parents (kelly_fraction_half=0 by design), and min_kelly differentiates single-leg vs partition filtering. Every parameter gains actionable context beyond schema.

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

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

Describes specific verb 'scan' and resource 'Polymarket markets', with clear differentiator 'where Pipeworx data disagrees with market price'. Distinguishes from sibling tools like polymarket_arbitrage and bet_research by targeting edge discovery for betting decisions.

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 frames tool as 'what should I bet on today' and notes that Fed bets are surfaced but excluded from ranking, implying alternative tool for Fed-focused analysis. Provides contextual guidance on when to use (opportunity discovery) and what to expect (three segments, diagnostics).

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

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

Annotations already declare readOnly and idempotent. The description adds valuable behavioral details: snapshots written on cache-miss, gaps mean no scan, history bounded by 60-day TTL, decay from daily closes. 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 detailed but well-structured, with a clear explanation of purpose followed by response fields and limits. Every sentence adds value, but slight verbosity could be trimmed.

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 fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field meanings. It covers edge cases (gaps, TTL) and is 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?

Both parameters are already described in the input schema with default values and constraints. The description adds context about valid window values and clarifies that 'days' is a lookback. Schema coverage is 100%, so description adds modest value.

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' from daily snapshots, answering whether an edge is shrinking. It differentiates from siblings like 'polymarket_edges' by focusing on historical context.

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

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

The description explains when to use the tool (to understand edge longevity) with a concrete example. However, it does not explicitly state when not to use it or compare with sibling tools, which 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, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds valuable behavioral context: it explains the risk of partial fills leading to directional exposure, the 'forced_directional_risk' field in the output, and the verdict types (clean|degraded|cannot_fill). No contradictions with annotations.

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

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

The description is well-structured with capitalized headings (SINGLE-MARKET, BASKET) and front-loads the core purpose. Every sentence provides useful information, though the text is somewhat lengthy. Could be slightly more concise, but clarity is maintained.

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

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

Given the tool's complexity (two modes, four parameters, risk analysis), the description is remarkably complete. It details all return fields, explains the auto side logic, and provides usage context. No output schema exists, but the description compensates by listing expected outputs (top_of_book, vwap_fill_price, etc.).

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 meaning beyond the schema: explains the two modes (single-market vs basket), the interpretation of size_usd (max spend/target proceeds for single-market vs settlement notional for basket), and the auto side logic for basket. It also describes return fields in detail.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with explicit parameter requirements (market vs event). The description also differentiates from siblings by specifying it is a pre-trade risk check for arbitrage 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?

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequences of not using it (partial basket fills converting an arb into unhedged 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 declare readOnlyHint=true, idempotentHint=true, so the tool is safe and side-effect-free. The description adds detailed behavioral context: two modes, response structure, compatibility warnings, temporal alignment checks, and skipped cross-type/subtype counters. 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 verbose with multiple paragraphs, but key information is front-loaded (first sentence defines purpose). Uses clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS) but could be more concise. Still adequate for the tool's complexity.

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

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

Given the tool's complexity (cross-venue comparison, multiple modes, safety fields, no output schema), the description covers all essential aspects: modes, parameters, response format, safety fields, and guidance on when spreads are meaningful. It is comprehensive 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% with descriptions for all parameters. The description adds context beyond schema: examples of topic values, explanation that explicit parameters override topic-mapped sides, and warning about pre-mapped topics not always being tradeable. This adds value beyond the schema baseline of 3.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('Cross-venue spread') and resources, and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on two-venue comparison.

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

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

The description explicitly explains two modes (topic shortcuts and explicit tickers) and warns that pre-mapped topics often are not tradeable. It provides safety fields that indicate when spreads are invalid. However, it does not directly contrast with sibling tools like 'polymarket_arbitrage' for single-venue arbs.

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 mentions scoping to identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description is consistent with these.

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, each adding value: core action, usage context, and related tools. It is well-structured and front-loaded with the primary purpose.

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

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

Given the tool's simplicity (one optional parameter, read-only, idempotent), the description is complete. It covers behavior, scoping, and relationship to sibling tools, leaving no major gaps for an agent to infer.

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

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

Schema coverage is 100% with a single optional parameter 'key'. The description adds meaning by explaining the default behavior when key is omitted (list all keys) and that it retrieves values saved via remember. This provides context beyond the schema's 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 clearly states the tool retrieves a value previously stored via remember or lists all keys when the key argument is omitted. It explicitly distinguishes from sibling tools remember and forget, making the purpose unambiguous.

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

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

The description explains when to use the tool for looking up previously stored context without re-deriving it, and mentions pairing with remember and forget. It does not explicitly list scenarios where it should not be used, but the guidance is clear enough for an agent.

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 claims mark_read:true flags events as read, a side effect that contradicts the annotation readOnlyHint: true, which indicates no state change. This is a critical inconsistency that misrepresents the tool's behavior. Beyond this contradiction, the description does add details about the feed structure and pollability, but the conflict undermines transparency entirely.

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

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

The description is four sentences long, front-loaded with the core purpose, and each sentence adds necessary detail—output fields, filtering, side effect, and alternative access. No word is wasted, and the structure is logical.

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

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

Despite lacking an output schema, the description fully explains what the response contains (source, citation_uri, payload), covers all parameters' effects, and even provides an alternative endpoint. For a read tool with 5 parameters, this is exceptionally complete.

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

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

Schema coverage is 100%, baseline is 3. The description adds value by providing an example (e.g., 'sec_8k' for type) and explaining the effect of mark_read on subsequent calls, enhancing understanding beyond the schema's basic 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 pulls fired events from the subscription feed, specifying the resource (recent alerts from the evaluator's persisted feed) and the action (pull). It distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing specifically on alert events and their content.

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

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

The description mentions polling suitability and an alternative REST endpoint for scripts/dashboards, providing some usage context. However, it does not explicitly contrast with sibling tools (e.g., when to use this vs. list_subscriptions or subscribe) or state when not to use it, limiting its guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT preferred, GNews on rate-limit/5xx), USPTO sunset soft-fail, and return structure with citation URIs. No contradictions.

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

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

Description is comprehensive but efficiently structured: starts with user-facing examples, then explains each data source, then parameter details. Each sentence adds information; only minor redundancy (e.g., 'ONE parallel call' could be implicit).

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

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

Given no output schema, description still clarifies return format (changes[] grouped by source, total_changes count, citation URIs). Covers all important aspects: data sources, fallback, date handling, entity resolution, and alternative tool for static data. 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?

Input schema already has 100% coverage with descriptions. Description adds value by explaining `since` accepts both ISO and relative shorthand with examples, `value` can be ticker or CIK, and `type` is limited to 'company'. Could include more edge cases but already enriches 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 multiple real-world query examples and clearly states it returns a change feed for a company in a time window. It lists sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from sibling tool entity_profile by contrast.

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 (queries like 'What's new with X') and when not to ('Use entity_profile instead for static profile regardless of window'). Also provides parameter guidance for `since` with typical monitoring values.

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 idempotentHint=true and no destructiveness. Description adds details: key-value storage, scoping by identifier, persistence differences for authenticated vs anonymous (24 hours). 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?

Four sentences, front-loaded with main purpose. Each sentence adds distinct value: purpose, usage triggers, scoping rules, and pairing instructions. No redundant or extraneous text.

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

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

For a simple 2-parameter tool with no output schema, the description covers all relevant aspects: what it does, when to use, how it behaves (persistence, scoping), and integration with siblings. Meets the needs for an AI agent to select and invoke correctly.

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

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

Schema descriptions already cover both parameters (100% coverage). Description reinforces with examples (e.g., 'subject_property') and explains the role of key-value pairs in the memory system. Adds context about typical usage patterns beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' (verb+resource). It specifies cross-session and cross-conversation persistence and provides concrete examples. It distinguishes from sibling tools like 'recall' and 'forget' by mentioning pairings.

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

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

Explicitly says when to use: 'Use when you discover something worth carrying forward...'. Provides context for scoping (by identifier) and duration (authenticated vs anonymous). Gives pairing instructions: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that calls cascade through multiple endpoints, replaces 2-3 manual lookups, and auto-disambiguates company inputs. Also details return structure (ticker, CIK, citation for company; RxCUI, ingredient for drug).

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

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

Description is detailed but focused, front-loading examples and usage guidance. Every sentence adds value; could be slightly shortened but is well-organized.

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

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

Covers both entity types and their return structures implicitly through examples. No output schema, so description compensates by listing returned fields. Could explicitly state output format, but sufficient for a resolver 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. The description adds valuable examples (e.g., AAPL for ticker, ozempic for drug) and notes auto-disambiguation for company names, going beyond schema.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with examples like 'What's the ticker for…'. It specifies supported types (company, drug) and the identifiers returned, distinguishing it from siblings like entity_profile or compare_entities.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context. Does not explicitly state when not to use it (e.g., if ID is already known), but the guidance is strong enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: probes each entity, treats first entry as subject, and returns a ranked list with 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?

Four sentences, front-loaded with the core action ('Compare AI visibility across multiple entities'), no wasted words. Efficient and to the point.

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 multi-entity probing tool with no output schema, the description adequately explains the process and return values (score, confidence, signal density). Could mention pagination or limits, but overall sufficient.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema: 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies behavioral nuance not in the schema.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes from sibling tools like ai_visibility_check (the underlying probe) and compare_entities.

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

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

Provides explicit use case ('competitive AI-marketing audits') and an example question. It does not explicitly mention when not to use, but the context makes it clear this is for comparative analysis.

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 readOnly and idempotent. Description adds critical behavioral details: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed listed. 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?

While fairly long, every sentence is informative and adds value. Front-loaded with purpose and usage. Minor redundancy (e.g., 'v1' repeated) 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?

No output schema exists, but description compensates by listing return fields (summary block, per-advisory detail, links, alternative versions). Parameters are fully documented, and ecosystem limitation is noted. Complete for its complexity.

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

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

Schema coverage is 100% with clear descriptions. The description adds context: scoped packages accepted, version defaults to latest. Slight extra value justifies 4 over baseline 3.

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

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

The description clearly states the tool's composite purpose: a one-call check for adding npm packages, combining deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM-only scope and referencing alternative tools for other ecosystems.

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

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

Explicitly says 'use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies limitations: NPM only in v1, other ecosystems handled by deps.dev:version directly.

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

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

Description adds significant context beyond annotations: BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flagging, and return of character offsets and similarity scores. 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?

Well-structured with purpose first, then usage guidance, then technical details. Each sentence adds value, though slightly verbose in places. Front-loaded with key information.

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

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

Despite no output schema, description explains return values (top-N passages, offsets, similarity scores). Covers truncation, embedding model, and pairing. Sufficiently complete 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%, so baseline 3. Description reinforces parameter meanings: text as document content with char limit, query as natural language with examples, and clarifies limit is max passages. Adds value beyond schema.

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

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

Clearly states verb 'semantic search' and resource 'inside a fetched record'. Distinguishes from sibling tools by specifying use case: when record is too large for prompt, 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 says 'Use when the record is too big to cram into the prompt'. Provides pairing guidance with ask_pipeworx_grounded and mentions that passages have offsets for verification.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description discloses behavioral traits: subscription persistence requires OAuth, delivery limits (sms 10/day, webhook auto-disabled after 10 failures), and one-time return of signing secret. 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 front-loaded with purpose and returns value. It uses efficient formatting (dashes, inline examples). Slightly verbose with type-specific details, but every sentence serves a purpose. Could be trimmed slightly 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?

Given the complexity of three parameters (one with nested objects), the description fully covers prerequisites, type-specific filters, delivery options, and limitations. It explains the return value (subscription id). No output schema is needed as the return type is simple. Sibling tools scenario suggests context for subscription lifecycle is covered.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains each type enum, provides concrete parameter examples for each type, and clarifies delivery object constraints (phone verification, webhook signing). This greatly enhances an agent's ability to construct correct inputs.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions (lists existing subscriptions) and unsubscribe (removes 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 explicit prerequisites (requires Pipeworx OAuth account), lists supported types with examples, and explains delivery channels. It implies when to use (for ongoing monitoring) vs one-time queries, but does not explicitly compare to tools like ask_pipeworx or recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it draws from a live catalog of thousands of tools, is an onboarding entry point, and returns structured questions. No contradictions.

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

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

The description is somewhat lengthy but front-loaded with common queries. Every sentence provides useful information, though some redundancy could be trimmed. Overall well-structured for a complex onboarding tool.

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

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

Given one optional parameter and no output schema, the description thoroughly explains what the tool returns (category-bucketed questions with exact tool+argument shapes). It does not mention pagination or number of questions, but is otherwise complete for its purpose.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing example topic values and explaining behavior when topic is omitted versus provided. This goes beyond the schema's basic 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 clearly states the tool's purpose: returning category-bucketed example questions for onboarding, with specific categories listed. It distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the entry point for new users.

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

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

Explicitly provides when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains the optional topic parameter for focused queries. It also mentions learning how to call meta-tools, which guides usage.

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

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

The description adds significant value beyond annotations: ownership enforcement, row deactivation (not deletion), and link to historical events via recent_alerts. Annotations provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which are consistent and enhanced by the description.

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

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

Three concise sentences, front-loaded with the core action, no wasted words. Every sentence adds necessary context.

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 required parameter and no output schema, the description is complete: it covers purpose, ownership constraints, side effects (deactivation), and integration with related tools (recent_alerts).

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 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no extra meaning about the parameter 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 the action (cancel a subscription), specifies the resource (subscription by id), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by noting ownership enforcement.

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

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

The description implies when to use (to cancel your own subscription) and provides context that the row is deactivated not deleted, pointing to 'recent_alerts' for historical events. It lacks explicit when-not or alternatives but is sufficient for a simple tool.

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

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

Annotations already declare readOnly, idempotent, openWorld, and not destructive. The description adds valuable context: returns a verdict (confirmed/approximately_correct/refuted/inconclusive/unsupported), structured form, actual value with citation, and percent delta. It also reveals the domain (company-financial claims via SEC EDGAR + XBRL) and that it is an aggregated replacement for multiple calls. No contradictions.

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

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

The description is front-loaded with magic words ('Is it true that…' / 'fact check'), followed by usage guidance and output details. It is appropriately concise but could be slightly tighter by removing redundant examples. Overall, well-structured.

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

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

Given the tool's simplicity (1 parameter, no output schema, good annotations), the description is sufficiently complete: it explains purpose, domain, output format, and efficiency. It does not detail error handling or edge cases, but that is acceptable for this tool.

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

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

The sole parameter 'claim' is described in the schema as 'Natural-language factual claim'. The description repeats this in examples. With 100% schema coverage, baseline is 3. The examples add marginal value but do not significantly enhance understanding 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's purpose: to verify factual claims via natural language ('Is it true that…' / 'fact check'). It specifies the verb 'verify' and the resource 'claims against authoritative sources', and distinguishes from siblings by focusing on claim verification with a verdict, unlike ask_pipeworx_grounded which provides general grounded answers.

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 the agent needs to check whether something a user said is factually correct' and notes it replaces 4-6 sequential calls, providing clear context. However, it does not explicitly mention when NOT to use it or name alternative tools, so it's not a full 5.

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