Scb Se

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint. The description adds value by disclosing the default model cost (free), the need for a BYO key for Anthropic, and the return format. 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 concise sentences. The first sentence states the core purpose and output, the second details model options and cost, and the third lists use cases. No filler, front-loaded with essential information.

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

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

Given the absence of an output schema, the description adequately covers return format (per-model fields + combined view) and optional parameters. It could mention authentication requirements more explicitly, but the openWorldHint and _apiKey parameter suffice.

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 meaningful context beyond schema: it specifies the default model, the cost implication of _apiKey, and the purpose of 'context'. This enhances understanding of parameter usage.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility. It distinguishes itself from siblings by specifying the scoring mechanism and model options, and it uses precise verbs like 'probe' and 'score visibility'.

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 for when to use the tool (e.g., 'AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to use it (default model, optional API key). However, it does not explicitly state when not to use it or compare it to similar siblings like scan_competitor_ai_presence.

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 non-destructive. The description adds context about the return format (structured answer with citation URIs) and performance characteristics (one fast call, works on every tier). 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 longer than average but every sentence adds value. It is front-loaded with a strong recommendation, then provides usage guidance, examples, and alternatives. It could be slightly more concise, but no sentences are wasted.

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 router tool without an output schema, the description fully explains the return format (structured answer with citation URIs), the scope of sources, and when to use alternatives. It leaves no major gaps for an agent to guess.

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 parameters. The description mentions the primary input 'question' and lists aliases, but adds no new semantic meaning beyond what the schema provides. The examples in the schema and description are helpful but the description does not elevate the parameter understanding.

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

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

The description clearly states the tool routes questions to the appropriate tools/sources and returns structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns'. It distinguishes from siblings by naming alternatives 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 states to prefer this over web search for many domains, provides examples of queries, and clearly explains when to step up to other tools (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also mentions it works on every tier.

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?

Describes behavioral traits beyond annotations: extracts answer only from tool result, returns structured response with answer, evidence, confidence, source, fetched_at, and explicit refusal reasons on failure. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the key purpose. Each sentence provides essential information, though it is somewhat dense. Could be slightly trimmed without losing 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?

The description is comprehensive: covers purpose, usage guidelines, behavior, output format, failure modes, and cost. No output schema is needed because the description fully specifies the 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 description coverage is 100%, so the schema already documents all parameters. The description does not add significant meaning beyond the schema, other than clarifying that multiple parameters are aliases for the question. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the routing and extraction process, and distinguishes it from the sibling 'ask_pipeworx' by emphasizing that it only uses the tool result to extract answers, preventing hallucination.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra cost.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: fan-out process, resolver contract with confidence levels, parent_event extraction, news field fallback mechanisms, safety short-circuits for low-confidence and closed markets, spread illiquidity warnings, and resolution-rule risk. 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 informative but quite long. It uses headers and examples to structure content, starting with a clear summary. However, some sections are verbose (e.g., resolution-rule risk paragraph could be condensed). Front-loaded key info, but overall could be 20-30% shorter without losing meaning.

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

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

Given the tool's complexity (3 params, no output schema), the description covers response shapes, error states, safety mechanisms, and edge cases comprehensively. It explains resolver confidence, parent events, news fallbacks, and resolution rules, ensuring an AI agent can handle a wide range of scenarios.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value beyond the schema by explaining the market parameter's input formats (slug, URL, question text), the depth parameter's behavior, and the include_raw parameter's impact on response size. It also provides examples and default behaviors.

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 input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes itself from siblings like 'ask_pipeworx' and 'polymarket_edges' by focusing on a single bet with a specific fan-out process.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples and category-specific fan-outs. It does not mention alternatives or exclusions, but the context is clear enough that an AI agent can infer 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 destructiveHint. Description adds substantial context: specific financial metrics from SEC EDGAR/XBRL, handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

Description is dense with information but front-loads purpose and examples. It avoids redundancy and each sentence adds value. Slightly verbose due to examples, but overall efficiently communicates key points.

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 absence of an output schema, the description adequately explains return values (paired data with citation URIs, sorted results). It covers the two entity types with specific metrics, sorting behavior, and data sources. Minor gaps: doesn't specify exact output format or pagination.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning for 'type' (explains what data each type pulls) and 'values' (gives examples and constraints like tickers/CIKs for company, names for drug). It also clarifies the purpose of each parameter in the tool'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?

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with illustrative examples like 'Compare X and Y' and 'X vs Y'. It distinguishes from siblings by noting it replaces 8-15 sequential lookups, making the tool's unique role 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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. It also explains the data pulled for each entity type, though it doesn't explicitly 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?

Description adds substantial context beyond annotations: 'returns a findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[] for facets the data couldn't answer (never invented)', 'Expect 15-60s', and 'this is NOT open-web search'. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and complemented.

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 long (nearly 200 words) but well-structured: begins with critical account requirement and fallback, then explains functionality, then use cases and limitations. Each sentence adds value; no redundant filler. Front-loading of key caveats is good. Slight deduction for length, but justified given tool 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 having no output schema, the description fully explains return format (findings packet with evidence, confidence, source, citation, gaps[]). Covers parameter details, use cases, limitations (empty gaps for topics not in structured catalog), expected latency, and authentication. Completely adequate for an agent to decide when and how to invoke.

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

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

Schema coverage is 100% but description adds meaning: explains depth enum values ('quick=3, standard=5 (default), thorough=8 (paid plans)') and clarifies that question is 'broad/multi-part is fine — decomposition is the point'. Adds value beyond 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 states 'grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and 'decomposes your question into focused facets, routes each to the right one of 4,482 tools IN PARALLEL'. It clearly distinguishes from siblings like ask_pipeworx and covers the tool's unique decomposition and parallel processing capability.

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 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes 'If you are not signed in, use ask_pipeworx instead' and that depth 'thorough' needs a paid plan. 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This adds value beyond annotations but does not contradict them.

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

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

The description is front-loaded with the core purpose, followed by a list of data sources, then return details and usage guidance. Every sentence adds value, though it is slightly long at 7 sentences. 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?

Given the complexity (6 parameters, no output schema), the description fully explains what the tool returns (top-N tools with full schemas and examples), when to use it (first step for discovery), and its role among 29 siblings. It covers all necessary context for an AI 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 description coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'query' accepts natural language and lists aliases (task, q, description, search). It also provides concrete examples like 'analyze housing market trends'. This compensates for the multiple 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's purpose: 'Find tools by describing the data or task.' It lists specific data sources (SEC filings, FDA drugs, etc.) and distinguishes this tool from siblings (none are for discovery). It provides a strong, specific verb+resource combination.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also gives examples of when to use (browse, search, look up). While it does not state when not to use, the guidance is clear and actionable.

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

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

Annotations already show readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing parallel execution, sources fanned out, soft-fail for patents, fallback for news, and specific return fields, far exceeding annotation-provided hints.

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 lengthy but packed with essential information, starting with examples and then detailing outputs. Some redundancy could be trimmed, but it remains well-structured 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 the tool's complexity (multiple sources, multiple return fields) and no output schema, the description thoroughly covers all return fields and even notes API constraints (patent sunset). It is complete for an agent to understand 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 coverage is 100% with descriptions for both parameters. The description adds context about value format (zero-padded CIK) and unsupported names, but schema already covers basic usage, so a 4 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 provides a 'full cross-source profile of a US public company in ONE parallel call' with many example queries. It distinguishes itself from siblings like resolve_entity by specifying that it does not support names.

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 chaining single-pack...lookups when the user asks for a holistic view' and when not to use: 'names not supported — use resolve_entity first if you only have a name.'

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so description adds the context of clearing sensitive data. This is useful beyond annotations but doesn't contradict 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?

Three sentences, no fluff. First sentence defines purpose, second gives usage guidelines, third mentions siblings. 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?

For a simple delete tool with one parameter and no output schema, the description combined with annotations provides complete context. It covers purpose, when to use, and relationships 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 clear description 'Memory key to delete.' Description does not add extra parameter details beyond 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?

Description clearly states 'Delete a previously stored memory by key,' specifying the verb and resource. It distinguishes from siblings like 'remember' and 'recall' by mentioning 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?

Explicitly says when to use: when context is stale, task done, or to clear sensitive data. Also suggests pairing with remember and recall, indicating proper 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe read-only operation. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This provides transparency beyond what annotations convey, though it could mention limits like URL validity.

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

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

The description is approximately 60 words in a single, well-structured paragraph. It front-loads the primary action, then explains the process and output, and concludes with explicit use cases. 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?

Given the tool's low complexity (2 params, no output schema, clear annotations), the description covers purpose, process, output format ('single text blob ready to drop at site-root/llms.txt'), and use cases. It lacks error handling details, but for a read-only, idempotent tool, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description's parameter explanations ('URL of the site to summarize' and 'Maximum number of link entries to include (default 25, max 50)') mostly repeat the schema descriptions without adding new semantics. No contradiction or missing nuance.

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 specific action: 'Generate a production-ready llms.txt file for any URL so AI crawlers... can index the site cleanly.' It uses a specific verb (generate) and resource (llms.txt file), and distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence which have different focuses.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' While it doesn't list when not to use it or mention alternatives among siblings, the context is sufficient for most scenarios.

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

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

Annotations already disclose readOnlyHint, idempotentHint, and destructiveHint. Description adds return field details but doesn't extend beyond annotation safety profile. Adequate but not exceptional.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every word earns its place.

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

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

For a simple tool with one optional boolean parameter and no output schema, the description covers return fields, usage context, and is fully sufficient for caller 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% for the single parameter. 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Could be improved by mentioning when not to use, but offers clear 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?

Despite annotations having no hints, the description adds rich behavioral info: rate-limited to 5 per identifier per day, free, doesn't count against quota, daily digest reading. 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?

Concise and well-structured. Four sentences cover purpose, usage scenarios, behavioral details, and constraints. Front-loaded with the main action. No wasted words.

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

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

For a feedback submission tool, the description is fully complete. It covers all necessary aspects: when to use, what to include, behavior (rate limits, quota), and how feedback is processed. No output schema needed.

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

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

Schema coverage is 100%, but the description adds significant value: explains each type in context (e.g., 'bug = something broke or returned wrong data'), provides guidance on writing the message (be specific, 1-2 sentences, 2000 chars max), and describes the optional context object.

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: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by focusing on feedback rather than queries or actions.

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

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

Explicitly tells when to use: for bugs, feature requests, data gaps, praise. Provides when-not-to-use: don't paste end-user prompts. Mentions rate limits and free usage, giving clear context for 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 readOnly, idempotent, non-destructive. Description adds value by noting self-aggregation from CF analytics, no PII, and caching (5min-1h). No contradiction.

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

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

Four sentences, front-loaded with purpose, followed by use cases and behavioral details. Efficient with no wasted words, though slightly verbose in the use cases list.

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 input schema and no output schema, the description adequately covers return shape (top tools, packs, volume) and caching. Missing details about pagination/limits, but not critical for this tool.

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

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

Schema coverage is 100% with a single parameter (window). Description adds context on how different windows surface hot vs. steady-state demand, beyond the schema's enum 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 trending data (top tools, packs, call volume) over a recent window, and distinguishes it from siblings by specifying it's about what other agents are calling.

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

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

Explicitly lists three concrete use cases (discovering hot data, confirming canonical tools, aligning use cases). Does not include when-not-to-use or alternative tools, 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals internal logic: Jaccard similarity threshold (0.30), partition filter (placeholders >20% fraction return null), and fill check using live CLOB depth. It explains when not to trade (realizable_edge_pp ≤ 0), which is critical 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?

The description is well-structured with clear sections (REQUIRES, event mode, topic mode, fill check) and front-loaded with the key requirement. However, it is quite lengthy; while informative, a slightly more concise version could improve readability without losing essential details.

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

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

Even without an output schema, the description defines the response structure (opportunities[], partition_check, fill_check) and details key fields (gap_pp, suggested_trade, etc.). It covers edge cases (skipped_low_similarity, placeholders_filtered, thin_legs) and references sibling tools, making the tool's behavior fully transparent.

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 description adds significant meaning beyond the input schema: explains that event accepts full URLs, topic seeds a cross-event scan with behavioral details (Jaccard similarity, partition filter). With 100% schema coverage, it goes far beyond the baseline by providing concrete examples and operational constraints.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) with explicit explanations, making it easy for an agent to understand what the tool does.

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: recommends event mode for a specific market, topic for cross-event scanning, and warns that calling with no arguments fails. It also references the sibling tool polymarket_fill_risk for custom sizing, aiding correct 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?

The description adds significant behavioral context beyond annotations: explains the three model families in detail, caching at KV level, diagnostics for empty segments, edge fields, and tradeable-edge filters. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so description enhances understanding.

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

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

The description is very detailed and structured but verbose. While every sentence adds value, it could be more concise. It is front-loaded with purpose but later includes extensive model details that might exceed typical description 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 high complexity (9 parameters, no output schema), the description thoroughly explains the response top-level structure, each opportunity's fields, caching behavior, knob effects, and diagnostic information. It is complete for an agent to understand the tool's behavior and return values.

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

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

Schema coverage is 100% with good descriptions. The description adds valuable parameter use context, such as how min_kelly skips partition arbs by design and how min_partition_leg_kelly applies to per-leg Kelly. 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 Polymarket markets for edges where Pipeworx data disagrees with market price. It specifies returning opportunities in three segments and distinguishes from siblings by emphasizing 'what should I bet on today' and avoiding paging through hundreds of markets.

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 discovering betting opportunities and explains knobs like min_liquidity and max_spread_pp. However, it does not explicitly state when to avoid using this tool or suggest alternatives among siblings like bet_research or polymarket_arbitrage.

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

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

The description extensively discloses behavior beyond annotations: detailed response structure (tracked, expired, snapshot_dates), limit information (60-day TTL, non-intraday decay), and data gaps. No contradiction with readOnlyHint.

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

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

The description is front-loaded with purpose, followed by structured argument and response details, and ends with limits. Every sentence adds value without redundancy, achieving high information density efficiently.

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 fully details the complex nested response (tracked, expired, snapshot_dates) and limitations. It provides all necessary context for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, so description adds minimal extra: it repeats defaults and options already in schema, with only slight additional context (e.g., 'max 30' is implied by schema's clamp). Adequate but not significantly enhanced.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical temporal analysis rather than current edges.

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 implicitly guides the agent to use this tool when temporal edge analysis is needed, contrasting a fresh wide edge with an old one. Explicit when-not or alternative statements are missing, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description goes beyond by detailing the walking of the order-book ladder, specific returned fields (top_of_book, vwap_fill_price, etc.), and risks like forced directional risk from partial fills. It explicitly states that theoretical overround on thin books is not capturable, enhancing 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?

The description is long but well-structured with clear mode sections and bullet-like lists of return fields. Information density is high and every sentence contributes value. While slightly verbose, it avoids redundancy and front-loads the core purpose. A minor deduction for length, still very 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 enumerating all return fields for both modes (single-market: top_of_book, vwap_fill_price, etc.; basket: theoretical_sum, realizable_sum, profit_usd, forced_directional_risk). It also explains the risk of partial fills and thin books, making the tool's behavior and outputs fully understandable without needing 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?

Despite 100% schema description coverage, the description adds significant meaning: explains size_usd semantics differ per mode (max spend vs target proceeds vs settlement notional), default side logic in basket mode ('auto — sell if partition sum > 1, buy if < 1'), and clarifies that market/event are mutually exclusive. 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?

Clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. Differentiates two modes (single-market and basket) and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their 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?

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 required parameters (market or event), default values, and warns about thin books and partial fills converting arbs into directional positions, effectively telling when and when not to use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: compatibility_warning conditions, temporal_alignment, skipped cross-types, and limitations of the macro shortcuts.

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

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

The description is dense but every sentence adds value. It is front-loaded with the main purpose and structured with clear sections. Slightly lengthy but appropriate 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 fully explains response fields and safety indicators. Given 3 parameters and complex behavior, it covers all necessary context.

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

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

Schema coverage is 100%; description adds meaning by explaining the two modes, listing all topic shortcuts, and providing examples. The explicit parameters are clarified with real 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes and distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explicitly describes when to use (real signal when bet shapes equivalent) and when not (compatibility_warning cases). Provides mode selection guidance and notes that most pre-mapped topics return warnings today.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the body is a PxWeb query object, which provides some additional context, but overall does not significantly enhance behavioral understanding.

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

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

The description is very concise at two sentences, front-loading the main purpose. However, it is so brief that it sacrifices completeness, making it slightly less 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 complexity of a PxWeb query with nested objects and an output schema, the description is inadequate. It does not explain the role of the path parameter, the structure of the body, or how to construct queries, leaving significant gaps 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?

Only 50% of parameters have descriptions in the schema (body has a description, path does not). The description adds minimal value by stating 'body is a PxWeb query object', but it does not compensate for the lack of documentation for the path parameter or explain the body structure beyond what is 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?

The description states it pulls data from a table, which is a clear verb+resource. However, it does not differentiate from sibling tools like table_meta, so it lacks sibling distinction.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., table_meta). It simply implies usage by stating the purpose without any when-not or 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavior: scoping to user identifier (anonymous IP, BYO key hash, or account ID). 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, all essential. Front-loaded with the main action, followed by usage context and pairing. 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?

The description covers purpose, usage, scoping, and pairing. However, it does not mention the return format (value or list of keys). Given no output schema, this is a minor gap, but overall adequate for a simple retrieval tool.

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

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

Schema coverage is 100% with description for the 'key' parameter. The description adds meaning by explaining that omitting the key lists all keys, which is a crucial usage nuance that the schema does not explicitly convey.

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 ('retrieve', 'list') and resource ('value previously saved via remember', 'all saved keys'). It distinguishes from siblings by naming 'remember' and 'forget' and gives concrete examples (ticker, address, notes).

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 states when to use the tool ('to look up context stored earlier, without re-deriving from scratch') and how it pairs with remember/forget. It does not explicitly state when not to use it, but the context is clear enough for an agent.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds crucial behavioral details: the returned fields (source, citation_uri, raw payload), the effect of mark_read on future calls, and the availability of the same feed via an HTTP endpoint. This goes well beyond what annotations provide.

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

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

The description is concise at five sentences, with the main purpose and key fields in the first sentence. Every sentence adds value without repetition or irrelevant detail.

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 is provided, but the description thoroughly explains return values (source, citation_uri, raw payload). It covers all five parameters, filtering, pagination via limit, and mark_read semantics. The alternative endpoint is also mentioned, making the tool fully self-contained.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds practical context: examples for type ('sec_8k'), explanation that since filters by fired_at >= timestamp, and that mark_read flags events as read to deduplicate subsequent calls. This enriches the schema explanations.

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 pulls fired events from a subscription feed, returns most recent alerts, and lists key fields like source and citation_uri. It distinguishes itself from sibling tools by mentioning the feed and an alternative access method, 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 provides clear context: 'Polls work fine' indicates suitability for polling, and it mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool, but the guidance is still strong.

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

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

Annotations declare readOnlyHint=true etc. Description adds fan-out logic, fallback (GDELT→GNews), sunset caveat (PatentsView), and return structure (changes grouped by source, citation URIs).

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 dense paragraph, front-loaded with examples, contains all necessary info. Could be more structured but no wasted sentences.

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

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

Given complexity (multi-source, fallback, sunset) and no output schema, description is comprehensive. Covers sources, parameter formats, return structure. Minor missing specifics on rate limits.

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

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

Schema coverage 100% but description adds value: explains 'type' only supports company, 'value' accepts ticker or CIK, 'since' accepts relative shorthand with 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 provides a change feed for a company, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It includes example queries and distinguishes from sibling 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?

Explicitly suggests using entity_profile for static profile instead, and provides typical monitoring window for 'since' parameter. Lacks explicit when-not-to-use but adequate.

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 provide idempotentHint=true, but description adds key behavioral details: scoped by identifier, persistence for authenticated users vs 24-hour for anonymous sessions. Does not explicitly confirm overwrite behavior, but aggregate is strong.

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, all essential. Front-loaded with core purpose and usage guidelines. 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?

Covers purpose, when to use, lifecycle (persistence), scoping, and pairing with recall/forget. No output schema needed for a write operation. Fully informative for an AI agent.

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

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

Schema already has 100% coverage with clear descriptions for key and value. Description adds minimal value beyond schema, just stating 'stored as a key-value pair' and giving context about scoping, but not detailed parameter syntax.

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 states 'Save data the agent will need to reuse later' with specific verb and resource. Clearly distinguishes from sibling tools recall and forget, which are mentioned for 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?

Explicitly says when to use ('when you discover something worth carrying forward') and mentions alternative tools (recall, forget) for retrieval and deletion. Provides concrete examples like resolved ticker or user preference.

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 idempotent, read-only behavior. The description adds rich detail: internal cascading through multiple endpoints, auto-disambiguation for companies, and exact return values with citation URIs.

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: starts with query examples, then usage instruction, then per-type details. Every sentence adds value, no wasted words.

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

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

No output schema, but description compensates by detailing return fields for each type and mentioning internal cascading. Could note error handling or uniqueness, but sufficient for the task.

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

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

Schema coverage is 100% with descriptions. The description adds examples and clarifies return types per parameter value, going beyond the enum and description 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?

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with explicit examples and supported types. It distinguishes from sibling tools by focusing on ID lookup from names.

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 'Use FIRST whenever you have a name but need an ID.' This sets clear context, though it doesn't explicitly contrast with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it 'probes each entity with ai_visibility_check', explaining internal operation, and notes ranking by score and return format. There is 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 two sentences plus a brief example, front-loaded with the main action. It is concise and avoids unnecessary detail. No fluff, but could be slightly more structured with bullet points for readability. 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?

The tool has 4 parameters (1 required) and no output schema. The description covers the return format ('ranked list with score, confidence, signal density per entity'), which is sufficient. It also explains the internal use of ai_visibility_check. Complete for a comparative tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it explains that the first entity in the array is treated as 'subject' for narrative, and rest as competitors. It also clarifies that context disambiguates common names. This adds value.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare, rank, surface which is most/least recognized) and the resource (AI visibility across entities). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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?

Provides a clear use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This implies when to use it. It does not explicitly state alternatives or when not to use, but the sibling list includes ai_visibility_check for single-entity checks, offering indirect 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?

Description discloses behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeout. Annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and description adds valuable context about timing and failure modes.

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

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

The description is well-structured and front-loaded with the core purpose. It contains rich detail without redundant sentences. However, it is slightly verbose with parenthetical lists and could be tightened slightly for optimal 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?

Despite having no output schema, the description thoroughly explains the return structure (summary block with specific fields, per-advisory detail, links, alternative versions) and handles edge cases (partial failures). It provides complete context for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds semantic value: clarifies that scoped packages are accepted for 'package' and explains default behavior for 'version' (latest when omitted). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose as a composite check for deciding whether to add an npm package, combining data from deps.dev and bundlephobia. It distinguishes itself from siblings by being the only tool that performs this specific composite analysis.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem limitations (NPM only in v1) and suggests alternatives for other ecosystems (PyPI, Maven, etc.), which is helpful but could be more explicit about when not to use.

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

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

Annotations already indicate readOnly, idempotent, etc. Description adds rich detail: character offsets, similarity scores, embedding model (BGE-base-en), window size (500-char overlapping), token limit (200K chars), and truncation behavior with flagging. 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 usage, then technical details. Every sentence adds value with 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?

No output schema, but description explains return format ('top-N passages with character offsets and similarity scores'). Covers technical details, use case, and pairing with sibling tool. Complete and actionable for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds example queries and a brief note on text max length, but doesn't add significant meaning 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 clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It differentiates from sibling tools like ask_pipeworx_grounded by noting the pairing and use case.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. Description adds context about return structure (child nodes with names and table counts) and path constraint (sub-path under /ssd/), which is valuable beyond annotations.

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

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

Two sentences with no wasted words. Front-loaded with action and context, including an example and expected output.

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, full schema coverage, clear annotations, and a mention of return structure, the description is complete enough for the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by providing examples, clarifying default behavior (empty = root), and explaining usage pattern, thus exceeding baseline.

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

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

Clearly states action (browse), resource (SCB PxWeb subject tree), and behavior (drill down with sub-path, returns child nodes with names and table counts). Distinct from siblings as it is specific to statistical subject tree navigation.

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?

Implies usage via examples but does not explicitly state when to use this tool vs alternatives or provide exclusions. With many sibling tools, more guidance would help.

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

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

Discloses key behaviors beyond annotations: OAuth requirement, return of subscription id, delivery constraints (SMS cap, webhook auto-disable), and rate limits. No contradiction with annotations.

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

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

Front-loaded with core purpose and return value, then well-organized into types and delivery. Slightly lengthy but appropriate for complexity.

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

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

Covers return value, prerequisites, type details, and delivery options. Minor gap: only 3 of 5 types detailed in description; others only in schema. No output schema, but return is stated.

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 extra meaning: detailed examples for each type, parameter structures, and delivery channel nuances. Goes beyond 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 'Create a proactive monitoring subscription' with specific verb and resource, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and mentions delivery channels. Lacks explicit when-not-to-use or comparison to alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining the return format (category-bucketed example questions with exact tool+argument shape) and the behavior with/without the topic parameter. No contradictions.

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

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

The description is well-structured with the purpose upfront, but it is somewhat lengthy. However, almost every sentence adds value (e.g., listing topics, explaining use case). It 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 simplicity (1 optional parameter, no output schema), the description fully covers its purpose, context, usage guidelines, parameters, and expected output. It mentions return format and examples, making it complete for an AI agent.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema's 'Optional focus area' by listing the possible topic values and explaining that omitting it gives a cross-category spread. This fully compensates for any missing schema detail.

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

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

The description clearly identifies the tool as an onboarding entry point that returns example questions for Pipeworx. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes from siblings like 'discover_tools' by stating it's the 'first' tool to use when exploring capabilities.

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

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

The description explicitly states to 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear when-to-use guidance and mentioning alternatives (meta-tools). It also explains the no-argument default and the optional topic parameter.

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 and idempotent behavior; description adds context about fetching definitions and filter values, enhancing transparency about what the tool returns.

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

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

Two concise sentences, each adding value: first explains what it fetches, second explains why it's needed. 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 presence of an output schema and thorough annotations, the description fully covers the tool's purpose and prerequisites, making it 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 description adds meaning by explaining the path parameter identifies a SCB PxWeb table and providing an example format, going beyond the schema.

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

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

Description clearly states the tool fetches dimension definitions and valid filter values for a specific SCB PxWeb table, distinguishing it from sibling query_table by noting it is a prerequisite.

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 it is required before calling query_table to know which codes to pass, providing clear guidance on when to use it and its relation to an alternative 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?

Description adds valuable context beyond annotations: row is deactivated (not deleted) and historical events remain via 'recent_alerts'. Annotations indicate non-destructive, idempotent behavior, which aligns with description.

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

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

Two concise, front-loaded sentences with no wasted words. Every sentence provides essential information.

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

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

For a simple one-parameter tool with no output schema, description covers key behavioral aspects. Minor omission: no mention of error cases like missing or already canceled IDs.

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% description coverage for the single parameter 'id'. Description mentions 'by id' but adds no semantic detail beyond the schema's description.

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

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

Description clearly states action ('Cancel a subscription by id') and includes ownership enforcement and deactivation behavior, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Description specifies when to use (cancel subscription) and ownership constraint, but lacks explicit alternatives or when-not-to statements. Context from siblings implies 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 readOnly, openWorld, idempotent, and non-destructive. Description adds return format details (verdict categories, citation, delta) and explains it replaces multiple calls, providing full 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?

Description is detailed but every sentence adds value. Front-loaded with purpose and usage, followed by technical specifics. Slightly long but justified given the tool's complexity.

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

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

Considering no output schema, description fully explains return verdict types, structured form, citation, and delta. Also mentions underlying data sources (SEC EDGAR + XBRL), making it 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?

Single parameter 'claim' has 100% schema coverage with natural-language description. The description expands with concrete examples and context, adding meaning beyond schema.

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

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

Description clearly states the tool performs natural-language claim verification against authoritative sources, explicitly for company-financial claims. It lists example queries and distinguishes it as a consolidated replacement for multiple sequential calls.

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?

Directly states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies domain. Lacks explicit when-not-to-use but domain scope is clear.

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