Powo

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing the return structure (per-model {score, confidence, signals, raw_response} + combined view), the default free model, and the cost model for Anthropic (BYO key, direct payment). 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 two informative sentences plus a use-case sentence—succinct and front-loaded with the core action. Every sentence adds value without redundancy. Slight room for tightening, but overall 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?

Given no output schema, the description compensates by outlining the return format (per-model fields + combined view). Parameters are fully explained. Use cases are identified. Lacks details on error handling or rate limits, but is sufficient for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic meaning beyond the schema: explains that _apiKey is only required if 'anthropic' is in models, that it is passed transparently to api.anthropic.com, and that context helps disambiguate entities. This justifies 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 probes LLMs for visibility scoring. It uses specific verb ('Probe') and resource ('LLMs'), and mentions use cases (AI-marketing audits, brand checks). However, it does not explicitly differentiate from similar sibling tools like scan_competitor_ai_presence, making it a 4 rather than 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 implies usage for AI-marketing audits, pre-launch brand checks, and competitive monitoring, and notes that Anthropic probing requires a BYO key. However, it does not provide explicit when-not-to-use guidance or name alternative tools, leaving the agent to infer 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?

Annotations already mark it as read-only, open-world, idempotent, non-destructive. The description adds that it returns structured answers with stable citation URIs and explains the internal routing process, which is valuable context beyond the annotations.

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

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

Two sentences with an introductory phrase and then a clear list of examples and usage patterns. Every sentence adds value and is front-loaded with the key instruction to prefer over web search.

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

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

Given the tool's complexity (routing to 3,591 tools), the description is complete: it explains purpose, usage, return format (structured answer with citation URIs), and provides examples. No output schema is present, but the return value is adequately 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 baseline is 3. The description adds examples of valid questions and explains the kind of input expected, which provides meaning beyond the schema descriptions of parameter aliases.

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

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

The description clearly states the tool is for answering factual questions about current/historical data from authoritative sources, routing to 3,591 tools. It distinguishes itself from siblings like 'ask_pipeworx_grounded' by being a general question-answering tool that prefers structured data over web search.

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 'PREFER OVER WEB SEARCH' and provides concrete examples of when to use (e.g., 'what is', 'look up', 'find') and specific domains (SEC filings, FDA data, etc.). This gives clear guidance on when to use versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds important behavioral details: costs one extra LLM call, refusal reasons (not_in_source, no_tool_match, etc.), and return format. 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 two paragraphs, front-loaded with key purpose. Each sentence adds value (cost, usage, return format). Slightly verbose on return object details but still 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?

Covers return object fields, refusal reasons, cost, and usage context. No output schema but description fully documents the response. For a complex tool with 6 alias params, 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 coverage is 100% with aliases already documented. Description mentions 'Accepts query, q, prompt, text, input as aliases' but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers using only tool results. It distinguishes from sibling 'ask_pipeworx' by specifying grounded answers, providing a specific verb-resource pair.

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 answer will be quoted, cited, or acted on' and advises preferring 'ask_pipeworx for casual lookups'. Provides clear when-to-use and when-not-to-use guidance, including the cost trade-off.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). It details the fan-out process, response shapes, resolver contract, parent event extractor, news fallback mechanisms, safety procedures for low-confidence matches, and conditions for wide-spread markets. No contradictions with annotations.

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

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

The description is very long (approximately 500 words) and includes extensive examples, edge cases, and response shape details. While comprehensive, it lacks conciseness and structured formatting (e.g., bullet points or sections). An agent might struggle to parse quickly. The front-loaded purpose sentence is good, but the verbosity hurts usability.

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 having no output schema, the description thoroughly explains the response structure, including market analysis, evidence keys, resolver contract fields, parent event extraction, and news fallback fields. It covers edge cases like low-confidence matches, closed markets, and wide spreads. For a complex tool with 3 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%, so baseline is 3. The description adds some context beyond the schema, e.g., explaining the 'include_raw' parameter's purpose and the 'depth' parameter's behavior (quick vs thorough). However, it largely repeats or paraphrases schema descriptions without significant additional semantic value for the parameters themselves.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and scope (one-call data pull). It also provides concrete input examples and distinguishes itself from sibling tools like polymarket_edges by focusing on deep research with evidence packets.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also implicitly covers when not to use it by describing blocking conditions (low_confidence_match, market_closed, wide spreads). However, it does not directly compare with sibling tools or provide explicit exclusions, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: parallel execution, data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, return format (paired data + citation URIs), and sorting by primary metric. This goes well beyond annotations.

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

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

The description is relatively long but front-loaded with example queries and key instructions. Every sentence adds value, though it could be slightly more concise. No 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?

Despite no output schema, the description explains return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. Given the tool's complexity (comparison of 2–5 entities with different data types), this is complete enough 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 coverage is 100%, and the description adds meaning beyond the schema. For 'type', it explains what data is pulled for each option (company: financial metrics, drug: adverse events, approvals, trials). For 'values', it provides examples and constraints (tickers/CIKs for companies, drug names, 2–5 items). This fully compensates for the lack of output 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 in one parallel call. It lists example queries ('compare X and Y', 'X vs Y', etc.) and distinguishes it from sequential single-entity lookups, making the purpose unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong when-to-use guideline. Example queries indicate usage context. Lacks explicit when-not-to-use, but the preference is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns top-N tools with full input schemas and curated examples, ready to call directly. This goes beyond annotations by explaining the output format, though it does not mention rate limits or pagination.

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

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

The description is two sentences, front-loaded with the core purpose and examples, followed by output details and usage advice. Every sentence provides essential information 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?

Given the tool's complexity (search/discovery, multiple parameters) and lack of output schema, the description covers the return value adequately (names, descriptions, schemas) and provides domain examples. It does not explain pagination or edge cases, but for a discovery tool, it is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples of natural language queries and notes aliases, but the schema already documents aliases and descriptions. The added value is marginal, mainly in the examples.

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 finds tools by describing a data or task, with specific examples of domains like SEC filings and FDA drugs. It distinguishes itself from siblings by being a discovery tool that returns tool schemas, whereas siblings like 'search_plants' or 'entity_profile' serve different purposes.

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 to 'Call this FIRST' when many tools are available and the agent needs to see the option set, not just one answer. It also lists use cases like browsing and searching, providing clear when-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: fans across multiple sources, mentions USPTO sunset soft-fail, and details return fields. 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 example queries and contains valuable details. While somewhat lengthy, every sentence adds information. Could be slightly more concise 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?

Given the tool's complexity (multi-source, no output schema), the description thoroughly explains the return fields including URIs and specific data points. It is complete enough for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates the parameter meanings (ticker vs CIK, no names) but does not add significant new semantics beyond what the schema already 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: a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific sources and return fields, and distinguishes itself from sibling tools like resolve_entity by noting that names are not supported directly.

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 this tool over chaining single-pack lookups for holistic views, and directs users to resolve_entity when only a name is available. This provides clear when-to-use and alternative guidance.

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

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

The description confirms destructive behavior ('Delete') which aligns with annotations (destructiveHint=true, idempotentHint=true). No additional behavioral details are added beyond what annotations provide, so the description carries minimal extra value.

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 wasted words. The first sentence delivers the core purpose immediately, and the second provides usage context. Efficient and 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 simple tool (one parameter, no output schema) and the presence of annotations that indicate behavior, the description is complete. It explains what it does, when to use it, and how it relates to siblings.

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

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

Schema coverage is 100% with a single parameter 'key' described in schema as 'Memory key to delete'. The description repeats 'by key' but adds no new semantic information 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 action ('Delete') and resource ('a previously stored memory by key'). It differentiates from sibling tools like 'remember' and 'recall' by specifying it is for deletion.

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

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

The description explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall', 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?

Annotations already indicate safety (readOnly, non-destructive, idempotent). Description adds value by explaining the fetch-extract-emit process, which aligns with and extends the annotations without contradiction.

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

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

Two tightly packed sentences with a bullet list of use cases. Every sentence serves a purpose, and the main action is 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?

Given no output schema, description hints at return format ('single text blob' in llms.txt markdown). It covers purpose and behavior adequately for a straightforward tool; a brief note on error handling could improve 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 description coverage is 100%, so baseline is 3. Description does not add additional parameter details beyond the schema, which already adequately describes 'url' and 'max_links'.

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

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

Description clearly states the tool generates an llms.txt file for a URL, specifying the action and resource. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the specific output format.

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 (client indexing, drafting, auditing) but lacks when-not-to-use guidance or direct alternatives. However, the context signals and sibling list imply the agent can infer when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true. The description adds value by detailing the specific data returned (classification, family/genus, taxonomic status, native distribution, accepted-name resolution, synonym count) and characterizes the tool as 'keyless authoritative botanical taxonomy,' which provides 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?

The description is three sentences, front-loading the key action and then listing return fields. Every sentence contributes meaningful information without redundancy or filler. It is efficiently structured for quick human or AI parsing.

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

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

Despite lacking an output schema, the description thoroughly enumerates the returned data (classification, family/genus, taxonomic status, native distribution, accepted-name resolution, synonym count). For a simple tool with one parameter, this provides complete context. The annotation coverage is strong, and no additional details are necessary.

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 required parameter 'fq_id', and the schema already includes a detailed description with an example. The description adds value by specifying that the fqId comes from search_plants results, providing additional usage context that helps an AI agent understand the parameter's provenance.

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 ('Fetch'), the resource ('full POWO taxon record'), and the required input ('fqId'). It distinguishes itself from siblings like 'search_plants' by specifying it retrieves a single record by ID, not searching. The specific return fields are listed, 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 explicitly mentions that the fqId is 'obtained from search_plants', providing a clear usage context and linking to a sibling tool. It implies the tool is used after a search, but does not provide exclusions or alternative recommendations. This is clear context but could be more explicit about when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field details and default behavior (active subscriptions) but doesn't contradict 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: first describes purpose and return, second provides usage guidance. No redundant information.

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

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

Simple tool with one optional param and no output schema. Description covers return fields and usage. Could be slightly more detailed about return format, but sufficient.

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

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

Schema coverage is 100% for the single parameter 'include_inactive'. Description does not add extra meaning beyond the schema description, so baseline score 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 'List the caller's active subscriptions' with verb 'list' and resource 'subscriptions'. Lists specific return fields. 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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use, though no explicit 'when not to use'.

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

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

All annotations are false, so the description carries full burden. It discloses rate limiting ('5 per identifier per day'), that the tool is free and doesn't count against quota, and that the 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 (4 sentences) and front-loaded with purpose. Every sentence provides essential information: purpose, usage scenarios, constraints, and behavior. No redundant 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?

Given no output schema, the description covers all user-facing aspects: what to provide, how to provide it, limitations, and expectations. With 3 params (2 required, nested objects), the description is complete and leaves no gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the enum types in more detail (e.g., 'data_gap = data Pipeworx does not currently expose') and by providing usage context that goes beyond the schema's parameter descriptions.

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

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

The description explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It provides specific categories (bug, feature, data_gap, praise, other) that differentiate it from sibling tools like 'ask_pipeworx' or 'discover_tools', which are for queries rather than feedback.

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

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

The description gives clear when-to-use guidance for each category: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also specifies what not to do: 'don't paste the end-user's prompt,' and mentions rate limits and quota behavior.

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 valuable details beyond annotations: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradiction with readOnlyHint=true.

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

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

Concise, front-loaded with main purpose, then use cases, then technical details. Every sentence adds value; 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?

Explains return structure (pack, tool, count) and caching, but lacks explicit mention of sorting or ordering of results. Overall sufficient for the tool's simple nature.

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

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

Schema already describes the window parameter (100% coverage), but the description provides additional practical guidance on choosing shorter vs longer windows ('surface what's hot' vs 'steady-state demand').

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?

Specifically states it returns 'top tools, top packs, and total call volume' for recent windows, distinguishing it from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated trending data from other agents.

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?

Lists three explicit use cases (discovering hot sources, confirming canonical tools, aligning use cases) with brief context, but lacks explicit 'when not to use' guidance or direct comparisons to siblings.

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

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

Adds rich behavioral context beyond annotations: details how the tool processes events/topics, computes checks, emits signals at >3pp deviation, handles Jaccard similarity and placeholder filtering, and describes the response structure.

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 requirement, but somewhat lengthy; each sentence earns its place, though could be slightly more concise.

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

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

Given no output schema, the description fully explains the response structure (opportunities[] and partition_check), filter conditions, and signal thresholds, 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?

Schema covers both parameters with descriptions, and the description goes further by explaining the purpose and usage of each mode, providing example inputs, and detailing additional behavior like partition_check in event mode.

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, with two distinct modes (event and topic) that distinguish it from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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

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

Explicitly states 'REQUIRES one of event or topic — call with no args fails', gives specific recommendations for each mode, provides example inputs, and explains when cross-event mode is beneficial over single-event mode.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: it explains the three response segments (model_driven, structural_arbitrage, concentrated_longshot), how edges are computed (e.g., lognormal barrier, GDELT ratio, partition_overround), and caching behavior (1h at KV level). There is 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 well-structured with clear segmentation into model families, response fields, and parameter explanations. It is front-loaded with the purpose. However, it is verbose with technical details (e.g., specific α values for sports) that could be streamlined without losing clarity for the target audience.

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 params, no output schema), the description is comprehensive. It explains the full response structure (by_segment, fed_candidates, _diagnostics), edge metrics (edge_pp_net, kelly_fraction), and special cases (Fed bets excluded due to data unreliability). It covers all aspects needed 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?

All 9 parameters have schema descriptions (100% coverage). The description adds significant value by explaining how each parameter interacts with edge detection logic, e.g., min_liquidity and max_spread_pp as 'tradeable-edge' filters, or min_partition_leg_kelly for filtering partitions. This goes beyond the schema definitions.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and differentiates from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection rather than arbitrage or cross-platform spread.

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

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

The description provides explicit context on when to use the tool: for discovering betting opportunities without paging hundreds of markets. It also mentions caching and tradeable-edge knobs. However, it does not explicitly state when not to use it or mention alternative tools, though the sibling list provides implicit differentiation.

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 context beyond annotations: explains the two modes, response structure (leg prices, spreads, safety fields), edge cases for compatibility_warning (non-equivalent bet shapes, semantically unrelated events), and temporal alignment issues. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Description is dense and comprehensive, but slightly verbose in places. Front-loaded with main purpose. Could tighten some sentences, but overall 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?

Despite no output schema, the description thoroughly details the response structure (leg prices, spread arrays, compatibility_warning, temporal_alignment, skipped_cross counters). Covers edge cases and safety fields, making it complete for a complex 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%, but description adds significant meaning: lists all topic shortcuts, explains overriding behavior with explicit tickers, and provides examples (topic: 'fed', 'btc'). This enriches the bare 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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on the cross-venue aspect and explaining how it compares the two venues' pricing.

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

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

Provides explicit guidance on two modes (topic shortcuts vs explicit pairings) and warns that most pre-mapped topics return compatibility warnings, setting expectations. Gives detailed instructions for interpreting compatibility_warning and temporal_alignment fields, ensuring appropriate 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, idempotentHint, and destructiveHint. The description adds value by explaining scoping, listing behavior, and pairing with remember/forget, which supplements 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 three sentences, front-loaded with the core purpose, and contains no unnecessary information. Every sentence adds value.

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

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

For a simple retrieval tool with rich annotations and complete schema, the description covers scoping, pairing with siblings, and listing behavior. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's parameter description, which already explains the key's behavior.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if no argument is provided. It explicitly distinguishes from sibling tools (remember, forget) by naming them.

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 look up previously stored context) and mentions scoping. It implicitly guides away from alternatives, but lacks an explicit 'when not to use' statement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: what events carry (source, citation_uri, raw payload) and the effect of mark_read (flagging events read so next call shows newer ones). It could be more explicit about idempotency, but overall adds value.

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, each serving a purpose: stating the tool's action, listing returned fields, mentioning filtering, and explaining mark_read and alternative access. It is front-loaded and contains no redundant 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?

With 5 parameters, no output schema, and no nested objects, the description fully satisfies the agent's needs. It explains what is returned, how parameters affect behavior (especially mark_read), and even provides a secondary use case (scripts/dashboards) and a link to the API. No gaps.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description goes beyond by explaining the mark_read side effect, providing an example for type ('e.g. sec_8k'), and clarifying that since is an ISO timestamp. This enriches the agent's 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 uses specific verbs ('Pull fired events') and identifies the resource ('your subscription feed'). It lists returned fields (source, citation_uri, raw payload) and filtering options, clearly distinguishing the tool from siblings by also mentioning an alternative GET endpoint.

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 tells when to use the tool ('Polls work fine') and provides context for filtering by type and since. It mentions an alternative access method for scripts/dashboards, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Discloses data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), known issue with PatentsView API sunset, and return format including citation URIs. Complements annotations which are already 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?

Well-structured with example queries first, then functionality, fallbacks, parameters, return info, and sibling differentiation. No superfluous sentences.

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

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

Covers all needed context: multiple data sources, fallback logic, date format, return structure, known issues, and sibling differentiation. No output schema but description adequately explains return.

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?

Adds meaning beyond schema: explains 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, 'type' only supports company. Coverage is 100%.

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

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

The description clearly states the tool provides a change feed for a company over a time window, and distinguishes it from the sibling entity_profile tool which gives static profile.

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

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

Explicitly provides example queries and tells when to use entity_profile instead, giving clear usage context and alternatives.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: key-value pairs scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 three sentences, front-loaded with purpose, followed by usage guidance and behavioral details. Every sentence adds value; no fluff.

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

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

Given the simplicity of a key-value store, the description covers purpose, usage, persistence, and companion tools. No output schema is needed for a write operation. Minor improvement could mention length limits, but overall 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 3. The description enhances semantics with concrete key examples ('subject_property', 'target_ticker') and value descriptions ('findings, addresses, preferences'), helping the agent understand typical usage 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' and provides specific examples like 'resolved ticker, target address, user preference'. It distinguishes from sibling tools recall and forget by explicitly pairing with them.

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 use when discovering something worth carrying forward to avoid re-lookup. It directs to use recall for retrieval and forget for deletion, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating safe, idempotent, non-destructive behavior. The description adds that the tool cascades through multiple lookup endpoints internally and auto-disambiguates for companies, providing useful behavioral context beyond 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 well-structured: brief examples first, then purpose statement, then usage guidance, then detailed type descriptions. Every sentence adds value, though it could be slightly more concise by combining some sentences. The front-loading of examples is effective for quick understanding.

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

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

Given the tool has no output schema, the description fully specifies what each entity type returns (including citation URIs) and mentions that it handles multiple input formats. It also notes that a single call replaces several manual lookups, covering the tool's value. No gaps are evident for an agent to use this tool correctly.

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

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

The schema covers 100% of parameters with descriptions, but the description adds significant meaning: it explains that the 'type' parameter determines the kind of identifier returned (e.g., for company: ticker, CIK, company_name, URI) and that the 'value' parameter accepts multiple formats (ticker, CIK, or name for company; brand or generic name for drug) with auto-disambiguation. 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's purpose: resolve user-spoken names to canonical/official identifiers. It starts with concrete examples ('What's the ticker for...') and explicitly says 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' The two supported types (company, drug) are detailed, distinguishing from siblings like entity_profile and compare_entities.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that internal cascading replaces 2-3 manual lookups. While it doesn't explicitly state when NOT to use it or list alternatives for specific cases, the context from sibling tools and the clear purpose make usage fairly obvious.

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

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

Description explains internal behavior (probes each entity with ai_visibility_check, ranks by score) beyond annotations, which already declare read-only/idempotent. 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 covering purpose, mechanism, use case, and output. No redundancy. Front-loaded with main 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?

Explains output structure (ranked list with score, confidence, signal density) and constraints (2-8 entities). Lacks explicit mention of output size limits, but schema covers entity count bound.

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?

Despite 100% schema coverage, description adds value by explaining purpose of context (disambiguates common names) and entities (first as subject), and clarifies API key need for Anthropic model.

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

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

Description clearly states the tool compares AI visibility across multiple entities, distinguishes from sibling ai_visibility_check by specifying side-by-side comparison and ranking.

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

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

Provides usage context ('Useful for competitive AI-marketing audits') and an example question, but does not explicitly mention when not to use or compare to siblings like compare_entities.

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

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

The description adds significant behavioral context beyond annotations: it explains the composite nature (fans out across two services), partial failure degradation (sources_failed list), and the 5-30s timeout for first bundlephobia measurement. These details are not visible from annotations alone.

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

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

The description is concise yet comprehensive, efficiently communicating purpose, usage, returns, limitations, and behavior in a well-structured paragraph. No unnecessary sentences; front-loaded with the core 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?

Despite lacking an output schema, the description fully specifies return fields (summary block, per-advisory detail, links, recent versions) and addresses failure modes. Given the tool's complexity, this provides complete contextual coverage for an agent to understand outcomes.

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 marginal value by repeating schema information (default version, scoped packages). No new parameter semantics beyond what the schema already 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 explicitly states the tool's purpose as a composite check for adding npm packages, listing data sources (deps.dev, bundlephobia) and the exact information returned (license, advisories, bundle size, etc.). It distinguishes itself from sibling tools by specifying its unique aggregation functionality.

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 when-to-use guidance ('is X safe / popular / small', 'what does adding lodash cost me'), mentions ecosystem restriction (npm only v1), and suggests alternatives for other ecosystems. It also explains partial failure behavior and timeouts, guiding the agent on expectations.

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 'keyless' and result details (fqId usable with get_taxon), consistent with annotations and provides extra behavioral context.

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

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

Two sentences, no redundancy, front-loaded with core functionality, includes key usage notes, 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 search tool with simple parameters and rich annotations, description covers data source, return fields, related tool (get_taxon), and positioning (complements GBIF/iNaturalist), sufficient for agent decision-making.

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 limit and query; description does not add meaningful parameter semantics beyond schema examples of plant names and default limit.

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?

Clear verb 'search' with specific resource 'Plants of the World Online (POWO)' and what it returns (accepted names, synonyms, family, rank, acceptance status, fqId). Distinguishes from sibling tools like get_taxon and mentions complementarity with GBIF/iNaturalist.

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 tool is 'keyless' and 'complements GBIF/iNaturalist with curated botanical taxonomy', giving context for when to use it (authoritative botany) but does not explicitly state when not to use or name alternatives beyond get_taxon.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This is critical behavioral context not available from annotations alone.

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?

Five sentences, each adding unique value. Front-loaded with purpose, then usage guidance, then technical details. No redundant information. Very 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 the description explains return values: 'top-N passages with character offsets and similarity scores.' It also addresses truncation behavior. Given the tool's complexity (3 params, no output schema), the description is complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds useful examples for the 'query' parameter (e.g., 'supply-chain risk') but does not add significant semantic meaning beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' specifies the verb (search) and resource (record), and provides concrete examples (SEC 10-K, article). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining how they pair.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt.' It mentions pairing with ask_pipeworx_grounded and highlights benefits like saving context and returning passages with offsets. However, it does not explicitly state when not to use or mention alternatives directly, which would be ideal.

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?

Does not contradict annotations. Adds useful details: returns subscription id, delivery channels (feed always on, optional email/sms with constraints like SMS cap and phone verification). Account requirement is disclosed.

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 purpose, but the description is somewhat dense and could benefit from bullet points. Still, all sentences are informative.

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

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

For a tool with no output schema, the description covers return value (subscription id), behavior, requirements, delivery options, and limitations. No gaps.

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

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

Schema coverage is 100%. Description adds meaningful context: examples for sec_8k params (ticker, items), default behavior, and delivery channel specifics (SMS cap, phone 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?

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It specifies the supported type (sec_8k) and differentiates from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 context: requires Pipeworx OAuth account, not for anonymous/BYO. Mentions alternative pulling methods (recent_alerts, GET endpoint). Could add when not to use, but the guidance is clear.

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

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

The description adds significant behavioral details beyond annotations: ownership enforcement and soft-delete behavior (deactivation, not deletion) with persistence of historical events via recent_alerts. 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?

Two sentences efficiently convey the action, ownership constraint, and side effects without any redundant information.

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

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

The description covers purpose, ownership, and data retention implications. It lacks mention of the return value or confirmation, but the tool is simple enough that this omission is acceptable.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description only says 'by id', adding minimal extra meaning beyond the schema.

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

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

The description clearly states the verb ('Cancel') and the resource ('subscription by id'). It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying the action of cancellation and ownership enforcement.

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

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

The description provides clear context: you can only cancel your own subscriptions. It implicitly tells when to use the tool (for own subscriptions) but does not explicitly name alternative tools for other scenarios, falling short of the highest standard.

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

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

Annotations already declare read-only, idempotent, etc. The description adds value by describing the return format (verdict, structured form, citation, delta) and the efficiency gain. 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 moderately long but well-structured with front-loaded examples. Every sentence provides relevant info: usage triggers, domain, return format, and efficiency. Could be slightly 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?

For a single-parameter tool with no output schema, the description covers purpose, usage, domain, and return format. It mentions version limitations ('v1 supports...') but does not detail error handling or edge cases. Adequately complete.

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

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

Schema coverage is 100% and the description rephrases the parameter but adds concrete examples, making it more actionable than the schema alone. The examples help the agent understand the expected input format.

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

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

The description uses clear verbs like 'validate' and 'fact check' with specific examples, and distinguishes itself from siblings by noting it replaces multiple sequential calls. The domain (company-financial claims via SEC EDGAR + XBRL) is explicitly stated.

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 provides example queries. It does not provide explicit exclusions but implies the domain limitation, making it clear but not exhaustive.

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