marine

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

Annotations declare read-only, idempotent, non-destructive. Description adds that default model is free, Anthropic requires BYO key, and return includes per-model {score, confidence, signals, raw_response} plus combined view. No contradictions.

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

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

Four sentences, front-loaded with purpose, no fluff. Each sentence adds unique 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?

Covers purpose, parameters, return structure, and use cases. Could detail scoring methodology or error handling, but sufficient for a probing tool with no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. Description rephrases parameter purposes but doesn't add substantial new meaning beyond schema.

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

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

The description clearly states it probes LLMs for entity knowledge and scores visibility per model with a default. It distinguishes from siblings like scan_competitor_ai_presence by focusing on per-model scoring.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks) and when to use the API key. Lacks explicit when-not-to-use vs alternatives, but context is sufficient.

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 true, and destructiveHint false. The description adds valuable context about internal routing to many tools and the structured answer format with citation URIs. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with a strong usage directive and lists clear examples. It is slightly verbose with multiple examples, but every sentence adds value. Could be trimmed slightly but remains efficient.

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

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

Given the tool's simplicity (one required parameter) and good annotations, the description covers when to use, what it does, and the output format (structured answer with citation URIs). No output schema exists, but the description compensates adequately.

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

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

Schema description coverage is 100% with clear descriptions for all aliases and examples. The description adds examples of questions but does not provide additional meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool routes questions to 3,774 tools across 895 verified sources and returns structured answers with citation URIs. It distinguishes from web search by explicitly preferring authoritative structured data, and differentiates from siblings like 'deep_research' by focusing on factual queries.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides specific query types and examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It gives clear guidance on when to use but does not mention specific exclusions or when to use sibling tools like 'deep_research'.

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 behavioral details beyond annotations: structured response format, refusal reasons, extra cost. Annotations already cover read-only, idempotent, non-destructive; description complements well without contradiction.

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

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

Two sentences, front-loaded with purpose, but second sentence is somewhat lengthy. Still efficient with no fluff.

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

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

Given complexity (refusal handling, cost tradeoff, no output schema), description fully explains return values, failure modes, and the tool's internal routing, making it complete for high-stakes use.

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

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

Schema coverage is 100% (all parameters are aliases for question). Description adds minimal extra meaning beyond 'natural language question'; baseline 3 is appropriate.

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

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

Clearly states it's a hallucination-resistant answer mode that extracts answers using only tool results, distinguishing it from ask_pipeworx by describing the additional extraction step.

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 to use when answers will be quoted/cited/acted on and facts must not be invented, and advises preferring ask_pipeworx for casual lookups, providing clear guidance on alternatives.

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

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

The description discloses many behavioral traits beyond annotations: short-circuit on low confidence, market closed handling, wide spread tradeability, resolution-rule risk, and cancellation rule parsing. Annotations indicate readOnlyHint true, which the description supports with 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 comprehensive but quite lengthy (multiple dense paragraphs). While front-loaded with the main purpose, the extensive detail on response shapes, resolver contract, and edge cases could be streamlined for quicker comprehension.

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 all response parts: market, analysis, evidence, resolver contract, parent event, news fields, and safety mechanisms. It covers every aspect an agent would need to correctly use the tool.

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

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

Even though schema coverage is 100%, the description adds significant meaning: explains market_input as slug/URL/question, depth enum values, include_raw default and effect. Examples illustrate usage. This goes well 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 researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage through its specific purpose.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives category-specific fan-out examples. However, it does not explicitly state when NOT to use the 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?

The description discloses significant behavioral details beyond the annotations: it explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials.gov for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the output format (paired data + citation URIs). Annotations already indicate readOnly, idempotent, and non-destructive behavior, and the description adds valuable 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?

The description is front-loaded with example queries and is comprehensive, but slightly verbose. However, every sentence adds value, so it earns a high score for being informative without unnecessary fluff.

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

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

Given the lack of an output schema, the description explains the return format (paired data + citation URIs) and covers behavioral aspects. It is fairly complete for a comparison tool with good annotations and schema, though it could specify the exact data structure a bit more.

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

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

The input schema covers all parameters (100% coverage), and the description adds meaningful context: examples for 'values' (tickers/CIKs for company, drug names) and explains how 'type' affects data retrieval. This 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?

The description clearly states the tool's purpose with explicit user query examples ('Compare X and Y', 'X vs Y', 'which is bigger', etc.) and specifies it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sequential single-pack lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'.

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

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

The description provides explicit guidance on when to use the tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and gives examples of triggering queries. It does not explicitly state when not to use it, but the positive 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?

Beyond annotations (readOnly, openWorld, idempotent), the description adds critical behaviors: parallel execution, grounded answers with verbatim evidence, gaps array, no invention, account requirement, and paid plan for thorough depth. No contradictions.

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

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

The description is relatively long but front-loaded with the core value proposition. Every sentence adds value, though some details (e.g., exact numbers of tools and sources) could be trimmed 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 the tool and absence of an output schema, the description covers essential aspects: return structure, behavior on unanswerable facets, account requirement, and typical response time. Slightly more detail on the output format could improve completeness.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant meaning: for depth, it lists the number of facets per level (quick=3, standard=5, thorough=8) and notes the paid plan requirement; for question, it clarifies that broad/multi-part questions are expected.

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: grounded multi-source research in one call, decomposing questions into sub-questions and routing to thousands of sources. It distinguishes itself from sibling tool 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 recommends use for broad or multi-part questions and suggests ask_pipeworx for single lookups. Mentions prerequisites (Pipeworx account, paid plan for thorough depth). Could explicitly state when not to use, but the alternative is clear.

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

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

Adds beyond annotations by describing return value (top-N tools with full schemas and examples) and readiness for direct invocation. Annotations already indicate read-only/idempotent.

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

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

Single paragraph of 4 sentences, front-loaded with purpose, no redundant or missing information. Every sentence earns its place.

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

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

Adequately covers purpose, behavior, and usage for a discovery tool with no output schema. Could mention that multiple aliases are accepted but schema already handles that.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with concrete examples (e.g., 'look up FDA drug approvals') that illustrate 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?

Description clearly states 'Find tools by describing the data or task' with specific verb and resource. It distinguishes itself from sibling tools by being a discovery tool rather than a task-specific one.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and advises 'Call this FIRST when you have many tools available'. Lacks explicit when-not-to-use but provides clear 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 (readOnly, idempotent, etc.), description details internal data sources (SEC, XBRL, USPTO, GDELT, GLEIF) and notes that USPTO PatentsView API sunset in May 2025 will cause soft-fails. No contradictions with annotations.

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

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

Well-structured with examples at top and bullet-like list of returned fields. Slightly long but each sentence adds value. Front-loaded with user-friendly examples.

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

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

No output schema, but description thoroughly enumerates all returned fields (cik, filings, fundamentals, patents, news, LEI) and notes limitations (names not supported, USPTO sunset). Complete for a holistic profiling tool.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description restates that names are not supported and type is limited to 'company', adding no new semantic value beyond the schema.

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

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

Clearly states it provides a full cross-source profile of a US public company. Includes concrete examples like 'Tell me about X' and distinguishes from sibling tools such as resolve_entity and compare_entities.

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

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

Explicitly says to prefer this over chaining single-pack lookups for holistic views. Also specifies that names are not supported and directs to use resolve_entity first.

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 and idempotentHint=true. The description says 'Delete', which matches, but does not add details on behavior for missing keys or idempotency effects.

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

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

Two sentences, each serving a distinct purpose (purpose and usage). No unnecessary words, front-loaded with the action.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose and usage adequately. Minor omission: behavior when key does not exist.

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 parameter is well-documented in schema. The description adds no additional semantic detail beyond 'by key', 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 verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Provides explicit use cases: when context is stale, task done, or clear sensitive data. Also advises pairing with related tools, but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds fetch, extraction steps, and output format, going 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 plus a bullet list, front-loaded with main purpose. Every sentence adds substance, no filler.

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

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

Given simple tool with 2 params, good annotations, and no output schema, the description fully covers purpose, behavior, usage, and output format.

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 default and max for max_links, and clarifies URL usage. Adds value beyond the schema.

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

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

Clearly states the verb 'generate' and resource 'llms.txt file', listing specific AI crawlers. Distinguishes from siblings like scan_competitor_ai_presence and ai_visibility_check which are related but different.

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: indexing client sites, drafting own projects, auditing competitors. No exclusions but the context is clear enough given sibling diversity.

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, covering safety. Description adds value by specifying returned data (wave height, period, direction) but no additional behavioral context beyond annotations.

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

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

Two sentences, no redundancy. First sentence states function, second provides usage context. Efficient and front-loaded.

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

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

With output schema present (context indicates true), description need not explain returns. Parameters fully covered. Description provides sufficient context for a real-time data 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 parameter descriptions (latitude, longitude). Description does not add extra meaning beyond what 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?

Description uses specific verbs 'Check' and 'Returns' with clear resource 'real-time wave conditions' and specifies output fields (height, period, direction). Distinguishes from sibling 'get_wave_forecast' by focusing on current vs forecast.

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

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

States use cases 'immediate surfing, boating, or maritime planning decisions' which implies real-time context. No explicit when-not-to-use or alternatives mentioned, but the purpose is clear enough for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by specifying exact return fields (max wave height, period, dominant direction). No contradiction.

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

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

Two sentences, front-loaded with core purpose, no redundant information. Every word 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?

Output schema exists; description explains return values. With strong annotations and schema, the description sufficiently covers what the agent needs to know for correct invocation.

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

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

Schema coverage is 100%; all parameters are described in schema. The description adds marginal context like 'coastal locations' and examples, but does not significantly enhance parameter meaning beyond schema.

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

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

Clearly states the tool returns multi-day wave forecasts with specific metrics (max wave height, period, dominant direction) and gives usage context. Differentiates from sibling 'get_current_waves' by explicitly being multi-day.

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

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

Provides explicit usage context: 'use when planning water activities or monitoring upcoming swell.' Does not explicitly exclude other uses but implies when not to use (e.g., real-time conditions).

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, destructiveHint false, idempotentHint. The description adds value by specifying the returned fields, scoping to 'caller's' subscriptions, and mentioning the default active-only behavior. No contradictions.

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

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

Two sentences with no wasted words. Front-loaded with purpose and return fields, then usage guidance. Perfectly concise.

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

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

For a simple list tool with one optional parameter and no output schema, the description is fully adequate. Annotations cover safety, description covers purpose, return fields, and usage. 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% for the single parameter. The description does not add any meaning beyond the schema: it mentions 'active' but that's reflected in the parameter default. 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 'List the caller's active subscriptions' with a specific verb and resource, and lists the return fields. It clearly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides clear usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implicitly tells when not to use (for subscribing or canceling). Could explicitly mention alternatives but sufficient for a simple listing tool.

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

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

Discloses behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads digests daily. No contradiction with annotations.

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

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

The description is concise and well-structured: starts with action, then usage scenarios, then constraints. Every sentence adds value with no fluff.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers all necessary aspects: purpose, usage, behavioral details, and parameter guidance. Complete for an AI agent to understand when and how to use 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% with clear parameter descriptions. The description adds extra value by advising not to paste the end-user's prompt and typical message length, but the schema already covers the enum and context field semantics well.

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

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

The description clearly states the tool's purpose: to send feedback about broken, missing, or needed features. It lists specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by being the dedicated feedback channel.

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 scenarios: for bugs, feature requests, data gaps, or praise. Also includes what not to do (don't paste end-user prompt) and mentions rate limits and quota, guiding appropriate usage.

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

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

Annotations already declare safe traits (read-only, idempotent). The description adds value by disclosing aggregation source (CF analytics-engine), no PII, and caching durations (5min-1h), which go 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?

Description is concise (4 sentences) with clear bullet-style list of use cases. Every sentence adds value; no redundancy or wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully covers: what is returned, caching, use cases, and data origin. Self-contained and 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 covers the single parameter fully with enum and description. The description enhances it by explaining semantic differences between windows (short for hot, long for steady-state), adding practical guidance not in 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 returns trending data (top tools, packs, call volume) and explicitly lists use cases. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on aggregated trends.

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 three explicit use cases and mentions caching behavior. It does not explicitly state when not to use or compare with alternatives, but the context is sufficiently clear for an agent to decide.

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

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

Adds extensive behavioral details beyond annotations: parameter requirement, similarity threshold (0.30 Jaccard), partition filter, fill check against live CLOB depth, and trade cautions. 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 dense with valuable information but slightly verbose. Could benefit from bullet points or clearer sectioning, but remains well-structured and front-loaded with essential requirement.

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 output schema, description fully explains response fields (opportunities, partition_check, fill_check) and references sibling tool for custom sizing. Covers all aspects needed for correct agent invocation.

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

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

Schema coverage is 100%. Description adds meaning by explaining parameter usage, providing examples (e.g., 'fed-decision-may-2026'), and noting that full URLs are accepted.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states requirement: 'REQUIRES one of event OR topic'. Provides guidance on when to use each mode (event recommended for specific market, topic for cross-event scanning) and mentions sibling tool for custom sizing.

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

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

The description goes far beyond the annotations (which already indicate read-only, open-world, idempotent) by detailing the exact model families, calculation methods (e.g., lognormal barrier from FRED log-returns, Kelly sizing caps at 0.25), response structure including diagnostics, caching behavior (1h at KV level), and special handling of Fed bets. This provides comprehensive behavioral understanding.

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

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

The description is comprehensive but verbose (approximately 600 words), covering technical details of model families, edge calculations, and response structure. While well-structured with clear sections, it could be more concise. Some information, like the exact model parameters, may be excessive for a general-purpose description.

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

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

Given the tool's complexity (9 parameters, nested response structure, no output schema), the description is highly complete. It explains the response top-level fields (by_segment, fed_candidates, _diagnostics), the content of each opportunity (edge_pp_net, kelly_fraction, etc.), and the tradeable-edge filters. The agent has all necessary context to use the tool effectively.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant value by explaining the purpose and effect of each parameter in context (e.g., min_kelly 'Skips opportunities that are too small to bet sensibly...', slippage_pp explains execution costs on Polymarket). This goes well beyond the schema descriptions and helps the agent make informed choices.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself by being built for 'what should I bet on today' and explains the three model families that compose the output, differentiating it from related sibling tools like polymarket_arbitrage.

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

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

The description provides clear context on when to use the tool (discovering betting opportunities without paging through hundreds of markets) and includes guidance on tradeable-edge knobs and filters. However, it does not explicitly state when to avoid this tool or mention alternatives, leaving some ambiguity for the 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 discloses extensive behavioral details: response structure (tracked, expired, snapshot_dates), computation method (daily closes of edge_pp_net, not intraday), and limits (60-day TTL). Annotations already provide safety and idempotency, so the description adds significant value beyond those.

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

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

The description is long but well-organized, front-loading the core purpose and then detailing response fields and limits. Every sentence contributes meaning, though a slight reduction in verbosity could improve conciseness.

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

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

Given the lack of an output schema, the description fully explains the response format and constraints. It covers purpose, parameters, output, limits, and caveats, making it 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?

With 100% schema coverage, the description still adds meaning: it provides default values, ranges (2-30 for days), and explains what 'window' refers to (snapshot family). This goes beyond the schema's bare 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 identifies the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis.

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 strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades') that implies when to use this tool over raw edges. However, it does not explicitly state when not to use it or name alternative tools, leaving some 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=true and destructiveHint=false. The description adds value by detailing required input modes, the walking of the order book ladder, and the return fields including verdict and forced_directional_risk, which go beyond the annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the requirement. While informative, it is relatively long; some minor redundancy could be trimmed, but the organization and essential details justify the length.

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

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

Given the tool's complexity (two modes, no output schema), the description comprehensively covers return values (top_of_book, vwap, slippage, verdict, etc.), explains the risk of partial fills, and provides rationale for usage. It leaves no critical gaps for an agent to understand invocation and results.

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

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

Schema coverage is 100%, but the description adds significant context beyond the schema: for size_usd it clarifies interpretation in each mode (spend vs proceeds vs settlement notional), for side it explains default auto behavior in basket mode, and for market/event it ties them to specific modes. This enriches the schema descriptions.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly relates to sibling tools (polymarket_arbitrage, polymarket_edges), showing when to use this tool instead.

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

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

Explicit instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills create directional risk), providing clear when-to-use and why-not-use guidance.

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

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

The description extensively discloses behavioral traits beyond annotations, including how compatibility_warning fires in two specific cases, temporal alignment checks, skipped cross-type/subtype counters, and the nuance that non-equivalent bet shapes make spreads invalid. No contradiction with annotations (readOnlyHint, 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?

The description is well-structured with clear sections (overview, modes, response fields, safety fields) and each sentence adds value. It front-loads the core purpose and progressively adds detail, maximizing information density without redundancy.

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

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

Given the complexity of comparing two venues with multiple modes and safety checks, and lacking an output schema, the description comprehensively covers input parameters, response fields (spreads, compatibility_warning, temporal_alignment, counters), edge cases, and caveats. It leaves no critical gaps for an agent to understand tool behavior.

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

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

Input schema covers all 3 parameters with descriptions. The description adds context on how the modes interact and provides examples, but does not add new semantic meaning to individual parameters beyond what the schema already provides. With 100% schema coverage, 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 identifies the tool as a cross-venue spread calculator between Polymarket and Kalshi, specifying two modes (topic and explicit) and the overall function. It implicitly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads rather than intra-venue arbitrage.

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

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

The description explicitly explains when to use the 'topic' mode vs explicit parameters, warns that most pre-mapped topics currently return compatibility warnings, and details the safety fields that indicate when spreads are not meaningful. This provides clear guidance on appropriate usage and exclusions.

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

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

Annotations already indicate readOnly and idempotent. Description adds scope detail (identifier-based) and context for use. 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?

Very concise, front-loaded with purpose, then usage context. Every sentence adds value; 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 one-parameter tool with full annotations, description covers purpose, usage, scope, and relationship to siblings. Output schema not needed.

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

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

Schema coverage is 100% and description explains the optional key parameter, but mostly repeats the schema description. Adds listing behavior but no new parameter insights.

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 retrieves a value saved via remember or lists keys if no argument. Differentiates from sibling tools remember and forget.

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

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

Explicitly describes when to use (look up stored context) and pairs with remember/forget. Lacks explicit when-not scenarios, but context is clear.

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

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

The description discloses the mark_read behavior, which modifies state (flags events as read), contradicting the readOnlyHint annotation (true) that implies no state modification. According to scoring guidelines, a contradiction warrants a score of 1.

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, well-structured paragraph that front-loads the main purpose, then succinctly covers return fields, filtering options, and an alternative access method. Every sentence adds value with no wasted words.

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

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

The description explains what is returned (source, citation_uri, raw event payload) and key behaviors (mark_read, polling). It does not elaborate on unread_only or pagination beyond the schema, but given the presence of annotations and high schema coverage, it is reasonably complete for a read-only tool with five parameters.

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

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

Schema coverage is 100% with all parameters described. The description adds value by providing concrete examples (e.g., 'sec_8k' for type) and explaining the effect of mark_read (so next call only shows newer ones). This goes beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies key return fields (source, citation_uri, raw event payload) and distinguishes from sibling tools like list_subscriptions by focusing on retrieving alerts rather than managing subscriptions.

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

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

The description provides clear context on when to use the tool (for recent alerts) and includes filtering options (type, since). It also mentions an alternative access method via GET registry.pipeworx.io/alerts.json. However, it does not explicitly state when not to use this tool or compare it to similar tools like recall or recent_changes.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT→GNews), USPTO soft-fail, and return structure with citations. No contradiction.

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

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

The description is a single dense paragraph that front-loads the purpose with many examples. Every sentence adds value, though it could be slightly more structured (e.g., bullet points). Overall, it is concise without waste.

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

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

Given no output schema, the description explains return structure (grouped changes, count, citations) and all important aspects: sources, fallback, parameter details, and alternative tool. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaningful guidance beyond the schema: examples for 'since' (ISO date, relative shorthand, suggestion for monitoring), and explanation that 'value' accepts ticker or CIK. This helps the agent form correct 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's purpose as a change feed for a company in a specified time window. It includes multiple query examples and explicitly distinguishes itself from the sibling tool 'entity_profile'.

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

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

The description provides clear guidance on when to use this tool versus 'entity_profile' and describes fallback behavior for news sources. However, it does not explicitly state when NOT to use the tool beyond the alternative.

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

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

Adds scoping (by identifier) and retention policy (persistent vs 24h) beyond annotations. Consistent with idempotentHint and no contradiction.

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

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

Two sentences, front-loaded with core purpose, no wasted words. Every sentence adds value.

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

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

For a 2-param tool with no output schema, the description covers purpose, usage, scoping, retention, and pairing. Fully adequate.

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

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

Schema coverage is 100%, so baseline 3. Description provides examples but does not add new semantics beyond what schema already states.

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 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. Provides concrete examples (ticker, address, preference) and distinguishes from siblings like 'recall' and 'forget'.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and pairs with 'recall' and 'forget' for alternative actions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral context beyond annotations, such as 'each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This provides transparency about internal processing and efficiency.

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

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

The description is moderately sized but well-structured. It starts with examples and a clear imperative statement, then provides type-specific details. Every sentence adds value, with no redundancy. It is front-loaded with key usage directives, making it efficient for an AI agent to parse.

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

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

Given two parameters and no output schema, the description provides ample context: input requirements, output details for each type, and internal behavior. It sufficiently explains what the tool does and what to expect, enabling correct invocation. Minor gaps like missing explicit error handling do not detract from overall completeness.

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 significant meaning beyond the schema. For company type, it specifies returns (ticker, CIK, company name, citation URI) and accepted input formats (ticker, CIK, or name with auto-disambiguation). For drug, it details returns (RxCUI, ingredient, brand, citation URI). This enriches the parameter semantics.

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: resolving user-spoken names to canonical/official identifiers. It provides specific examples (ticker, CIK, RxCUI) and distinguishes from sibling tools by explicitly saying to use it 'FIRST whenever you have a name but need an ID.' The supported entity types (company, drug) are listed with detailed output expectations.

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 includes explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It explains input formats for each type and what the tool returns. While it doesn't explicitly state when not to use it, the context is clear that this tool is for identifier resolution before using other tools.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: it probes each entity via ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. 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?

Three concise sentences with a logical flow: function, mechanics, use case. No redundant words, front-loaded with core purpose, every sentence earns its place.

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

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

Given no output schema, the description adequately describes the return value (ranked list with score, confidence, signal density). Parameter guidance is complete, and the tool's behavior is sufficiently explained for an agent to use it correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds context beyond schema: explains the special role of the first entity as subject, and how the context parameter disambiguates common names. This enriches parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, explicitly naming the verb 'Compare', the resource 'AI visibility', and the action 'ranks by score'. It distinguishes itself from sibling tools like 'ai_visibility_check' by being a comparative variant.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. While it doesn't explicitly state when not to use the tool or list alternatives, the purpose is well-defined and use context is clear from the context signals and sibling list.

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

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

Adds significant behavioral context beyond annotations: fans out across deps.dev and bundlephobia, mentions potential 5-30s delay on first bundlephobia measurement, explains graceful degradation with sources_failed list. 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?

Three dense sentences: first defines tool, second gives usage guidance, third details return values and failure modes. No fluff, 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?

No output schema, but description fully enumerates return fields (summary block, per-advisory details, links, alternative versions) and failure behavior. For a complex multi-source tool, this is complete and actionable.

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

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

Schema description coverage is 100% and already well-documented. Description reinforces NPM-only constraint but does not add new semantics beyond schema. Baseline 3 is appropriate.

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

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

Clearly states it's a composite check for npm packages, describing what it covers (license, advisories, version history, bundle size, ESM/tree-shake). Distinguishes from sibling tools like scan_competitor_ai_presence by its specific focus on dependency evaluation.

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: when agent asks about safety/popularity/size or cost of adding a package. Also notes when not to use: for non-NPM ecosystems, referencing fallback tools. Provides clear context for invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds beyond these: it discloses the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and truncation behavior (cap at 200K chars with flag). No contradiction with annotations.

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

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

The description is one paragraph, front-loaded with the main purpose. It is reasonably concise, though some sentences could be shortened. Every sentence contributes useful information.

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

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

Given the annotations cover safety/idempotency, the description fully explains the search mechanism, limits, return format (passages with offsets and similarity scores), and pairing with a sibling tool. No output schema exists, but the description compensates by describing what is returned.

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

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

Schema coverage is 100%, but the description adds value: for 'text' it reiterates the max length, for 'query' it gives concrete examples, and it explains the purpose of 'limit' indirectly. The examples and clarification of truncation go beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It specifies the verb ('search'), the resource ('text inside a record'), and distinguishes from sibling tools by noting it is used when the record is too large 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?

The description explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative approach: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' It also highlights the benefit of saving context and the offset 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?

Discloses OAuth requirement, return of new id, delivery channels, SMS cap (10/day), phone verification need, webhook HMAC signing and auto-disable after failures. Annotations already indicate non-read-only and non-destructive; description adds rich operational details.

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: purpose and return first, then prerequisites, then type details, then delivery channels. Every sentence adds necessary information. Appropriate length given 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?

Covers all aspects: subscriptions types, parameters, delivery channels, constraints (auth, phone verification, limits, webhook signing and auto-disable). No output schema but return value (subscription id) is stated. Complete for agent to call 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 good descriptions; description adds substantial value with explicit examples for each subscription type, parameter structures, and detailed delivery options including webhook secret and HMAC verification.

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

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

States clearly 'Create a proactive monitoring subscription to a live-data event stream' with verb and resource. Returns a subscription id. Differentiates from sibling tools like list_subscriptions (read) and unsubscribe (delete).

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 context for use (setting up proactive monitoring) and detailed guidance on subscription types and parameters. However, does not explicitly state when to prefer this over alternatives like list_subscriptions for checking existing subscriptions.

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. Description adds that it returns category-bucketed questions and can be focused by topic, enriching the behavioral context without contradicting annotations.

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

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

Front-loaded with common user questions, but slightly verbose. Every sentence adds value, though some repetition could be trimmed. Still well-structured and clear.

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

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

Given single optional parameter, full schema coverage, and no output schema, the description thoroughly explains purpose, usage, and outcomes. No gaps for this simple tool.

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

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

Schema coverage is 100%, and description adds value by explaining the topic parameter values (e.g., 'finance', 'pharma') and that omitting it gives a full spread. Provides usage context beyond the schema.

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

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

Clearly states it's the onboarding entry point that returns category-bucketed example questions. Distinguishes from siblings by being the first tool to use when the agent doesn't know Pipeworx's capabilities.

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

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

Explicitly states when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also mentions learning how to call meta-tools, providing clear context.

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

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

The description adds behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and availability of historical events via recent_alerts. Annotations provide idempotentHint and non-destructive nature, which are consistent.

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

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

Two concise sentences with no waste. The first sentence states the action and the second adds necessary nuance about ownership and side effects.

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 completely covers the action, constraints, and effect on data, including the connection to 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% and already describes the id parameter well. The description does not add further parameter details, 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 'Cancel a subscription by id.' It uses a specific verb and resource, and distinguishes from siblings like subscribe, list_subscriptions, and recent_alerts.

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

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

The description implies when to use: when you own the subscription and want to cancel. It mentions ownership enforcement and that historical data remains accessible via recent_alerts, but does not explicitly exclude other scenarios.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: returns a verdict, structured form, actual value with citation, percent delta, and that it uses SEC EDGAR + XBRL. No contradictions.

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

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

The description is fairly long but front-loaded with example query patterns. It provides necessary details without excessive fluff. Could be slightly more concise, but structure is clear.

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

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

Given it's a single-param tool with no output schema, the description fully explains return values (verdict, structured form, actual value, citation, delta) and scope (company-financial claims). It is complete for an agent to understand what to expect.

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

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

Schema covers the sole parameter with description. Description adds examples of claims and explains the type of claims supported (company-financial), along with what the tool returns, which adds value beyond the schema.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources, specifically company-financial claims. It provides a specific verb+resource ('Validate Claim') and distinguishes itself from sibling tools like deep_research or compare_entities.

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

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

The description explicitly says when to use it: when the agent needs to fact-check something a user said. It also notes the current scope (company-financial claims) and replaces multiple sequential calls. While no explicit when-not is given, it's 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.