Solscan

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

The description adds substantial behavioral context beyond the annotations (e.g., scoring range 0-100, returned fields per model, cost implication for Anthropic, default free model). It does not contradict any annotation and provides a comprehensive behavioral model.

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 short sentences, each delivering essential information: action, default and optional usage, output structure, and use cases. No wasted words; all content 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 complexity (4 parameters, 1 required, no output schema), the description is complete. It explains input parameters, default behavior, output format, and common use cases. Annotations cover safety, so no additional safety details 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%, so baseline is 3. The description adds useful extra meaning: default model for 'models', when '_apiKey' is needed, and how 'context' disambiguates. This goes 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 uses a specific verb ('Probe') and resource ('LLMs for entity knowledge'), clearly states the output (visibility score 0-100), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring with a default model and optional Anthropic probe.

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 contexts for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to provide the API key (only if probing Anthropic). However, it does not explicitly exclude scenarios or mention alternative tools, leaving some room for ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it routes to 4,552 tools across 1,160 sources and returns structured answers with citation URIs, which is beyond what annotations provide.

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

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

Description is front-loaded with key imperative 'PREFER OVER WEB SEARCH' and is well-organized into domains, routing, usage guidance, and alternatives. Though somewhat long, every sentence adds value; slight verbosity prevents a 5.

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

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

Given no output schema, the description adequately explains the tool returns structured answers with citations and routes questions. It provides examples and usage context. Could be more specific about output format, but sufficient for agent 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 description coverage is 100% (all 6 parameters documented). Description adds minimal extra info beyond schema, only noting that the question parameter accepts aliases. Baseline 3 is appropriate since schema does the work.

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 authoritative structured data sources, lists many domains (SEC, FDA, FRED, etc.), and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' and resource 'Pipeworx' are well-defined with scope.

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 guidance: 'PREFER OVER WEB SEARCH' for factual questions, and gives step-up alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad queries). Includes many examples and even advises on breaking news.

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: extracts answer only from tool result, returns structured response with refusal reasons, and mentions extra LLM call cost. 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 paragraph front-loaded with purpose, followed by key details. No unnecessary words; every sentence adds value.

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

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

Despite no output schema, description fully explains return structure, failure modes, and use cases. Provides complete guidance for agent decision-making.

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

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

Schema description coverage is 100%, and description adds context that question is in natural language. While schema already covers aliases, description reinforces 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling 'ask_pipeworx' by explaining the grounded extraction process and explicit refusal handling.

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: when answers will be quoted, cited, or acted on and must not invent facts. Also advises to prefer 'ask_pipeworx' for casual lookups due to 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?

The description discloses extensive behavioral traits beyond annotations: market resolution, classification, fan-out patterns, response shapes (result.market, result.analysis, result.evidence), resolver contract with confidence scores, parent event extraction, news fallback fields, safety blockers for low-confidence and closed markets, spread warnings, and cancellation rule parsing. No contradiction with annotations (readOnlyHint, idempotentHint are consistent).

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

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

The description is well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and bullet points, making it navigable. However, it is very verbose (approx. 800 words). While every sentence adds value, it could be tightened without losing clarity. A more concise version would improve agent processing.

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 covers all critical aspects: input handling, classification, data sources, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, spread warnings, and cancellation rules. Edge cases (closed markets, low confidence, wide spreads) are addressed. Examples for different bet types make 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%, so baseline is 3. The description adds significant value by explaining usage patterns for market input (slug, URL, question text), depth options ('quick' vs 'thorough' with details), and include_raw behavior (summarized vs full payloads, size implications). It provides examples and response context beyond the schema, justifying a 4.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verbs ('Research', 'pulling') and resources ('Polymarket bet', 'Pipeworx data'). It details input types (slug, URL, question text) and use cases, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges by offering comprehensive multi-source research in one call.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context on blocking conditions (low-confidence matches, closed markets) and mentions result fields to inspect before trusting analysis. However, it lacks explicit when-not-to-use guidance or direct comparisons to sibling tools, making it clear but not fully exhaustive.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds detailed behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + citation URIs). 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 informative but slightly verbose. Front-loaded with key purpose and usage guidance. Every sentence adds value, but could be trimmed slightly without losing information. Still 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 tool with no output schema, the description fully compensates by describing what data is returned (revenue, net income, etc. for companies; adverse-event counts for drugs) and how results are sorted. It also explains when to use (comparison vs. single lookups) and covers both entity types comprehensively.

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 significant value by explaining the data sources for each type, clarifying that tickers/CIKs are for companies and names for drugs, and noting max of 5. It goes beyond the schema's simple enum/string 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 uses specific verbs ('Compare', 'side-by-side comparison') and identifies the resource (entities of type company or drug). It clearly distinguishes from siblings by stating it replaces 8–15 sequential lookups and explicitly contrasts with sequential single-pack lookups.

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

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

Explicitly tells when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also provides example queries and scope (2–5 entities), leaving no ambiguity about 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. Description adds critical behavioral context: account required (free with paid plan for 'thorough' depth), returns evidence with confidence/source/citation, explicit 'gaps[]' for unanswered facets, 'never invented' data, and expected response time of 15-60s. 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 front-loaded with the critical account requirement and alternative tool. While long, every sentence adds unique value (e.g., data source count, parallel execution, output format). Minor redundancy in repeating 'pipeworx:// citation' could be trimmed, but overall efficient for the complexity.

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

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

Despite no output schema, the description fully explains the return value ('findings packet' with 'verbatim evidence + confidence + source + fetched_at + pipeworx:// citation + explicit gaps[]'), expected duration, and tier restrictions. For a complex tool with two parameters and no output schema, this leaves no critical gaps.

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

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

Schema coverage is 100%. Description enriches both parameters: 'depth' enum values are mapped to facet counts (quick=3, standard=5, thorough=8) with payment tier note; 'question' is described as 'natural language' and 'broad/multi-part is fine'. These details exceed what the 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 the tool conducts 'grounded multi-source research' across '1160 STRUCTURED data sources' by decomposing questions and routing to tools in parallel, returning a findings packet. It distinguishes itself from sibling tools like 'ask_pipeworx' by specifying it is not open-web search and is best for broad/multi-part questions.

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 ('broad/multi-part questions over structured data') and when not to use ('BREAKING or colloquial CURRENT-NEWS' topics, directing to 'ask_pipeworx'). Also notes account prerequisites and advises using 'ask_pipeworx' for single lookups.

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 it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is rich behavioral context beyond annotations.

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

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

The description is two sentences plus a list of domains, front-loading the core action. Every sentence adds value: purpose, return format, usage timing. 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 6 parameters, no output schema, and rich annotations, the description fully informs the agent about what the tool does, when to use it, what it returns, and how parameters work. 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% with all parameters described. The description adds value by explaining that 'query' accepts multiple aliases (task, q, description, search) and by providing natural language examples in the schema's examples array. Also explains the 'limit' parameter indirectly via 'top-N'. This goes a bit beyond 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?

The description clearly states 'Find tools by describing the data or task', which is a specific verb+resource. It distinguishes from siblings by emphasizing discovery and listing diverse domains like 'SEC filings, financials, FDA drugs'.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use advice and implicitly contrasting with other tools.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context: it fans out across multiple sources, mentions USPTO API sunset and soft-fail behavior, and describes the return 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 lengthy but front-loaded with example queries. Every sentence provides useful information. A slight reduction in detail on the sunset could improve conciseness, but overall it is 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?

No output schema exists, so the description must compensate. It explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers the USPTO sunset and name resolution fallback. Adequate for a complex 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 by clarifying that 'type' is only 'company' currently, 'value' can be ticker or zero-padded CIK, and names are not supported. This goes 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 explicitly states it returns a 'full cross-source profile of a US public company' and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and output fields. It clearly distinguishes from sibling tools like 'resolve_entity' by specifying when to use each.

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

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

Provides explicit example queries ('Tell me about X', 'research Acme', etc.) and a directive to 'ALWAYS PREFER over chaining single-pack...lookups when user asks for holistic view'. It also mentions to use 'resolve_entity' first if only a name is available, covering 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?

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, reinforcing destructive nature. No contradictions. Some additional detail like permanence could be helpful but not required given 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 concise sentences, front-loaded with purpose and usage guidance. No redundant words. Every sentence adds value.

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

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

Tool is simple (1 param, no output schema, clear annotations). Description covers purpose, usage, and pairing with related tools. Complete for the tool's complexity.

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

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

Schema covers the single 'key' parameter with description 'Memory key to delete'. Description only repeats 'by key', adding no new semantic detail beyond schema. Baseline 3 is appropriate for 100% schema coverage.

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 explicitly states 'Delete a previously stored memory by key' – specific verb, resource, and mechanism. It distinguishes from siblings 'remember' and 'recall' by mentioning pairing, clarifying its unique role.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, task is done, or clear sensitive data'. Mentions pairing with remember/recall for context. Lacks explicit when-not-to-use but positive guidance is strong.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and nondestructive behavior. The description adds context by explaining the tool fetches the page, extracts title/description/links, and emits standard markdown, which is consistent and informative.

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, front-loaded with the main action, and uses two informative sentences plus a bullet list of 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?

Despite lacking an output schema, the description fully explains the output format (standard llms.txt markdown, single text blob) and placement (site-root/llms.txt). Annotations further cover safety and idempotency, making the tool's behavior complete.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema for the two parameters (url, max_links), but it does reinforce their purpose through context.

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: generate a production-ready llms.txt file for any URL. It specifies the output format and target use cases, distinguishing it from sibling tools by its unique function.

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 client's site indexed, drafting for own project, auditing competitors), but does not mention when not to use the tool or suggest 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 readOnly and idempotent. The description adds behavioral context by specifying the exact fields returned (balance, owner, executable flag, rent epoch), which is useful but does not cover error scenarios or edge cases.

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 sentence that immediately conveys the purpose without any wasted words. It is 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?

For a simple read-only tool with one parameter and an output schema, the description sufficiently covers the return fields. No further detail is needed given the annotations and schema coverage.

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

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

Schema coverage is 100% with a clear description of the 'address' parameter as a Solana public key. The description does not add additional meaning beyond what the schema provides, so 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 the tool provides an overview of a Solana account listing specific fields (SOL balance, owner program, executable flag, rent epoch). It is distinct from siblings like get_token_holdings which focus on token-specific data.

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 explicit guidance on when to use this tool versus alternatives such as get_token_holdings or get_transaction. The description does not mention usage context or exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing output fields (mint, symbol, amount, decimals, USD value) which is not in 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 concise sentences, no unnecessary words. Information is front-loaded and easy to parse.

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

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

Tool has output schema and rich annotations. Description lists output fields, which suffices. Missing usage guidelines are the only gap.

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 provides context ('SPL-token balances') but adds little beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool returns SPL-token balances for a Solana account, specifying fields: mint, symbol, amount, decimals, USD value. This is specific and distinguishes it from siblings like get_token_meta or get_account_detail.

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 on when to use this tool vs alternatives. Siblings include similar tools like get_token_meta and get_account_detail, but the description offers no comparison or context 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 indicate a safe read operation. The description adds value by specifying exactly which metadata fields are returned (e.g., name, supply, market cap), providing context beyond the annotations.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's purpose. No extraneous 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 tool with one parameter and an output schema, the description lists the key return fields. With output schema handling details, this is fully 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 of the token_address parameter. The description does not add significant new detail beyond the schema, but listing the metadata fields indirectly clarifies the parameter's role.

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 provides metadata for an SPL token mint, listing specific fields like name, symbol, decimals. This clearly distinguishes it from sibling tools like get_token_holdings.

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 does not explicitly state when to use this tool versus alternatives. It implies usage for general token metadata retrieval, but no exclusions or context is provided.

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 readOnlyHint and idempotentHint. Description adds the return fields (status, slot, fee, etc.), providing useful behavioral context beyond annotations.

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

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

Two efficient sentences: first states purpose, second lists return fields. 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?

Tool has one parameter, annotations cover safety, description specifies return content. Complete for its 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% (parameter description exists). Description confirms signature is base58 but adds no new meaning beyond the schema.

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

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

Description clearly states 'Fetch a Solana transaction by base58 signature' with specific verb and resource. Distinguishes from all sibling tools as none are about fetching transactions.

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 implies when to use (when you have a signature) but does not explicitly exclude other cases or mention alternatives. However, no direct alternative exists among 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?

Discloses return fields (id, type, params, created_at, last_fired_at, fire_count) and default behavior (active only). Complements annotations (readOnlyHint, idempotentHint, destructiveHint) with useful details.

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

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

Two concise sentences: first defines purpose and outputs, second provides usage guidance. No unnecessary words.

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

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

For a simple list tool without output schema, the description covers return fields, optional parameter, and usage context. It is sufficient for an AI 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 has 100% coverage with description for 'include_inactive'. The tool description adds context that 'active' is default but does not significantly enhance the schema's explanation of the parameter.

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 'List the caller's active subscriptions,' using a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing existing 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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use, though alternatives are not explicitly named (implied by 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is clear. The description adds that it returns specific fields, but does not disclose pagination behavior, rate limits, or ordering of results. Some value added beyond annotations but limited.

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 sentence that front-loads the purpose and output details. No redundant words; 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 annotations (safety profile), input schema (full parameter descriptions), and existence of an output schema (not shown but noted), the description is fairly complete. It could mention pagination details explicitly, but the page params are in the schema. Adequate for a read-only list 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 descriptions for all three parameters (address, page, page_size). The description does not add new meaning beyond the schema; it merely implies the tool requires an address. 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 it lists recent SOL and SPL token transfers for an account, specifying the returned fields (signature, timestamp, side, token, amount, counterparty). This specific verb-resource combination distinguishes it from siblings like get_transaction or get_token_holdings.

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 transfer history but does not explicitly state when to prefer this tool over alternatives such as get_transaction or get_account_detail. No when-not-to-use or exclusion criteria are provided.

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 don't cover rate limits or quota, so description adds value with rate-limit (5 per day), free usage, and how feedback is processed (daily digests, roadmap impact). 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?

Concise (5 sentences), front-loaded with purpose, no fluff. Every sentence adds relevant 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 no output schema, description explains outcomes (team reads, roadmap impact, rate limits) and constraints, making it fully complete for a simple feedback 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 detailed meaning for type enum (explains each value), message constraints (1-2 sentences, 2000 chars), and context optionality, going beyond basic 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 sends feedback to the Pipeworx team, specifying types (bug, feature, data_gap, praise). It distinguishes itself from siblings as the only feedback tool among many 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 says when to use each feedback type, what not to do (don't paste user prompts), and includes rate-limit and quota info, providing clear guidance compared to 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. Description adds valuable context: data derived from CF analytics, no PII, caching behavior (5min-1h). This goes beyond annotations.

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

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

The description is three sentences, front-loading the primary function, then listing use cases, and concluding with data source and caching. 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?

No output schema exists, but the description explains exactly what is returned (top tools, packs, call volume) and provides sufficient behavioral details (source, privacy, caching). For a simple read-only tool with one optional parameter, this is fully adequate.

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

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

Schema coverage is 100% with a single parameter 'window' having an enum and description. The description adds semantic guidance: '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 clearly states the verb 'returns', the resource 'top tools, top packs, and total call volume', and the scope 'over a recent window' with specific durations. It is distinct from sibling tools like 'discover_tools' or '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?

Provides three explicit use cases for when to use the tool (discovering hot data, confirming canonical tool, seeing alignment). Does not mention when not to use or alternatives, but the use cases are clear and contextual.

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 algorithm details (monotonicity, partition sum, semantic anchor, partition filter, fill check with CLOB depth). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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

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

Very informative but slightly lengthy; could benefit from bullet points or section headers for scannability. However, every sentence adds value, and it's appropriately detailed 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?

No output schema, but the description thoroughly explains response fields (opportunities[], partition_check, fill_check). References sibling tool for custom sizing. Covers prerequisites, fallbacks (null arb signal), and edge cases (placeholders, low similarity).

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 brief descriptions. The tool description greatly expands on each parameter: explains event mode with slug examples, topic mode with seed questions, and how each affects the scan. Adds significant meaning beyond schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (trending_scan, event, topic) and distinguishes from sibling tools like polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scans. Recommends event mode, warns not to trade if realizable_edge <= 0, and suggests polymarket_fill_risk for custom sizing.

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

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

The description adds significant behavioral context beyond annotations: caching (1h at KV level), slippage assumptions, market move warnings, and edge calculation details. Annotations already signal readOnly, idempotent, non-destructive, and description aligns with these.

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 well-structured with clear sections for segments, knobs, and response fields. It front-loads the purpose. Every sentence adds meaningful information, though some details (like exact model parameters) could be trimmed without losing utility.

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 9 parameters and no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and edge calculation. It covers why segments might be empty. However, it lacks explicit description of the full output shape (e.g., each opportunity's fields), relying on inline mentions.

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 100% of parameters with descriptions, so baseline is 3. Description adds extra value by explaining real-world implications of slippage (Polymarket zero fees but bid/ask typically 20-50bp) and clarifying why min_kelly doesn't filter partition arbs, requiring min_partition_leg_kelly instead.

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 a clear specific verb 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly states the use case 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven and structural arbitrage opportunities.

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

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

The description explains when to use the tool (discovering opportunities) and provides detailed guidance on adjustable knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly. It also warns about unreliable fed candidates and explains why segments can be empty via diagnostics.

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

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

The description adds significant behavioral context beyond annotations: it explains the tool reads snapshots, provides time-series data, computes trend and decay, and notes that gaps mean no scan occurred that day. It also clarifies that decay is based on daily closes, not intraday. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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

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

The description is fairly lengthy but well-structured, starting with a high-level purpose, then detailing the response structure (tracked, expired, snapshot_dates), and ending with limits. It is front-loaded with the core question. However, it could be slightly more concise while retaining all necessary 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 no output schema, the description thoroughly explains the return format (tracked[], expired[], snapshot_dates[]) and their contents (edge_pp_net time-series, trend, decay, lifespan). It also covers constraints like TTL and snapshot start time. The tool is fully described for effective use.

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

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

The input schema already provides descriptions for both parameters (days and window) with 100% coverage. The tool description adds context by explaining the lookback default/max and the list of window options, reinforcing the schema. It does not add entirely new parameter meaning but reinforces 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from sibling tools like polymarket_edges (which likely provides current edges) by focusing on historical persistence and decay 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 explains when to use the tool: to answer how long an edge has existed and whether it is shrinking. It provides context that a fresh wide edge is different from an old wide edge. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_edges 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds context: it walks the ladder, returns fields like slippage_pp, verdict, thin_legs, and warns about forced directional risk. 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 dense but well-structured with capitalized mode labels and a clear flow. Some repetition could be trimmed, but every sentence adds value. Slightly verbose but effective.

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

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

Given no output schema, the description fully explains return fields for both modes, includes warnings about partial fills and forced directional risk, and covers edge cases like thin_legs and max_clean_notional_usd. Complete for an agent to understand.

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 meaning: explains side behavior in different modes, size_usd interpretation differences (spend vs target proceeds vs settlement notional), defaults, and clamps. This goes well beyond the schema.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live order-book depth. It distinguishes between single-market and basket modes and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying its use as a pre-action validation.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial basket fills cause directional risk).

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 critical behavioral traits: two modes, response structure (leg-by-leg prices, spread, safety fields), compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for dropped leg-pair comparisons. 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 detailed but well-organized with sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. However, it is somewhat verbose—some sentences could be tightened without losing meaning. Still, every sentence earns its place.

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

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

Given no output schema, the description thoroughly explains the response structure, including safety fields, temporal alignment, and skipped counters. For a tool with 3 optional params, it covers all scenarios and edge cases, making it 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% (all parameters have descriptions), so the baseline is 3. The description adds significant value by explaining the interplay between topic and explicit mode, how parameters override each other, and providing examples. This elevates it above mere schema repetition.

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 (topic and explicit) and distinguishes itself from the sibling tool 'polymarket_arbitrage' which focuses on single-venue arbitrage. The verb 'spread' and resource 'Polymarket–Kalshi' are specific and unambiguous.

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

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

The description provides guidance on when to use topic mode vs explicit mode, and warns that pre-mapped shortcuts often don't yield tradeable spreads. It implies that for single-venue probabilities, other tools like 'bet_research' would be appropriate, but it does not explicitly name alternatives. The context of sibling tools compensates somewhat.

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 readOnlyHint=true and destructiveHint=false. Description adds that listing occurs when key is omitted, and scoping by identifier. 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 with no redundancy. Front-loaded with the primary action. Every sentence adds value.

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

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

Tool has no output schema, but description explains what it does (retrieve value or list keys) and mentions scoping. Could specify return format, but 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 description coverage is 100% and property description already states 'omit to list all keys'. The description reinforces this but adds limited new value beyond the schema.

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

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

Clearly states the tool retrieves a saved value or lists all keys. Uses specific verbs (Retrieve/list) and identifies the resource (keys/values). Distinguishes from sibling tools remember and forget by naming them in the description.

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: to look up context saved earlier, avoiding re-derivation. Mentions scoping by identifier. Does not explicitly state when not to use or name alternatives, but the context with siblings remember and forget 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, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds valuable behavioral context: it returns the most recent alerts with specific fields (source, citation_uri, raw payload), explains the mark_read flag's effect on advancing the read pointer, and notes that unread_only filters by read_at null. 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 purpose ('Pull fired events...'). It covers content, filtering options, mark_read behavior, and polling suitability in a few sentences. While efficient, slightly longer than necessary but no redundant information.

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

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

Given 5 optional parameters and no output schema, the description comprehensively covers the return fields (source, citation_uri, raw payload), filtering by type and since, the mark_read behavior, polling suitability, and alternative access. No gaps—an agent can confidently invoke 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 description coverage is 100% (all 5 parameters have descriptions). The description adds meaning by explaining how mark_read changes subsequent calls and the purpose of filtering by type and since. This goes beyond the schema's simple descriptions, justifying a score above baseline 3.

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

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

The description starts with 'Pull fired events from your subscription feed', clearly stating the verb and resource. It distinguishes from sibling tools like 'list_subscriptions' by focusing on events from subscriptions, not the subscriptions themselves. Also mentions an alternative access method (GET registry.pipeworx.io/alerts.json).

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 'Polls work fine' and points to an alternative endpoint for scripts/dashboards, giving clear context on when to use this tool. However, it does not explicitly state when not to use it or prerequisites (e.g., must have 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?

The description adds significant behavioral detail beyond annotations: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and parameter format rules (ISO date vs. relative shorthand). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description reinforces and expands 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 a single dense paragraph with front-loaded examples and minimal waste. Every sentence contributes information, but the density could be improved with bullet points or clearer separation of fallback logic and parameter 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?

Given the tool's complexity (multiple sources, fallback, soft-fail, three required parameters) and no output schema, the description adequately covers behavior and return structure (changes[], total_changes, citation URIs). Could briefly mention error handling when all sources fail, but overall 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%, but description adds value: explains relative date shorthands for 'since' (7d, 30d, 3m, 1y) and typical use ('30d' or '1m'), clarifies 'value' accepts ticker or CIK, and notes 'type' is limited to 'company'. This goes 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 explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific example queries. It lists data sources (SEC EDGAR, GDELT, GNews, USPTO) and distinguishes itself from the sibling tool 'entity_profile', which is for static profiles.

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 recommends using 'entity_profile' for static profiles. It also explains fallback behavior and soft-fail for USPTO. However, it does not explicitly state when not to use the tool beyond the alternative.

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

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

Annotations provide idempotency and non-destructive hints. Description adds scope (per-agent key-value, authenticated vs anonymous duration) 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?

Four concise, front-loaded sentences with no redundancy. Each sentence adds distinct value: purpose, usage trigger, storage mechanism, and companion 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?

No output schema; description explains persistence differences and pairs with recall/forget, covering key behavioral aspects for a simple store tool.

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

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

Schema coverage is 100% with clear descriptions. Description does not add additional parameter meaning beyond what schema provides, meeting 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?

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples. Differentiates from siblings recall and forget.

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

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

Explicitly advises when to use (when discovering something worth carrying forward) and pairs with recall/forget, but does not explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds valuable context: it cascades through multiple endpoints, replaces 2-3 manual lookups, and specifies return details (e.g., ticker+CIK+URI, RxCUI+ingredient+brand). This goes well beyond annotations.

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

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

The description is reasonably concise at ~4 sentences and well-structured, starting with query examples and ending with supported type details. Minor wordiness could be trimmed, but overall it's efficient and front-loaded with key examples.

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

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

Given no output schema, the description fully explains return values for each type (e.g., ticker, CIK, company_name, citation URI for companies; RxCUI, ingredient, brand for drugs). It covers input, process, and output thoroughly, making it complete for a lookup 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 both parameters described. The description enriches parameter semantics by providing concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying accepted input formats for both company and drug types, adding significant 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 resolves a name to an official identifier, using specific verbs and resources like ticker, CIK, RxCUI. It distinguishes itself by stating 'Use FIRST whenever you have a name but need an ID,' making its purpose explicit and distinct from siblings.

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 ('Use FIRST whenever you have a name but need an ID'). However, it does not explicitly mention when not to use it or suggest specific alternatives among sibling tools, though its purpose is clear enough to avoid misuse.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. 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 four sentences, each serving a purpose: stating the action, explaining the method, giving a use case, and specifying the output. 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 no output schema, the description adequately describes the return format (ranked list with score/confidence/signal density). It explains the composite nature and use case. Could be enhanced by mentioning any limits on entities (2-8 from schema) but that is in the schema.

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

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

Schema coverage is 100%, but the description adds value by clarifying that the first entry in entities is treated as the 'subject' for narrative and the rest as competitors. This nuance is not in the schema 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 uses a specific verb-resource combination ('Compare AI visibility across multiple entities side-by-side') and distinguishes from sibling tools like ai_visibility_check by stating it probes each entity with that tool and ranks results. It also contrasts with potentially generic comparison 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 gives a clear use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). However, it does not explicitly state when to avoid this tool or mention alternatives like using ai_visibility_check 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 provide readOnly and idempotent hints. The description adds significant context: composite fan-out to two services, behavioral detail about bundlephobia's first measurement taking 5-30s, graceful degradation with sources_failed list, and the return structure summary.

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 5 sentences, front-loaded with the core purpose. Every sentence adds value, but it is somewhat dense. Could potentially be slightly more structured, but remains efficient for the amount of 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 no output schema, the description fully covers return fields (summary block with listed fields, per-advisory detail, links, alternative versions). It also addresses input constraints (scoped packages, default version), and explains partial failures and timeout. Very complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: for 'package' it notes scoped packages are accepted, and for 'version' it clarifies default behavior (latest) and mentions defaults. This is above the 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?

The description clearly states it is a composite check for npm packages, listing specific checks (license, advisories, version history, bundle size, etc.). It uses specific verbs and resources, and the 'NPM ecosystem only' line distinguishes it from possible non-npm dependency tools among siblings.

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 agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing both when and when-not to use, with an alternative.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and returns character offsets for verifiable quotes.

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 slightly verbose (5 sentences). However, it is well-structured: starts with problem and solution, then details and pairing. Every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly explains return values (top-N passages with offsets and similarity scores) and covers edge cases (truncation). The tool is complex but fully described.

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

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

Schema coverage is 100% but the description enriches parameter meanings: clarifies `text` is from a fetched record, gives example queries for `query`, and notes default for `limit` (5). Adds context beyond schema field names.

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 ('semantic search inside a fetched record') and identifies the resource (a record's text). It distinguishes from siblings like `ask_pipeworx_grounded` by explaining the pairing and different function.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt — search_within saves context'. Also provides guidance on pairing with `ask_pipeworx_grounded` for grounded answers.

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=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: account requirement, delivery channel constraints (SMS 10/day cap, webhook auto-disabled after 10 failures, secret returned once). Does not contradict annotations. Missing explicit idempotency mention, but annotations provide it.

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 primary action and return value. Followed by essential context, type examples, and delivery details. Dense but well-organized. Could be slightly tighter, but 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?

Given no output schema, description explains return (subscription id). Covers prerequisites, type-specific parameters, delivery channels with constraints. Comprehensive for a subscription creation tool. Missing explicit mention of idempotency, but annotations compensate.

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 extensive meaning beyond schema: explains type-specific parameters with examples (e.g., items codes for sec_8k, topic for polymarket_edge, series_id for fred_series). Also details delivery options (email, SMS, webhook) with constraints (E.164 format, verification, signing). Greatly enhances 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb (create), resource (subscription to live-data stream), and return value are explicit. Distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

Provides explicit context: requires Pipeworx OAuth account (anonymous/BYO cannot persist). Lists supported subscription types with examples and parameters. No explicit 'when not to use', but sibling tools cover related actions (unsubscribe, recent_alerts). Clear context for selective invocation.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral context: it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and it is an onboarding tool. 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 front-loaded with alternative phrasings that help the AI map user intent, then explains purpose, output content, and usage instructions. Every sentence adds value, and the structure is logical 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 simplicity (one optional parameter, no output schema), the description fully covers what it does, what it returns, how to use it, and when to use it. It mentions the source (live catalog) and the relationship to meta-tools, leaving no gaps.

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

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

Schema coverage is 100% with a detailed description of the topic parameter. The description reinforces that parameter's purpose and provides example values, adding some extra context about focusing the output. This is above the baseline of 3 but not a significant leap.

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 identifies the tool as an onboarding entry point that returns categorized example questions. It distinguishes itself from sibling tools by stating it should be used first when the agent doesn't know what Pipeworx can do, and it names specific meta-tools like ask_pipeworx and 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?

Explicit use case is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass the topic argument vs. calling with no arguments, providing clear guidance on alternatives.

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

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

The description adds behavioral details beyond annotations: it states that ownership is enforced and that the row is deactivated (not deleted), keeping historical events available. However, it does not mention idempotency, which is indicated in annotations (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?

The description is two sentences: the first states the action, the second adds key constraints. It is concise, front-loaded, and every sentence adds value.

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

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

Given the tool's simplicity (one parameter, no output schema) and the rich annotations, the description covers purpose, ownership, and behavioral nuance. It references 'recent_alerts' to clarify the deactivation benefit, making it contextually 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?

The only parameter 'id' is described in the schema as 'Subscription id (uuid) returned by subscribe.' The description adds no additional meaning beyond this, and schema coverage is 100%, so a baseline of 3 is appropriate.

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

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

The description clearly states the function: 'Cancel a subscription by id.' It specifies the action (cancel) and the resource (subscription), and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation (not deletion).

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

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

The description explicitly notes 'Ownership is enforced — you can only cancel your own subscriptions' and explains the deactivation behavior. This gives clear context for when to use the tool, though it does not mention alternatives or 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?

The description adds significant behavioral context beyond annotations: it explains the tool returns verdicts, structured form, actual value with citation, and percent delta. It also notes that it replaces 4-6 sequential calls. Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description complements these well.

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

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

The description is concise yet comprehensive, front-loaded with example queries, and every sentence contributes meaning. It avoids redundancy and is 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?

The description covers purpose, usage, input format, and key outputs (verdict types). However, it lacks details on how to interpret the verdicts or handle edge cases, and there is no output schema. Given the tool's complexity, slight more depth would improve completeness.

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

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

The single parameter 'claim' has 100% schema description coverage. The description adds value by providing natural-language examples and clarifying the expected format. This 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's purpose: natural-language claim verification against authoritative sources for company-financial claims. It provides specific examples and mentions the return types (verdict, structured form, citation, delta). It distinguishes itself from sequential calls, though not explicitly from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implicitly sets scope by mentioning 'v1 supports company-financial claims'. However, it does not provide explicit when-not-to-use or alternative tools, leaving some ambiguity.

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