Seo Keywords

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds that Anthropic calls require user's key and direct payment, and details the return format (score, confidence, signals, raw_response). 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?

Single paragraph of 4 sentences, front-loaded with main action and key details. Every sentence adds value 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?

Explains return format and use cases. Lacks output schema but the description compensates. Could mention rate limits or max models, but overall sufficient given annotations.

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 all 4 parameters with descriptions (100% coverage). Description adds context on default model, the role of _apiKey, and the 'context' parameter's purpose for disambiguation, enhancing schema info.

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 topic visibility and returns a score (0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general brand/topic visibility rather than competitor 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?

Explicitly mentions use cases (AI-marketing audits, pre-launch checks) and model selection (default free model, Anthropic requires key). However, no explicit when-not-to-use or comparison to alternatives like 'bet_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?

Transparencies (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are already present. The description adds valuable behavioral context: routes to 4,476 tools across 1,127 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. No contradiction.

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

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

Description is detailed yet concise; uses bullet points for examples and sibling comparisons. Front-loads the primary directive ('PREFER OVER WEB SEARCH'). Every sentence adds value 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?

Despite complexity and no output schema, the description thoroughly covers the tool's purpose, scope, return format (structured answer with citations), and clear usage guidance. Examples cover a wide range of domains, making it complete 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 has 100% coverage with clear descriptions of all 6 parameters (aliases for question). Description does not add parameter-level meaning beyond schema, but provides examples of valid questions which indirectly guides usage. 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 a vast set of verified sources for authoritative structured data with citations. It lists specific domains (SEC, FDA, FRED, etc.) and includes examples, effectively distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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 when-to-use scenarios with example queries. It also instructs when to step up to alternatives for hallucination resistance or broad questions, giving clear usage boundaries.

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, etc. The description adds behavioral details like refusal reasons (not_in_source, no_tool_match) and the extra LLM call cost, enriching transparency 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?

Two paragraphs with front-loaded purpose. Every sentence adds value: purpose, process, output format, refusal reasons, usage advice. 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?

Comprehensive for a complex tool: explains difference from sibling, output format, refusal reasons, and cost trade-off. No output schema, so description rightly details return structure.

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

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

Schema coverage is 100% with all parameters described. The description adds that it accepts multiple aliases for 'question', but this is minimal additional value. 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 only from tool results with explicit refusal. It distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and use cases.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and advises preferring ask_pipeworx for casual lookups due to cost. Provides 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 mark as read-only, idempotent, non-destructive. The description adds extensive behavior details: fan-out examples, response shapes, resolver contract with confidence levels, parent event extraction, news field fallback mechanics, safety short-circuits, liquidity warnings, and cancellation rule parsing.

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

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

The description is verbose (~700 words) but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While every sentence adds value, it could be more concise without losing clarity.

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

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

No output schema exists, so the description fully explains all response fields (market, analysis, evidence, parent_event, news) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It is complete for the tool's complexity.

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

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

Schema coverage is 100%; description enriches every parameter: market input types (slug, URL, question text), depth default and behavior (quick vs thorough), include_raw default and response size implications. This adds significant value beyond the schema.

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

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

The description specifies a clear verb ('research') and resource ('Polymarket bet'), detailing the process of resolving, classifying, fanning out, and returning an evidence packet with comparison. It distinguishes itself by focusing on Polymarket bets with specific data packs, contrasting with siblings like ask_pipeworx or deep_research implicitly.

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

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

The description gives explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it does not state when NOT to use it or directly compare to sibling tools, leaving some ambiguity for agents.

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, indicating safety. The description adds valuable behavioral context: it explains the data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and claims it replaces 8-15 sequential lookups. 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 somewhat lengthy but well-structured: begins with example queries, explains purpose, then details per type, sorting, and efficiency claim. Every sentence adds value, though some redundancy exists (e.g., repeating '2-5'). It earns its 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 full schema coverage, healthy annotations, and no output schema, the description is thorough: it covers data returned (paired data + citations), sorting, and efficiency gains. It does not detail error behavior or exact return format, but that is acceptable without an output schema.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'type' it details what data is pulled for company (revenue, net income, etc.) and drug (adverse events, approvals), and for 'values' it specifies tickers/CIKs for companies and names for drugs with examples. This far exceeds 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 that the tool performs side-by-side comparisons of 2-5 companies or drugs in one call, with specific examples and explicit instruction to prefer it over sequential lookups. The verb 'compare' is precise, and the resource (entities) and scope (2-5) are unambiguous, distinguishing it from single-entity tools like 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?

Provides explicit guidance to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' effectively telling when to use this tool. It also explains the different data sources per type. However, it does not discuss when not to use it (e.g., for more than 5 entities) or compare directly with sibling 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?

Discloses many behaviors beyond annotations: not open-web search, decomposes questions, parallel execution, returns gaps[], never invents, 15-60s. No contradiction with annotations (readOnlyHint, openWorldHint, 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?

Each sentence earns its place; front-loaded with critical account requirement. Slightly verbose but still focused and well-structured for a complex tool.

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

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

Complete given 2 parameters and no output schema: describes output format (findings packet with evidence, confidence, gaps). No missing essential context for an AI agent to select and invoke correctly.

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

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

Schema covers both parameters 100%, but description adds value by explaining depth enum values (quick=3, standard=5, thorough=8) and noting paid plan requirement for thorough. Also describes question as 'natural language' and 'broad/multi-part is fine'.

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

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

Specific verb (research) and resource (Pipeworx's 1127 structured data sources). Distinguishes from sibling ask_pipeworx (single lookup) and explicitly states what it is NOT (open-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?

Clearly states account requirement, when to use (broad/multi-part questions) vs when not to use (breaking news, use ask_pipeworx). Provides example queries and alternative tool names.

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 beyond annotations: returns top-N relevant tools with names, descriptions, and full schemas with curated examples, ready to call directly. No contradictions with readOnlyHint, idempotentHint.

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 listing many domains makes it slightly verbose. Still efficient 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?

No output schema, but description fully explains what is returned (tools with names, descriptions, schemas) and why ready to call. Adequate for its purpose.

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

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

Schema coverage is 100% with descriptions already. Description adds examples but no new parameter-level insights 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 the tool finds tools by describing data or task, listing specific domains like SEC filings, FDA drugs, etc. It distinguishes from siblings (e.g., bet_research, compare_entities) by being a discovery tool.

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 call this first when wanting to see available options, and when needing to browse/search/discover tools. This provides clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: lists all datasources fanned out (SEC EDGAR, XBRL, USPTO, news, GLEIF), describes return fields with specifics (e.g., 'fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC)'), and explicitly notes a known failure mode ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). 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: opens with concrete examples, then explains the cross-source behavior, and finally details the return fields. Every sentence adds substantive information. While it could be tightened slightly, it avoids redundancy and remains focused.

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 what the tool returns: cik + company_name, recent_filings with direct URIs, fundamentals with sorting, patents status, news via GDELT→GNews fallback, and LEI via GLEIF. It also covers edge cases (patents soft-fail, name not supported). The description is sufficiently complete for an AI agent to understand the tool's capabilities and limitations.

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

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

The input schema (100% coverage) already documents both parameters and their constraints. The description adds valuable context beyond schema: explains that 'value' accepts ticker or CIK (not names), elaborates on 'type' by stating only 'company' is supported with others coming soon, and reiterates the name limitation. This enhancement justifies a score above the baseline of 3.

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

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

The description starts with concrete examples ('Tell me about X', 'research Acme') that clearly indicate the tool's purpose: generating a holistic cross-source profile for US public companies. It explicitly states 'ALWAYS PREFER over chaining single-pack lookups' and distinguishes from sibling tools by noting that names are not supported (use resolve_entity instead). This makes the purpose unambiguous and well-scoped.

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

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

The description provides explicit when-to-use guidance ('holistic view') and when-not-to-use ('names not supported', instructing to use resolve_entity first). It also prioritizes this tool over chaining alternatives, giving clear direction for the AI agent. This is exemplary usage guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms destructive nature but adds no new behavioral context (e.g., how deletion affects other tools, whether it's reversible). 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, minimal and efficient. No redundant phrases.

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 simplicity (1 param, no output schema, clear sibling context), description covers purpose and usage well. Could mention behavior on missing key minimally.

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

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

Only one parameter ('key') with schema coverage 100%. Description adds no extra meaning beyond 'Memory key to delete' already in schema. Baseline 3 applies.

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

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

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource. However, it doesn't explicitly differentiate from sibling tools like 'remember' and 'recall' beyond mentioning pairing.

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

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

Provides explicit when-to-use scenarios ('when context is stale, task is done, clear sensitive data') and references sibling tools. No when-not-to-use given, 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?

The description discloses actions (fetches, extracts, emits markdown) that align with the annotations (readOnlyHint, destructiveHint false). It adds value by explaining the process and output format beyond what annotations convey. No contradictions, but could mention potential rate limiting or network dependencies.

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 succinct with two efficient sentences plus a brief use-case list. Key information is front-loaded (action, output, purpose), and every sentence adds value without redundancy.

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

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

For a tool with two parameters, clear annotations, and no output schema, the description sufficiently covers what the tool does, how it works, output format, and when to use it. No gaps for an agent to decide applicability.

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

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

Schema coverage is 100% and the schema already describes both parameters including defaults and limits. The description does not add new information about the parameters beyond what the schema provides. Baseline 3 is appropriate as the description does not need to compensate for insufficient 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 specifies a clear verb ('generate') and resource ('llms.txt file for any URL'), and distinguishes from sibling tools by focusing on AI crawler indexation. It also provides concrete use cases, making the purpose unmistakable.

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

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

The description includes a 'useful for' section with specific scenarios (client site indexing, personal drafts, competitor auditing), providing clear context for when to use. However, it does not explicitly state when not to use or mention alternative tools, like ai_visibility_check or scan_competitor_ai_presence, which are 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds useful context: it returns specific fields and implies scoping to the caller. 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: the first covers purpose and return fields, the second gives usage guidance. No unnecessary words.

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

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

For a simple tool with one optional boolean parameter and no output schema, the description is complete: it explains what it does, what it returns, and when 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%; the parameter 'include_inactive' is described in the schema. The description does not add additional meaning beyond the schema, 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 'List' and resource 'subscriptions', specifies the scope 'caller's active', and lists the returned fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by being the read operation.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it does not mention explicit alternatives or 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?

Discloses that feedback is free, doesn't count against tool-call quota, and is rate-limited to 5 per identifier per day. Annotations are non-contradictory and description adds behavioral context beyond structured fields.

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

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

The description is well-structured with front-loaded purpose and clear guidelines. It is slightly longer than minimal but every sentence adds value, so it earns a high score.

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 explains what happens after sending (team reads digests, affects roadmap). For a feedback tool of moderate complexity, this is complete enough.

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

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

Schema coverage is 100%, and description enriches each parameter: explains enum options for type, describes context fields, and specifies message constraints (plain text, 1-2 sentences, 2000 chars max).

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

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

The description clearly states the tool is for sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It distinguishes itself from sibling tools by focusing on feedback, not data retrieval or queries.

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

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

Explicitly lists when to use each feedback type (bug, feature, data_gap, praise, other) and provides a clear instruction to avoid pasting end-user prompts. Also 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?

The description goes beyond annotations by disclosing data source ('CF analytics-engine'), privacy ('no PII'), data structure ('pack, tool, count'), and caching behavior ('cached 5min-1h'). Annotations already indicate read-only, idempotent, non-destructive, and the description adds significant context.

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

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

The description is concise and well-structured: a single sentence stating the core function, followed by bullet-point use cases, and then technical details. 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?

The description covers the output (top tools, top packs, total call volume), caching, and use cases. Given the simplicity of the tool (one optional parameter, no output schema), it provides sufficient context 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%, and the description adds value by explaining the trade-off between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This surpasses the baseline of 3.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, using a specific verb 'returns' and defining the resource as trending data. It distinguishes itself from siblings like 'discover_tools' by focusing on call volume and current activity.

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 (discovering hot data sources, confirming popular tools, aligning use cases). It does not explicitly state when not to use, but the context is clear. The lack of direct comparison to alternatives prevents a higher score.

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 context, such as walking child markets, checking ordering, computing partition_check, filtering placeholders, and performing fill checks against live CLOB depth. It explains what each mode does and the response structure. 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 relatively long but well-structured with clear sections (modes, semantic anchor, partition filter, fill check). It is front-loaded with the requirement for one of event or topic. While not extremely concise, every sentence provides necessary detail for such a complex tool.

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

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

Despite having no output schema, the description thoroughly explains the response structure: 'opportunities[]' with fields, and in event mode 'partition_check' with fields. It also covers fill check behavior. Given the tool's complexity and 2 parameters, the description is complete and leaves no ambiguity.

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

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

Parameter descriptions in the schema cover 100% of parameters, but the description goes further by explaining the two modes in detail, giving examples of valid values, and clarifying the behavior of each parameter. It adds meaning beyond the schema, such as the semantic anchor and partition filter conditions.

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 precisely states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between event mode and topic mode, and provides examples of each. This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: event mode for a specific market (recommended), topic mode for cross-event scanning. It warns that calling with no args fails. It also references a sibling tool 'polymarket_fill_risk' for custom sizing, providing clear guidance on when to use this tool vs alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are present, but the description adds extensive behavioral context: caching at 1h, model families and their gates, diagnostics for empty segments, Fed data limitations, and edge computation details. This adds significant value beyond annotations, fully disclosing behavioral traits.

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

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

The description is very long but highly informative. It is front-loaded with the main purpose, then details models and knobs. While not concise, every sentence adds value. Could be more structured (e.g., bullet points or sections), but it effectively communicates complex information.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response format (by_segment, diagnostics), what each opportunity carries, caching, and knob effects. The description provides enough context for an agent to use the tool effectively without additional documentation.

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 full descriptions in the input schema (100% coverage). The description adds context, such as 'max_spread_pp: Set to 2 to require tight books — anything wider eats most plausible edges.' and 'min_partition_leg_kelly: apply to per-leg Kelly inside top_legs.' These explanations enhance meaning beyond schema basics.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan', the resource 'Polymarket markets', and the unique value 'Pipeworx data disagrees with market price'. The tool distinguishes itself from siblings like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on a specific data source and angle.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the knobs (e.g., min_liquidity, max_spread_pp) and when to use them. However, it does not explicitly state when NOT to use this tool or compare it to alternatives like 'polymarket_arbitrage' or 'polymarket_edge_tracker'. Still, the usage 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, idempotent, non-destructive), description discloses time-series nature, response structure (tracked, expired, snapshot_dates), decay computation (from daily closes, not intraday), and limits (60-day TTL, snapshot start). 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 relatively long but front-loaded with purpose. Structured with key question, then arg explanation, then response breakdown. Every sentence is informative; no fluff. Could be slightly shorter 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?

Without output schema, description fully explains the three response arrays (tracked, expired, snapshot_dates) and their fields. Also covers limits and data source. Complete for a tool of this complexity.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds default values and clamp for days, and enumerates options for window with default. Adds context about 'snapshot family' meaning, adding value beyond schema.

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

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

Description clearly states specific verb+resource: 'edge persistence and decay telemetry built from daily polymarket_edges snapshots'. It answers a specific question about edge longevity, distinguishing it from sibling tools like polymarket_edges and 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?

Provides context on when to use the tool by contrasting fresh vs. old edges, implying use for persistence assessment. Does not explicitly list alternatives or when not to use, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds operational context such as possible verdicts (clean|degraded|cannot_fill) and the risk of thin books, which complements 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 well-structured with uppercase section headers (SINGLE-MARKET, BASKET) and bullet-like lists for return fields. Despite its length, every sentence adds value, and the core purpose 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 the complexity (two modes, detailed returns, and risk factors), the description covers all necessary aspects: it explains the return fields, usage context, and potential pitfalls. There is no output schema, but the description compensates by listing what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning: it explains each parameter's role in single-market vs basket mode, default values, and constraints (e.g., 'clamp 10–1,000,000'). This goes well beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it before those signals.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely solely on theoretical overround, highlighting the risk of partial basket fills converting an arb into an unhedged directional position.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, etc. The description adds significant context: compatibility_warning conditions (non-equivalent bet shapes, no token overlap), temporal_alignment, and counters for skipped comparisons. This fully discloses behavioral traits beyond annotations.

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

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

The description is detailed but well-structured, with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. While lengthy, every sentence provides necessary context for a complex tool. A minor trimming 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 no output schema, the description thoroughly explains the response: leg-by-leg prices, spread array, and safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It covers edge cases and interpretation, making the tool usable without additional documentation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by elaborating on the topic parameter (listing the 10 macros and explaining auto-fetch behavior) and explaining the override semantics for kalshi_event_ticker and polymarket_event_slug. It also describes the response structure, supplementing 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two modes (topic and explicit) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use each mode ('TWO MODES: (1) topic — 10 pre-mapped macro shortcuts ... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings'). It also provides guidance on interpreting results, e.g., 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today'. 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scope (per identifier) and the listing behavior. It doesn't detail error handling or limits, but given the annotations, it's sufficient.

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

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

Three sentences, each essential. First sentence states the primary action and alternative. Second provides usage context and examples. Third explains scope and pairing. 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 one parameter, no output schema, and good annotations, the description covers the core functionality: retrieving by key, listing all, scope, and relationship to remember/forget. Minor omissions like maximum keys or behavior for missing keys are 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?

The single parameter 'key' is fully described in the schema (100% coverage). The description adds significant value by explaining that omitting the key lists all saved keys, which is not inferable from 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 verb 'retrieve' or 'list' and the resource 'values previously saved via remember'. It distinguishes from siblings 'remember' (save) and 'forget' (delete), and explains the listing behavior when key is omitted.

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

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

It explicitly states when to use (to look up context stored earlier, with examples like ticker, address, notes) and pairs with remember/forget. It doesn't explicitly state when not to use or compare to other tools like deep_research, but the context is clear enough.

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

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

Description states mark_read:true flags events as read, implying a side effect that modifies state. However, annotations declare readOnlyHint=true, indicating the tool is read-only. This contradiction undermines transparency.

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

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

Three concise, well-structured sentences that front-load the main action and avoid 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?

Explains returned fields and alternative access method. Missing mention of limit parameter behavior, but overall adequate for a read tool with good schema coverage.

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

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

Schema coverage is 100% with parameter descriptions, but description adds value by providing examples (e.g., 'sec_8k' for type) and explaining mark_read's effect on subsequent calls.

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 pulls fired events from subscription feed, returns alerts with specific fields (source, citation_uri, raw payload). Distinct from sibling tools like list_subscriptions and subscribe.

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 filtering by type and since, explains mark_read behavior, and offers alternative URL for scripts/dashboards. Does not explicitly state when not to use, but 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description's read-only 'change feed' framing. Discloses multi-source fan-out with fallback (GDELT→GNews), soft-fail for USPTO, and return structure (changes[] grouped by source + total_changes + citation URIs), 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?

Single paragraph packs examples, purpose, technical details, and alternative guidance. Somewhat dense but every sentence is informative. Minor improvement would be using bullet points for clarity, but current structure is effective.

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

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

Despite no output schema, the description sufficiently explains return structure and source details. Covers input, behavior (parallel call, fallbacks), and output. Context signals (3 required params, 100% coverage) and annotations support the provided information. Complete for an AI to invoke correctly.

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

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

100% schema coverage with descriptions for all 3 params. Description adds value by: explaining 'since' formats (ISO date or relative shorthand) with example, recommending '30d' or '1m' for monitoring, and clarifying 'value' accepts ticker or CIK. Also notes only 'company' type is supported.

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

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

Opens with specific user queries ('What's new with X', 'latest on Y') and defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' Directly distinguishes from sibling entity_profile by stating when to use each.

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 when to use (e.g., 'updates on Acme', 'news on Tesla recently') and provides a clear alternative: 'Use entity_profile instead when you want the static profile.' Also explains internal fan-out and fallback behavior, aiding tool 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?

Description adds value beyond annotations by explaining scoping ('scoped by your identifier'), persistence duration ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and storage format ('key-value pair'). No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, then expands with usage and behavior. 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?

Covers key aspects: purpose, when, scoping, persistence. But lacks mention of return values (though no output schema) and overwrite behavior. Still fairly complete for a simple write tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add additional parameter semantics beyond what's already in the schema.

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

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

Description clearly states verb 'Save' and resource 'data the agent will need to reuse later' with explicit examples of what to store (resolved ticker, target address, etc.). It distinguishes from siblings like 'recall' and 'forget' by mentioning 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?

Explicitly states when to use: 'when you discover something worth carrying forward' and provides concrete examples. Mentions pairing with recall and forget, and scoping by identifier.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that each call cascades through multiple internal lookups and replaces 2-3 manual steps, providing 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 somewhat lengthy but front-loaded with examples and has clear sections per type. Every sentence adds value, though it could be slightly more concise.

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

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

With no output schema, the description fully explains return values for each type (ticker, CIK, citation, etc.) and notes it replaces multiple lookups. For a 2-param tool, it is complete.

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

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

Schema coverage is 100%, but description adds meaning: for company, it accepts ticker, CIK, or name and auto-disambiguates; for drug, it accepts brand or generic name. This enriches understanding beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific example queries. It distinguishes itself from sibling tools by noting it should be used first when a name needs an ID.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It covers supported entity types and what they return, providing clear context for when to use this tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context: it probes entities with ai_visibility_check, uses optional API key for Anthropic, and returns a ranked list. This supplements annotations without contradiction.

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

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

The description is three sentences, each purposeful: first sentence states action, second explains process, third gives use case. No filler, front-loaded with the main verb 'Compare AI visibility…'.

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 4 parameters with full schema descriptions, no output schema but the description specifies return fields (score, confidence, signal density per entity), and the tool's moderate complexity, the description sufficiently covers purpose, input, output, and use case. It also clarifies the internal call to ai_visibility_check.

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

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

Schema description coverage is 100%. The description adds value by stating that the first entity is treated as the 'subject' for narrative and that the tool probes each entity with ai_visibility_check, which is not evident from parameter descriptions 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies actions: probes entities with ai_visibility_check, ranks by score, surfaces most/least recognized. The example use case and differentiation from sibling ai_visibility_check (single entity) is implicit via 'multiple 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 gives a clear usage context: 'Useful for competitive AI-marketing audits' with an example question. While it doesn't explicitly state when not to use or list alternatives, the implicit contrast with ai_visibility_check (single entity) and the required array of 2-8 entities guides 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 provide readOnly, idempotent, and open-world hints. Description adds valuable context about graceful partial failures, including bundlephobia's first measurement delay (5-30s) and the sources_failed field. 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?

Description is dense but efficient, front-loading the core purpose. It includes necessary technical details without redundancy, though it could be slightly more structured for readability.

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

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

No output schema, but description thoroughly lists all return fields: summary block, per-advisory detail, links, and alternative versions. Also covers partial failure behavior, making the tool's output and edge cases clear.

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. Description adds clarifying examples for version (e.g., '18.3.1') and states that scoped packages are accepted, providing added 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?

Description clearly states it is a composite check for deciding whether to add an npm package, fanning out across deps.dev and bundlephobia. This distinguishes it from all sibling tools, none of which perform similar dependency scanning.

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

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

Explicitly states usage scenario: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies NPM-only scope and directs to alternatives for other ecosystems via deps.dev:version.

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 valuable specifics: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char limit with truncation flagging, and character offsets for verification. This exceeds what annotations provide.

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

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

Single paragraph efficiently packs purpose, usage guidelines, behavioral details, and technical specifics without redundancy. 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?

Despite lacking an output schema, the description fully explains what is returned (top-N passages with offsets and scores) and covers technical limits (200K chars, windows, embeddings). For a search tool, this is comprehensive.

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 detailed parameter descriptions. Description does not add significant new semantics beyond what is in the schema, but it reinforces the natural-language usage of 'query' and notes the char limit for 'text'. 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?

Clearly states 'Semantic search INSIDE a fetched record', distinguishing it from sibling tools by specifying it operates on already-fetched text. The verb 'search' and resource 'text within a record' are explicit.

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

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

Provides explicit when-to-use: 'when the record is too big to cram into the prompt'. Also pairs with sibling 'ask_pipeworx_grounded' for a full workflow. No when-not-to-use needed given clarity.

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 by specifying the batch size (up to 10 keywords), the metrics returned (search volume, difficulty, CPC, competition), and the required API key format. Annotations already indicate the tool is read-only, idempotent, and non-destructive, so the description complements without contradicting.

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: two sentences and an example. It front-loads the main purpose and includes no extraneous information. Every sentence contributes to 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's complexity (4 parameters, no output schema, rich annotations), the description covers the essential aspects: purpose, inputs, outputs, example, and authentication. It is complete for an agent to select and invoke correctly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing a full example with real values, explaining the API key format, and noting the default location code (2840 for US). This clarifies usage beyond the schema.

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

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

The description uses a specific verb ('returns') and clearly identifies the resource (monthly search volume & difficulty for keywords) and the outputs (search volume, difficulty, CPC, competition). It explicitly states the tool is for 'Keyword research for SEO,' distinguishing it from sibling tools like bet_research or polymarket_*.

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 (SEO keyword research) and a concrete example, implying when to use. However, it does not explicitly state when not to use or list alternatives, leaving room for slight 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?

Description provides rich behavioral details (OAuth requirement, type-specific params, delivery channels with caps and verification). However, annotations include idempotentHint=true, which contradicts the described behavior—each call creates a new subscription and returns a new ID, implying non-idempotent creation. This contradiction reduces trust.

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 longer but well-structured: purpose first, then types, then delivery options. Each sentence adds necessary detail. Could be slightly trimmed, but given complexity, it is appropriately dense 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?

Given no output schema, the description covers the return value ('subscription id'), auth prerequisites, every parameter type, delivery channel behavior, rate limits (10 SMS/day), webhook auto-disable after 10 failures, and verification steps. Comprehensive for a creation 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 the description adds significant value beyond the schema by explaining type-specific parameter formats (e.g., 'items:["5.02"] = officer change'), delivery channel constraints (SMS cap, phone verification), and webhook signing. These details are not present in the schema descriptions 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 action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return ('Returns the new subscription id'). It differentiates from sibling tools like 'list_subscriptions' and 'unsubscribe' by specifying creation versus management.

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 auth requirement ('Requires a Pipeworx OAuth account') and provides examples for each subscription type. Mentions alternative for pulling alerts ('recent_alerts'), but does not explicitly state when not to use this tool. Still, context is helpful.

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 that it returns category-bucketed example questions with exact tool shapes, drawn from live catalog. Does not contradict annotations and adds useful 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?

Description is fairly long but all sentences provide value. It front-loads trigger phrases and uses clear structure. Could be slightly more concise but overall well-organized.

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

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

Given no output schema, description explains return content thoroughly (category-bucketed example questions with tool+argument shape) and covers main use cases. Completeness is high 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 description coverage is 100%, so baseline is 3. Description adds minimal extra meaning beyond schema for the 'topic' parameter, just examples that overlap with schema description.

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

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

The description clearly states the tool returns example questions to help users know what to ask, serving as an onboarding entry point. It includes trigger phrases and distinguishes itself from sibling tools by being first-use oriented.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on calling with or without topic, but does not explicitly list exclusions or 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 (destructiveHint=false), the description clarifies that the row is deactivated (not deleted) and historical events remain 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, all information is relevant and non-redundant. Very 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 single-parameter tool with no output schema, the description fully explains the effect (deactivation, historical availability), making it complete for effective 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%, with the 'id' parameter already described. The description adds 'by id' and ownership context, but does not significantly enhance parameter semantics beyond the schema.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Clearly states ownership enforcement ('you can only cancel your own subscriptions'), but does not explicitly contrast with alternatives or provide 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 (readOnlyHint, idempotentHint) already indicate safe, non-destructive behavior. The description adds value by detailing the return format (verdict, structured form, actual value with citation, delta) and noting it replaces multiple sequential calls. No contradictions.

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

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

The description is moderately long but front-loaded with trigger phrases and a clear purpose. Every sentence contributes useful information without redundancy. Could be slightly more concise, but 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 one parameter, no output schema, and informative annotations, the description covers the tool's purpose, inputs, outputs, and usage context adequately. It lacks mention of rate limits or error handling, but overall is complete for an agent to 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 covers the single claim parameter with a description. The tool description enriches this by providing examples of valid claims and clarifying the natural-language nature, adding meaning 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 it verifies natural-language claims against authoritative sources, with specific trigger phrases and scope (company-financial claims). It is well-defined but does not explicitly differentiate from sibling tools.

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

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

The description explicitly says to use when checking factual correctness of a user's claim. It provides context about supported claim types (company-financial) but does not explicitly list when not to use or alternative tools.

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