Complex Portal

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

The description complements annotations by detailing the probing behavior, default model, cost implications for Anthropic, and the return structure. Annotations already indicate safe read-only behavior, so the description adds useful context without contradiction.

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

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

The description is extremely concise, with the main action and output in the first sentence, followed by key details and use cases. No unnecessary words or 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?

The description explains the output structure (per-model {score, confidence, signals, raw_response} + combined view) and use cases, compensating for the lack of an output schema. It could mention error handling or signals details, but overall it is complete enough for the tool's complexity.

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

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

Schema descriptions cover all parameters at 100%, so the tool description adds marginal value (e.g., naming the default model). The parameter explanations in the description largely mirror those in the schema, resulting in a baseline score.

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 visibility scoring. It uses specific verbs ('probe', 'score visibility') and distinguishes the tool from siblings by focusing on LLM knowledge about entities, which is unique among the listed sibling tools.

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

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

The description provides use-case scenarios (AI-marketing audits, brand checks, competitive monitoring) and explains the free vs. paid model options. However, it does not explicitly differentiate from related tools like ask_pipeworx or scan_competitor_ai_presence, leaving some ambiguity for selection.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining internal routing to 3,586 tools and citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. It efficiently lists domains and examples. Slightly verbose but well-organized and each sentence adds value.

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

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

For a complex meta-tool with many possible sources, the description is remarkably complete: it explains the routing mechanism, what kinds of questions to ask, and the output format (structured answers with citation URIs). The examples cover diverse use cases.

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 each alias. The description does not add additional parameter meaning beyond 'your question in natural language'. Since schema is comprehensive, 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 routes questions to a massive set of sources and returns structured data with citations. It specifies many domains (SEC filings, FDA data, etc.) and gives examples. However, it does not explicitly differentiate from sibling tools like 'ask_pipeworx_grounded' or 'discover_tools', though the unique routing behavior is implied.

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?

Strong guidance is provided: 'PREFER OVER WEB SEARCH' with a long list of suitable query types. Use cases and example queries are given. No explicit when-not-to-use or alternative tools are mentioned, but the description is clear enough for typical factual queries.

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 details beyond annotations: costs one extra LLM call, returns specific refusal reasons, and extracts only from tool result. 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, front-loaded, every sentence adds value. Two sentences cover purpose, behavior, use cases, and trade-offs.

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

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

Despite no output schema, description explains return format (fields) and refusal reasons. For a complex tool with 6 params, 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 coverage is 100%, so description doesn't need to add parameter info. 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 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It also distinguishes from ask_pipeworx.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'Prefer ask_pipeworx for casual lookups', providing clear when-to-use and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral context: fan-out examples, classifier categories, resolver contract, parent_event extractor, news fallback fields, safety short-circuits, liquidity warnings. Goes far 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?

Front-loaded with purpose and classifiers. Length is justified given complexity, but could be better organized (e.g., bullet points for fan-out examples and response shapes). Every sentence adds information; no waste.

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

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

Given the tool's complexity and absence of output schema, the description covers response structure, edge cases, safety mechanisms, and alternative resolution paths. It provides everything an agent needs to understand invocation and interpretation.

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 3 parameters. The description adds value by explaining default behavior for 'depth', summarizing 'include_raw' effects on response size, and providing examples for 'market' input. Baseline 3, elevated for added 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 tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question) and outputs (evidence packet + market-vs-model comparison). It distinguishes from siblings by detailing fan-out behavior and classifier categories not found in other tools.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Describes safety mechanisms like low-confidence resolution and closed market handling. Does not explicitly exclude non-bet queries, which is implied.

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 significant behavioral context: off-calendar fiscal years handled correctly, results sorted by primary metric, returns pipeworx:// citation URIs, and replaces 8-15 sequential lookups. No contradictions with annotations.

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

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

The description is informative but somewhat long, containing multiple example queries and details. It is front-loaded with examples but could be slightly more concise without losing 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?

No output schema exists, but the description briefly mentions return format (paired data + citation URIs, sorted by primary metric). Given the tool's complexity (two types, constraints, data sources), the description is sufficiently complete for an agent to understand inputs, outputs, and behavior.

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

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

Input schema covers both parameters with 100% description coverage. The description adds meaning beyond the schema by explaining the enumeration for 'type' (company vs. drug) and providing context for 'values' (tickers/CIKs for company, drug names for drug), including constraints and 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 explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, specifies data sources (SEC EDGAR for companies, FAERS for drugs) and metrics, and distinguishes it from sequential lookups, making its purpose very clear.

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 usage context with example queries and explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' While it doesn't explicitly list when not to use it or alternative tools, the guidance is strong enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full schemas with curated examples and can be called directly, which helps the agent understand behavior beyond annotations.

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

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

The description is well-structured: starts with purpose, then lists domains, then explains return value. It is slightly long but every sentence adds value, earning its place.

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

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

Given no output schema, the description thoroughly explains what is returned (top-N tools, names, descriptions, schemas, curated examples). Parameter count and sibling context are handled well, making the tool complete for an agent to use.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters beyond what the schema provides; it focuses on output and 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: 'Find tools by describing the data or task.' It lists specific domains and verbs like browse, search, look up, discover, distinguishing it from siblings like search_complexes or search_within.

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: 'Call this FIRST when you have many tools available and want to see the option set.' Also lists use cases (SEC filings, financials, etc.), making it clear when to invoke.

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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: single parallel call, fan out across sources, soft-fails on patents due to USPTO sunset, and fallback mechanisms (GDELT→GNews). 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 dense and well-structured with query examples at the start. It contains all necessary information without redundancies. While long, every sentence earns its place. Slight room for trimming but overall efficient.

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

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

The tool has 2 simple parameters and no output schema. The description comprehensively covers return values (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with sunset note, news via fallback, LEI). Complete for a profile tool given the constraints.

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 both parameters described. The description adds value by explaining the value parameter accepts ticker or zero-padded CIK, giving concrete examples, and clarifying that names are not supported. This is helpful beyond the schema's basic description.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company. It lists the sources (SEC, XBRL, USPTO, news, GLEIF) and the returned data fields. It distinguishes itself from the sibling tool 'resolve_entity' which is for name resolution, and from chaining individual lookups.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also instructs to use 'resolve_entity' first if only a name is available, and provides example queries for ticker or CIK input.

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 convey destructiveness and idempotency; description adds no extra behavioral context beyond aligning with annotations.

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

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

Two sentences, no wasted words, front-loaded with purpose.

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

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

Simple tool with one parameter and no output schema; description is sufficient for an AI agent to use correctly.

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

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

Single parameter 'key' is fully described in schema; description adds no additional meaning beyond what schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings (remember, recall).

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data' and mentions paired tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

Three sentences with no fluff: first states purpose, second describes process, third lists use cases. Front-loaded and efficient.

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

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

Given low complexity (2 params) and good annotations, the description covers output format and usage. Missing mention of error handling for invalid URLs, but overall complete.

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

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

Schema coverage is 100% with both parameters well-described. The description adds minimal extra meaning beyond the schema (e.g., url is 'site to summarize', max_links default 25 max 50). Baseline score of 3 is appropriate.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' and specifies the output format and use cases. It distinguishes the tool from siblings by focusing on AI crawler requirements, which is unique among the listed sibling tools.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. However, it does not include when NOT to use the tool or mention alternatives, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by detailing the returned data (participants, UniProt IDs, roles, stoichiometry, etc.) and noting it is 'Keyless' (no authentication required).

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

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

Two concise sentences with no wasted words. The purpose is front-loaded, and the content is efficiently packed 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 tool's simplicity (one parameter, no output schema), the description provides sufficient context: what is returned, how it relates to other databases, and that no key is needed. It lacks mention of error handling or non-existent accessions but is otherwise 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% with a clear description for the 'id' parameter. The description adds meaning by providing an example accession ('CPX-7762') and explaining the purpose, which goes beyond the schema's basic description.

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

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

The description clearly states the tool retrieves a single Complex Portal record by accession, provides an example accession, and distinguishes from siblings by noting it is 'keyless' and 'Complements UniProt/IntAct/STRING'.

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 retrieving a single record but does not explicitly state when to use it over siblings like search_complexes or when not to use it. The mention of complementing other databases provides some context but lacks direct comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields and focuses on active subscriptions, which is useful context beyond annotations. No contradictions.

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

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

Two sentences: first states the action and return fields, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose, return fields, and usage context. Annotations cover safety. Nothing missing.

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

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

The input schema covers 100% of parameters with a description for include_inactive. The tool description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

The description explicitly says to use this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for its use. It does not mention when not to use alternatives but implies it's for existing subscriptions.

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

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

Annotations are all false (no hints), so description bears full responsibility. It discloses rate limiting (5 per identifier per day), cost (free, no quota usage), and impact (read daily, affects roadmap). No contradictions with annotations because annotations are neutral.

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, each serving a distinct purpose: purpose, usage scenarios with actionable guidance, behavioral traits, and constraints. No redundancy or filler.

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

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

For a tool with 3 params (including nested object) and no output schema, the description covers all necessary aspects: when, how, constraints, and consequences. No gaps remain for an agent to use it correctly.

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

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

Schema covers 100% of parameters, so description's job is to add context. It does so by clarifying the 'type' enum with examples, and instructing that 'message' should not contain end-user prompts, which adds meaning 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 the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise. It uses specific verbs ('Tell', 'broken, missing, or needs to exist') and distinguishes from sibling tools which are all about retrieving or analyzing data, not providing feedback.

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

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

Explicitly specifies when to use each feedback type (bug, feature/data_gap, praise) and provides instructions on what to include (describe issue in terms of Pipeworx tools/packs, don't paste end-user prompt). This guidance is absent from any sibling tool.

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

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

Annotations already declare readOnlyHint and non-destructive behavior. The description adds valuable context: data source ('CF analytics-engine'), absence of PII, and caching behavior (5min-1h). No contradictions found.

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

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

The description is concise, with front-loaded purpose followed by bullet-pointed use cases. Every sentence provides meaningful information, with no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description is largely complete. It explains the output (top tools, packs, volume) and caching, though it could optionally mention output limits or sorting.

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

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

The schema covers the single parameter (window) with 100% coverage, and the description adds semantic meaning beyond the enum values: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description uses a specific verb ('Returns') and clearly identifies the resource: 'top tools, top packs, and total call volume'. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on trending usage metrics.

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

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

The description lists three explicit use cases for the tool (discovering hot data sources, confirming canonical choices, aligning use cases). It also explains the semantic difference between window lengths. However, it doesn't explicitly mention when to avoid this tool or compare it to similar siblings.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: required parameter conditions, specific algorithmic checks (monotonicity, partition-sum), semantic anchor thresholds, placeholder filtering, and response structure. No contradictions.

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

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

The description is detailed and well-structured, starting with a required-parameter condition, then explaining modes, followed by algorithmic details and response structure. Though slightly dense, 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?

Without an output schema, the description thoroughly explains the response structure (opportunities[] with fields and partition_check details) and failure cases (no args, low similarity, placeholder slugs). Combined with high schema coverage, the tool definition is complete and actionable.

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

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

Schema descriptions cover 100% of parameters, providing baseline at 3. The description adds extra value by explaining recommended usage, acceptance of full URLs, and the behavioral difference between event and topic modes, enhancing the schema's meaning.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes between event and topic modes. This is a specific verb+resource with clear differentiation from sibling tools.

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

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

The description provides clear guidelines on when to use each parameter mode (event recommended for specific market, topic for cross-event scanning) and that calling with no args fails. However, it does not compare the tool to sibling tools like polymarket_edges or polymarket_kalshi_spread, missing the opportunity to aid in cross-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?

Annotations indicate read-only, idempotent, non-destructive; description adds extensive behavioral context: caching at KV level (1h), segments, diagnostics, edge calculation with slippage and Kelly, and 24h-move warning. No contradictions.

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

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

Description is lengthy but well-structured with sections for model families, response top-level, and diagnostics. Each sentence adds information; however, some details (e.g., exact historical parameters for concentrated_longshot) could be abbreviated. Still, it's efficient for the tool's complexity.

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

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

Covers everything needed to use the tool correctly: response structure (by_segment, diagnostics), filters, caching, Fed bets exclusion. Without an output schema, description explains return fields (edge_pp_net, kelly_fraction, etc.) and diagnostics. Complete for a complex data-providing tool.

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

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

Schema coverage is 100% but description adds valuable context beyond schema: e.g., min_kelly explains 'skip opportunities too small to bet sensibly', slippage_pp notes typical 20-50bp, min_partition_leg_kelly explains why parent-level min_kelly doesn't apply. Each parameter's rationale and interaction are clarified.

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

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

Clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly for 'what should I bet on today'. Distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx's edge models.

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

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

Provides explicit usage context: 'Built for agents to discover opportunities without paging hundreds of markets'. Mentions Fed bets are excluded (fed_note) and tradeable-edge knobs (min_liquidity, max_spread_pp) guide when edges are realizable. Does not explicitly name alternative tools but context implies when not to use this.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond by detailing compatibility_warning scenarios, temporal_alignment, skipped_cross_type/subtype counters, and the fact that real spreads are rarer than shortcuts suggest. No contradictions with annotations.

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

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

The description is relatively long but well-structured with clear sections (overall, modes, response, safety fields). It is front-loaded and every sentence adds useful information. Slightly verbose, but not wasteful.

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, yet the description explains the response structure in detail (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, etc.). It covers all aspects needed for the agent to understand what the tool returns and how to interpret it.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds value by explaining the topic list and the override behavior of explicit parameters, providing examples. This extra context justifies a 4.

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

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

The description clearly states that this tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by being the only spread tool, and explains two modes of operation (topic shortcuts and explicit event identifiers).

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

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

The description explains when to use topic shortcuts versus explicit pairing, and warns that most pre-mapped topics currently return compatibility warnings. It could be slightly more explicit about when not to use the tool (e.g., when events are not comparable), but it provides adequate 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, indicating safe read-only behavior. The description adds minimal new behavioral detail beyond scoping and pairing, so it's adequate but not significantly additive.

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

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

The description is four sentences, front-loaded with the main action, and each sentence adds necessary context 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?

No output schema exists, but the description implies return values. It could specify the format more clearly, but for a simple retrieval tool with a clear parameter schema, it is mostly 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% with a parameter description, but the description explains the behavior when key is omitted (list all keys) vs. provided (retrieve value), adding value beyond the schema.

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

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

The description clearly states the verb 'Retrieve' or 'list' and the resource 'saved keys/values', and distinguishes from sibling tools 'remember' and 'forget'.

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

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

The description provides explicit guidance on when to use the tool (look up previously stored context) and gives concrete examples (target ticker, address, research notes). It also explains scoping and pairing with remember/forget.

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

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

Description states that setting mark_read:true flags events as read, implying a state change, which contradicts annotation readOnlyHint=true. This is a clear annotation 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?

Five sentences, each informative and front-loaded with the main action. No redundant or unnecessary information. Every sentence contributes to understanding the tool's purpose and usage.

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 the contradiction, the description provides comprehensive context: purpose, parameters with examples, return fields, side effect of mark_read, suitability for polling, and alternative access method. No output schema exists, so the description adequately compensates.

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

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

Schema descriptions already cover all parameters (100% coverage). Description adds value by explaining mark_read behavior ('so the next call only shows newer ones') and providing an example for type filtering. This goes beyond 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?

Description clearly states it pulls fired events from subscription feed, specifies return fields (source, citation_uri, raw payload), and contrasts with a direct HTTP endpoint. It is specific and resource-oriented, distinguishing it from siblings by focusing on alert retrieval.

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

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

Explicitly mentions polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, guiding usage context. However, it does not explicitly compare to sibling tools or state when not 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?

Beyond annotations (readOnlyHint, etc.), the description details fan-out to three sources, GDELT preferred with GNews fallback, USPTO soft-fail, and return structure. No contradictions with annotations.

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

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

Description is somewhat long but well-structured with front-loaded example queries. Every sentence adds value; however, it could be slightly more concise.

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

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

For a complex tool with three sources, fallback, and parameter nuances, the description is comprehensive. No output schema, but return structure is summarized (changes[], total_changes, citations).

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 with good parameter descriptions. The tool description adds value by explaining relative shorthand for 'since' (', '30d', '3m', '1y') and default suggestion (use '30d' or '1m'). Minor addition.

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

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

The description starts with example queries clearly indicating the tool's purpose: a change feed for a company. It explicitly distinguishes from sibling 'entity_profile' by stating 'Use entity_profile instead when you want the static profile...'.

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

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

Provides explicit 'when to use' examples and a clear alternative ('entity_profile'). Also explains fallback behavior for news sources and soft-fail for patents, guiding proper usage.

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

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

Adds behavioral details beyond annotations: scoped by identifier, persistent for auth, 24-hour for anonymous. Complements idempotentHint by implying overwrite behavior. 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?

Five sentences, no fluff, front-loaded with purpose. Every sentence adds meaningful context: usage, scope, persistence, and sibling tools.

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?

Fully covers storage mechanism, scope, persistence durations, and relationship to recall/forget. No gaps for a simple 2-param tool without output schema.

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

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

Schema covers both params with descriptions. Description adds concrete examples (ticker, address, preference) that help an agent choose appropriate keys and values, enhancing semantics beyond schema.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by mentioning them as pairing tools.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on persistence per user type. Lacks explicit 'when not to use' but implies alternatives via sibling references.

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 significant behavioral context: it cascades through several lookup endpoints internally, and specifies exact return fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). 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 moderately lengthy but efficiently structured. It leads with relatable query examples, then explains types and return values. Every sentence adds value, though some internal repetition (e.g., repeated citation format) could be trimmed slightly.

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

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

With no output schema, the description fully covers return values for each type and explains the internal cascading mechanism. Given the tool's complexity (multiple entity types, multiple endpoints), the description is comprehensive and leaves no ambiguity about what the tool does and returns.

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

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

Schema coverage is 100% (both parameters documented). The description adds meaning beyond schema: for 'type', it gives enum values with examples; for 'value', it provides input examples and disambiguation details (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company). This enhances usability.

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 specific verb phrases like 'resolve' and 'look up'. It distinguishes itself from siblings by noting it replaces 2-3 manual lookups and provides specific examples for each supported type (company, drug).

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to invoke it. While alternatives are not explicitly listed, the context of sibling tools (e.g., compare_entities, entity_profile) implies when not to use it. The description also details supported types and input formats.

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, non-destructive. Description adds detail: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns ranked list with score, confidence, signal density. No contradiction.

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

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

Two sentences: first states purpose, second explains mechanism and use case. Every sentence adds value, no filler. Front-loaded.

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

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

Given no output schema, description explains return format (ranked list with score, confidence, signal density). Annotations cover read-only/idempotent. All parameters documented with coverage. Use case fully explained. Complete for this tool's complexity.

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

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

Schema coverage is 100% (baseline 3). Description adds practical usage context: entities array size 2-8, models default to workers-ai, _apiKey needed only if anthropic in models, context helps disambiguate common names. Adds value beyond schema.

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

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

Description clearly states verb 'compare' and resource 'AI visibility across multiple entities side-by-side'. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic) by focusing on competitive AI audits.

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 'useful for competitive AI-marketing audits' and gives an example question. Implicitly excludes single-entity checks (handled by ai_visibility_check) but does not explicitly list alternatives or when-not-to-use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds beyond annotations: mentions degradation gracefully on partial failures, first measurement can take 5-30s, sources_failed list, and specific return fields. Provides rich behavioral context.

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

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

Description is front-loaded with the core purpose, followed by structured details on services, usage, scope, and behavior. Every sentence adds value without fluff. Efficient and well-organized.

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

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

Despite no output schema, description fully enumerates return fields (summary block, per-advisory detail, links, alternatives). Also covers edge cases like partial failures and timing. Complete for a composite external API 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. Description adds that scoped packages are accepted for 'package' and that 'version' defaults to latest. This extra context moves it to 4.

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

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

The description explicitly states it is a composite check for npm packages, fans out across deps.dev and bundlephobia, and lists what it returns. It clearly distinguishes its purpose from sibling tools like 'scan_competitor_ai_presence'.

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

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

Provides explicit when-to-use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states when not to use: 'NPM ecosystem only in v1', and gives alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the tool is keyless, returns specific fields (accession, name, description, organism), and accesses a manually curated database. No contradictions with annotations.

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

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

The description is two sentences long, clearly front-loaded with the core purpose and followed by key context (curated, keyless, complements). Every sentence serves a purpose without 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 search tool with no output schema, the description adequately explains what returns (accession, name, description, organism). It also notes the database is curated and stable. Parameters are fully documented in schema. No gaps remain.

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

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

Schema coverage is 100%, so the description is not required to add param details. It provides examples of valid queries, reinforcing the schema's descriptions but not adding new semantic meaning beyond what the schema already provides for 'query' and 'limit'.

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

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

Description clearly states the tool searches the EBI Complex Portal for protein complexes by name, gene, GO term, or biological process, with specific examples. It also mentions the return fields (accession, name, description, organism) and distinguishes itself by noting it complements UniProt/IntAct/STRING, which differentiates from sibling tools like get_complex or entity_profile.

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

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

The description provides clear context on when to use the tool, listing acceptable query types (protein name, gene, GO term, biological process) and examples. It states it is 'keyless,' indicating no authentication needed. However, it does not explicitly state when NOT to use it or offer direct alternatives among siblings, though 'complements' implies differentiation.

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

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

Goes well beyond annotations: details the embedding model (BGE-base-en), chunking (500-char overlapping windows), similarity metric (cosine), character cap (200K) with truncation flagging, and output format (passages with offsets). 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 at ~5 sentences, front-loading the primary use case and key differentiator. Every sentence provides value: examples, technical details, and usage pairing. 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?

For a moderately complex tool with 3 parameters and no output schema, the description covers purpose, usage, behavioral details, parameter semantics, and output format (passages with offsets and scores). No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the algorithm and usage, and provides example queries for the 'query' parameter. However, the parameter descriptions in the schema are already detailed, so the additional semantics are modest.

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 a specific verb ('search inside a fetched record') and resource ('record text'), with concrete examples (SEC 10-K, article). It differentiates from siblings like 'ask_pipeworx_grounded' by emphasizing that it saves context and returns passages with offsets.

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

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

Explicitly advises use 'when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded'. While it doesn't explicitly state when not to use, the guidance is clear and practical.

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 idempotency and non-destructiveness. The description adds behavioral details: returns a new subscription ID, requires OAuth, feed is always on, optional email delivery. No contradictions with annotations. Minor omission: no mention of SMS despite schema presence.

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 (6 sentences), well-structured, and front-loaded with the core purpose. Every sentence adds value, and the example is clear.

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

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

Given the rich input schema and annotations, the description is largely complete. It explains the return value (subscription ID) and the feed delivery mechanism. It does not cover error cases or the SMS channel beyond the schema, but overall adequacy is high.

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 each parameter is documented. The description adds value with concrete examples for 'params' (ticker, items) and explains defaults. However, it only mentions email delivery, while the schema also includes SMS with its own description (including cap).

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the support for type 'sec_8k' and provides concrete examples (e.g., items:["5.02"]). This distinguishes it 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?

The description includes important usage context: requires a Pipeworx OAuth account, and anonymous/BYO cannot persist subscriptions. It also mentions delivery channels and how to pull alerts. However, it does not explicitly contrast with other tools or state when not to use it.

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

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

Adds behavioral context beyond annotations: row is deactivated not deleted, historical events remain via recent_alerts. Consistent with destructiveHint=false and idempotentHint=true.

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

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

Two sentences, front-loaded with main action, constraints, and behavior. 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?

Complete for a simple tool with one parameter, clear annotations, and no output schema. Covers action, ownership, deactivation behavior, and connection to recent_alerts.

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

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

Schema coverage 100% with clear parameter description. Description adds no extra semantic value for the parameter, baseline score is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource, distinguishing from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement (can only cancel own subscriptions), providing clear usage condition. Lacks explicit alternatives but context from siblings is available.

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 valuable behavioral context: it reveals the tool replaces multiple sequential calls, details the return format (verdict types, structured form, citation, delta), and names the data source (SEC EDGAR + XBRL). This significantly enriches the agent's understanding of what happens during invocation, going well beyond the annotations.

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

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

The description is a single, information-dense paragraph. It starts with attention-grabbing trigger phrases, then covers purpose, scope, return values, and efficiency gains. While concise, it could be slightly restructured for easier scanning (e.g., bullet points for return types). No unnecessary sentences, and every part earns its place.

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

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

Given the tool's simplicity (single parameter, no output schema, rich annotations), the description is remarkably complete. It covers the domain, trigger examples, source, return format (including verdict types and citation), and even the efficiency improvement. The only minor gap is not explicitly stating unsupported claims fallback, but 'unsupported' verdict is listed. This is sufficient for an AI agent to understand and use the tool effectively.

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

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

With 100% schema description coverage for the single parameter 'claim,' the schema already documents the natural-language string with examples. The description reiterates the examples but does not add new semantic meaning beyond what's in the schema. A baseline score of 3 is appropriate since the schema carries the weight.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources for company-financial claims. It explicitly lists trigger phrases like 'fact check' and 'verify the claim,' making the purpose unmistakable. It differentiates from siblings by specifying the niche (SEC EDGAR + XBRL for public US companies), though it does not directly contrast with potential overlap like ask_pipeworx_grounded.

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

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

The description gives clear guidance to 'use whenever the agent needs to check whether something a user said is factually correct' and limits scope to company-financial claims. It lacks explicit when-not-to-use instructions or named alternatives, but the context is sufficiently clear for an agent to infer appropriate usage.

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