Dart Kr

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the probing nature, free default model, BYO key for Anthropic, and return format. It does not contradict annotations and provides useful behavioral context beyond them.

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

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

The description is moderately concise and well-structured: first sentence states main purpose, then parameter details, then use cases. It could be slightly more terse but is well-organized 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?

Despite no output schema, the description outlines the return structure (per-model score, confidence, signals, raw_response + combined view). It covers all critical details for a probing tool: entity, optional models, API key handling, and context. No gaps in essential information.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds meaningful context: default model explanation for 'models' parameter, BYO key clarification for '_apiKey', and usage context for 'context'. This goes beyond 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 uses a specific verb ('Probe') and resource ('LLMs for knowledge about a business/brand/product/topic') and clearly states it scores visibility 0-100. It distinguishes from siblings by focusing on AI visibility scoring, which is unique among the 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 states when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model and optional Anthropic probe. However, it does not explicitly mention when not to use it or compare to alternatives like scan_competitor_ai_presence or entity_profile.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds useful behavioral context: it functions as a router, returns stable pipeworx:// citation URIs, is fast ('one fast call'), and works on every tier. This goes beyond the annotation signals and tells the agent what to expect functionally.

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

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

The description is longer than typical but every part serves a purpose: scope, examples, routing guidance, and alternative tool selection. It front-loads the key instruction ('PREFER OVER WEB SEARCH') and the examples are concrete, though some repetition of the domain list could be trimmed.

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

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

For a single-parameter tool with no output schema, the description is complete: it explains what inputs are accepted, what the tool does internally, what the output contains (structured answer with citation URIs), and when to use alternatives. An agent can confidently select and invoke this tool based on the description alone.

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 fully documents the 'question' parameter and its aliases, so the baseline is 3. The description adds value by giving real example questions per domain and clarifying that natural-language factual questions are the intended input, which helps the agent formulate the parameter correctly.

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

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

The description clearly identifies the tool as a default factual-query router: it 'routes the question to the right one of 5,743 tools' and returns a structured answer with citation URIs. It also lists concrete domains (SEC filings, FDA data, FRED, stocks, etc.) and distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this over web search, gives trigger-phrase examples ('what is', 'look up', 'get the latest'), and tells the agent when to step up to alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is clear, actionable guidance with named 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 annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful operational context: no candidate is currently active, it matches ask_pipeworx exactly today, and it is a full working router with no fallback. This goes beyond the structured hints and sets accurate expectations.

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

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

The description is front-loaded with the core identity and is reasonably compact for the amount of context it conveys. There is minor redundancy between 'matches ask_pipeworx exactly' and 'identical universal router', but no sentence is wasted.

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

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

Given the high schema coverage, read-only annotations, and the explicit statement that the response shape matches ask_pipeworx, the definition gives an agent enough to call the tool correctly. It lacks an example or return-value sample, but this is a thin beta wrapper over a known sibling, so the gap is minor.

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 documents q, text, input, query, prompt, and question with 100% coverage, so the description adds little parameter-specific meaning. The statement that it takes the same arguments as ask_pipeworx is useful but does not add detail 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 states clearly that this is the beta variant of ask_pipeworx, an identical universal router over 5,743 tools with the same arguments and response shape, but with experimental routing improvements when active. This distinguishes it from the stable ask_pipeworx and the grounded sibling.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is wanted, and explains that results are compared against the stable router. It gives a clear use condition, though it does not spell out exclusions or when the stable version should be preferred.

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

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

Beyond the readOnlyHint annotation, the description discloses the refusal contract with specific refusal_reason values, promises a verbatim evidence quote, explains that data may be truncated, and reveals the extra LLM call cost. This gives the agent a precise mental model of failure modes and safety behavior.

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?

Every sentence earns its place: the core behavior, return contract, refusal reasons, usage guidance, and cost comparison are all packed into a compact paragraph. The critical 'use only what the tool result contains' constraint is front-loaded before the return 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 there is no output schema, the description fully covers the return shape and refusal reasons. It also supplies routing guidance, cost tradeoffs, and a list of high-stakes use cases. An agent has everything needed to decide when to call it and how to interpret its response.

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

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

The schema already documents the question parameter and all five aliases with 100% coverage, so the description does not need to explain parameter semantics. The description adds no parameter-level detail beyond framing the input as a natural-language question, which is consistent with the baseline for a fully documented single-logical-parameter tool.

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 opens with a specific claim: 'Hallucination-resistant answer mode for high-stakes reads.' It then explains the exact pipeline — route to a tool, fill arguments, fetch data, and extract the answer only from the tool result — which clearly distinguishes this from ask_pipeworx and other 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 explicitly states when to use it: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual 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?

Adds extensive behavioral details beyond annotations: market resolution, classification, fan-out, response shapes, safety short-circuits, resolver contract, parent event extraction, news fallback, and blocking behaviors. No contradiction with annotations.

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

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

Front-loaded with core purpose but very long and dense single paragraph. Lacks structured formatting (e.g., bullet points) for readability. Every sentence adds value but could be more concise and better organized.

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

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

No output schema, so description fully explains return values: result fields, resolver contract, parent event, news fields, safety behaviors, and edge cases. Covers all aspects needed for an agent to use the tool correctly.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining market input formats (slug, URL, question text) and examples for depth/include_raw. Some extra context provided 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?

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific usage examples like 'should I bet on X'. Differentiates from sibling tools by focusing on Polymarket bets and Pipeworx 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?

Explicitly says what to use it for ('use for should I bet on X'), includes safety warnings to inspect fields before trusting analysis, and mentions resolution-rule risk before sizing bets. Provides clear context despite not listing alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) declare safe, read-only, idempotent behavior. Description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction.

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

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

Concise 3-4 sentence description front-loaded with user-query examples. Every sentence adds value: usage patterns, data specifics, and efficiency claim. 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 2 required params, no output schema, and rich annotations, description covers what each type returns, result sorting, and replaces many lookups. Lacks details on error handling or response format but sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values'. Description enriches by explaining what data each type pulls (e.g., 'latest 10-K revenue + net income' for companies, 'FAERS adverse-event counts' for drugs) and provides examples for 'values'.

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 leads with clear example queries ('Compare X and Y', 'X vs Y', 'which is bigger') and explicitly states the action: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It distinguishes from sibling tools by advising 'ALWAYS PREFER over 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?

Provides explicit when-to-use examples covering typical comparison scenarios (e.g., 'rank these companies', 'head to head'). States preference over sequential lookups. Missing explicit when-not-to-use but context 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and behavior. The description adds value by listing the returned fields and the purpose, which complements the annotations without contradiction.

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

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

The description is concise with two sentences. The first sentence lists the fields, and the second provides usage guidance. Every sentence is necessary and well-structured, front-loading the most important 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?

Despite no output schema, the description lists all expected return fields (corp_name, stock_code, CEO, market tier, industry code, address, founding date, fiscal-year-end month, homepage), making the output clear. It also provides usage context, making it complete for a simple 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?

The input schema already describes the parameter (8-digit DART corp identifier) with 100% coverage. The description adds context by explaining that the corp_code typically comes from dart_search_filings, which is useful for understanding parameter origin, but does not add new syntax or constraints 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 returns a basic profile for a Korean DART-registered company and lists the specific fields (corp_name, stock_code, CEO, market tier, etc.). It also distinguishes from siblings by noting it is used after dart_search_filings to enrich corp_code or as a first lookup.

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 tells when to use the tool: after dart_search_filings to enrich a corp_code into a readable entity, or as the first lookup when given a corp_code with no context. This provides clear guidance and suggests alternatives (other tools for financials, etc.).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by clarifying the output includes current and prior period amounts and that data goes back to 2015, offering behavioral 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?

Three sentences with no wasted words; front-loaded with the core purpose, then usage guidance, then pairing recommendation. Excellent conciseness and structure.

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

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

Given high schema coverage and no output schema, the description adequately covers what the tool returns (income statement, balance sheet, cash flow items) and example line items. It could mention output format, but for fundamental analysis it is sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds contextual value (e.g., pairing suggestion, example line items) but does not significantly deepen parameter-level meaning beyond the schema.

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

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

The description clearly states that the tool retrieves key financial line items from Korean company periodic reports, specifying the types of statements and periods. It does not explicitly distinguish from sibling tools like dart_company_info or dart_insider_holdings, but those have obviously different purposes, so the purpose is clear.

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

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

The description advises using the tool for fundamental analysis on KOSPI/KOSDAQ filers and suggests pairing with ecos_get_series for macro context. This provides practical guidance, though it lacks explicit when-not-to-use or alternative tool mentions.

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, covering safety. Description adds value by detailing the return fields and the analogy to US Form 4, but does not mention rate limits or auth requirements.

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

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

The description is concise: two sentences, front-loaded with the key purpose and use cases. No unnecessary words or 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 one parameter and comprehensive annotations, the description adequately explains the return fields and use cases. It could mention data freshness or historical scope but is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% for the single parameter 'corp_code', which has a clear description. The tool description does not add additional parameter-level information beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns insider equity-holding disclosures for Korean executives and major shareholders, listing specific fields and drawing analogy to US Form 4. It distinguishes from siblings like dart_major_shareholders by specifying 'insider transactions' and executive compensation 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 explicitly recommends use for insider-trading signal, executive compensation analysis, and family ownership tracking. It does not explicitly exclude alternatives but provides clear use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context about regulatory threshold (5%) and equivalence to US filings, enhancing transparency.

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

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

Two sentences with no redundancy: first defines functionality and output, second gives usage context. Front-loaded and 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 single parameter and safe read-only nature, description covers return fields, regulatory background, and use cases sufficiently despite lack of output schema.

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

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

Schema description for corp_code is already clear (8-digit DART identifier). Description does not add further details; baseline 3 due to 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?

Clearly states it retrieves Korean 5%-rule disclosures for a company, specifies returned fields (shareholder name, holding type, shares, stake, change reason, report date), and compares to US 13D/13G. Distinct from sibling tools like dart_insider_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?

Provides explicit use cases: 'who owns big stakes in $KR_COMPANY', activism tracking, follow-the-money on KOSPI filings. Lack of explicit when-not-to-use or alternative mentions is minor given clear context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds useful behavioral details like default date ranges (30 days ago to today) and that omitting corp_code searches all companies, providing transparency 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 a single, focused paragraph that front-loads the purpose and immediately lists key return fields. It uses no filler sentences and has a natural flow from purpose to filters to 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?

The description covers the tool's core functionality, return fields, and filtering options. Although there is no output schema, the description mentions the key return fields (rcept_no, rcept_dt, etc.). It misses some nuances like pagination but is complete for most use cases.

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

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

With 100% schema description coverage, the description adds value by giving concrete examples for corp_code (e.g., '00126380' for Samsung) and expanding on pblntf_ty categories (e.g., 'B (major events)'). This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool provides an 'AUTHORITATIVE list of recent Korean corporate disclosures' from DART, with specific fields returned. It includes concrete use cases like 'what did Samsung file last week', distinguishing its purpose effectively.

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

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

The description gives explicit usage examples (e.g., filtering by company, date range, filing type) and specifies the tool is for recent filings. It doesn't explicitly mention when not to use or alternatives, but the context is clear enough for an AI agent.

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

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

Annotations declare read-only, idempotent, non-destructive behavior, and the description greatly enriches this: account/plan requirements, parallel decomposition, explicit gaps[] that are 'never invented,' contradictions[] for standard/thorough, semantic excerpting, resolvable pipeworx:// citation URIs, and expected latency ranges. It also clearly notes what happens for topics outside the structured catalog (mostly empty gaps). No annotation contradiction.

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

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

The description is long and dense, but nearly every clause adds distinct operational information: auth, source scope, alternatives, depth semantics, output shape, limitations, timing, and citation fetchability. It front-loads the account requirement and the key 'NOT open-web search' caveat. Some redundancy exists with the depth parameter schema, and the single-paragraph structure could be tightened, but overall it earns its length.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers the findings packet shape (verbatim evidence, confidence, source, fetched_at, citation_uri), the gaps[] behavior, contradictions, hop mechanics, timing, and auth limitations. It gives the agent enough context to invoke the tool correctly and interpret its results.

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

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

The input schema already provides full descriptions for both parameters, with 100% coverage. The description adds meaningful behavioral nuance beyond the schema, especially for depth: 'quick=3 (single hop), standard=3... gap-recovery hop... contradictions[] scan, thorough=6... full iterative hop.' It also clarifies that the question parameter can be broad or multi-part, reinforcing the decomposition design.

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

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

The description states a precise verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call.' It also explicitly contrasts itself with sibling tools: 'this is NOT open-web search' and names ask_pipeworx as the alternative for single lookups and current-news topics. The agent can clearly distinguish deep_research from siblings without inspecting schemas.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: best for 'broad/multi-part questions over structured data,' while single lookups and breaking/current-news should 'prefer ask_pipeworx.' It also specifies the account prerequisite and directs unsigned-in users to ask_pipeworx, plus explains depth-tier behavior for choosing standard vs thorough.

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, and description does not contradict. Description adds behavioral context: results are ready to call directly with full schemas, no second lookup needed.

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 a single paragraph, front-loaded with the core purpose. It lists many categories, which is useful but slightly wordy. Could be tightened without losing meaning.

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

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

No output schema, but description explains what is returned (top-N tools with names, descriptions, schemas). Sufficient for a discovery tool with read-only, idempotent behavior.

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

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

Schema coverage is 100% (all 6 parameters documented). Description adds value by explaining aliases for 'query,' providing examples, and stating defaults for 'limit.'

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

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

Description starts with 'Find tools by describing the data or task,' which is a specific verb+resource. It lists many categories (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools that are specific data tools.

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

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

Explicitly states '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 guidance and implying not to use when you already know the tool.

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

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

The description goes far beyond the annotations by disclosing the multi-source fan-out, fallback chains, soft-failure behavior for USPTO patents, expected empty results for FDA products, and the resolved:false private-company path. It explicitly warns that an empty section means 'no data,' not a bug, which is valuable behavioral context.

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

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

The description is lengthy but dense with necessary information, and it front-loads concrete examples and the core purpose. Each detail about return fields, failure modes, and input forms serves a purpose, though the single-paragraph structure could be better organized for scanability.

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

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

With no output schema, the description carries the full burden of explaining return structure, and it does so thoroughly: it enumerates each returned section, the source behind it, URI format for filings, and the meaning of resolved_from/resolved_to. It also explains fallback behavior and expected empty results, making the tool safely callable.

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 already 100%, so the baseline is 3, but the description adds meaningful clarification: 'type' accepts 'company' or 'ticker' interchangeably, and 'value' can be a ticker, zero-padded CIK, or company name with resolution via SEC EDGAR. This enhances parameter understanding beyond the schema's basic field 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 specific verbs and a clear resource: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple query examples and explicitly states this tool should be preferred over chaining single-pack lookups, clearly distinguishing it from narrower 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 explicitly states when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies acceptable inputs, the meaning of empty sections, and the behavior for private companies, giving an agent clear decision rules.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and operating on memory, which is consistent and helpful beyond the annotations.

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

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

Two sentences, no unnecessary words, and front-loads the core 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?

For a simple one-parameter tool with no output schema, the description covers purpose and usage. However, it lacks details on what happens if the key doesn't exist or confirmation of success, which 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?

Schema coverage is 100%, so the parameter 'key' is already described. The description only mentions 'by key' and the example provides a sample, adding minimal extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by focusing on 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 provides explicit when-to-use scenarios: stale context, task done, clearing sensitive data. It also suggests pairing with remember and recall, giving context for usage but not explicitly 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?

Description adds value beyond annotations by detailing the process (fetches page, extracts title/description/key links) and output format. Annotations already declare readOnlyHint, idempotentHint, and non-destructive, and description aligns 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 concise with three sentences plus a bullet list, front-loading the main action and output. Every sentence earns its place with no redundancy.

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

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

Given the simple operation (2 params, no output schema), the description fully covers what the tool does, how it works, and the output format. No gaps remain for effective usage.

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 briefly mentions max_links defaults (25, max 50) which is already in schema, adding no significant new meaning beyond 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's purpose: generate a production-ready llms.txt file for any URL. It specifies the output format and distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists concrete use cases (getting client site indexed, drafting own llms.txt, auditing competitor), providing clear context for when to use. It lacks explicit when-not or alternative tool recommendations, but the use cases sufficiently guide selection.

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

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

Annotations already declare readOnlyHint, non-destructive, idempotent. Description adds specific return fields and the optional parameter behavior (include_inactive). No contradictions.

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

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

Two sentences, succinct and front-loaded with the core action. No extraneous 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 with 1 optional param and good annotations, the description fully covers purpose, return fields, and usage context. No output schema needed.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. Description does not add detail beyond the schema's description of include_inactive, but it does clarify default behavior (active only).

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 lists the caller's active subscriptions and lists the return fields. The verb 'List' and resource 'subscriptions' are explicit, and the description distinguishes it from sibling tools like subscribe/unsubscribe.

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

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

Provides context on when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. It implicitly advises against adding without first reviewing, but does not explicitly mention alternatives like subscribe or unsubscribe.

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

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

With all annotations false, the description fully carries the burden of disclosing behavior. It reveals rate limiting (5 per identifier per day), that it's free and doesn't count against quota, the anonymous claim_token flow for tracking feedback, and that the team reads digests daily. No contradictions with annotations.

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

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

The description is dense and front-loaded with the core purpose. Each sentence adds unique information (scope, exclusions, token flow, rate limit, cost). While a bit long, it remains efficient and well-structured for the complexity it covers.

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?

There is no output schema, but the description explains the return behavior (claim_token) and how to later check resolution status. It also covers edge cases like uncertainty about server ownership and account-less usage. Given the tool's complexity and optional parameters, the description is complete.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds value by explaining the claim_token workflow (passing it later to read status) and providing message content guidelines (be specific, don't paste user's prompt), which are not in the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and explicitly enumerates feedback types (bug, feature, data_gap, praise), which distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit when-to-use scenarios: when a tool returns wrong/stale data, when a desired tool is missing, or when something worked well. It also gives a clear exclusion: do not report tools from other MCP servers, and tells the user to file with that server instead. This is exemplary guidance.

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

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

Annotations (readOnly, openWorld, idempotent) already declare safety; description adds caching details (5min–1h) and confirms no PII. No contradictions, and adds useful behavioral 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?

Approximately 4 sentences, front-loaded with main output, then use cases, then caching note. Every sentence adds value; 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?

Explains return fields (top tools, packs, volume) and caching. With no output schema, it provides sufficient context for typical use. Could mention potential limits (e.g., top N count), but not critical for clarity.

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

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

Single parameter 'window' with enum values fully described in schema. Description adds semantic nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', which enriches the schema's enum list.

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 returns trending call data (top tools, top packs, volume) over configurable windows. The verb 'returns' and specific resource model it well from siblings like ask_pipeworx (direct Q&A) or discover_tools (broader discovery).

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

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

Lists three concrete use cases (hot data sources, canonical tool confirmation, use case alignment). Lacks explicit when-not-to-use or direct sibling comparisons, but the use cases provide strong contextual guidance.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: internal logic (Jaccard similarity, partition filter, placeholder detection), fill check mechanics, and edge cases. 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 lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though some details could be more terse. Well front-loaded with purpose and usage.

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

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

Given the tool's complexity (multiple modes, intricate checks) and lack of output schema, the description thoroughly covers expected outputs (opportunities array, fill check details) and operational constraints, providing a complete picture for the 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?

Both parameters are documented in the schema (100% coverage). The description adds meaning beyond the schema by explaining what constitutes a valid event slug vs topic seed question, providing concrete examples, and clarifying the no-args default behavior.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args (trending scan), event (single event), and topic (cross-event), each with a specific verb and resource, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly guides when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It explains cross-event mode catches patterns single-event misses, and provides a fill check warning not to trade if realizable edge <= 0, offering clear decision criteria.

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 and idempotentHint; description adds extensive behavioral detail: three model families with formulas, edge calculation (net of slippage), caching at KV level for 1h, diagnostics for why segments are empty, and 24h-move warning. Fully transparent with 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 thorough but long (~600 words). Well-structured with sections for segments and knobs, front-loading purpose. However, some detail could be condensed for easier parsing while retaining 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 explains response structure (by_segment, fed_candidates, _diagnostics), covers inputs, behavioral traits, filters, and caching. Complete for agent invocation.

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

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

All 9 parameters have schema descriptions; description enriches them with practical context (e.g., min_liquidity: 'Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven'). Adds meaning beyond schema.

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

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

Description explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifying three segments. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery and edge detection.

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

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

Clearly positioned as 'what should I bet on today' for discovering opportunities without paging. Provides guidance on when to use and describes knobs like min_liquidity and max_spread_pp, but does not explicitly state when not to use or compare to alternatives, though context is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond annotations: data comes from daily snapshots with 60-day TTL, decay computed from daily closes (not intraday), and snapshot gaps occur when no cache miss. 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 long but well-structured with clear subsections. It front-loads the core purpose and includes necessary details about response format and limits. Some redundancy (e.g., default values repeated) could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description fully explains the three response arrays (tracked, expired, snapshot_dates) with field semantics. It also covers data freshness and limitations (TTL, snapshot start). For a read-only telemetry tool with 2 well-documented params, this is highly complete.

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

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

Schema description coverage is 100% so baseline is 3. The description reiterates and slightly extends parameter meaning (defaults, clamp, window family), but adds limited new semantic value beyond the schema's existing 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 specific verbs and nouns: 'Edge persistence and decay telemetry' and answers a concrete question about edge longevity and shrinkage. It clearly distinguishes from sibling tools like 'polymarket_edges' by focusing on historical time-series rather than current snapshots.

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

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

The description provides clear context for when to use this tool—to differentiate between fresh-wide edges and old-wide edges—and implies not to use it for current snapshot data. However, it lacks explicit when-not or alternative tool mentions, leaving 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, and non-destructive. The description adds rich behavioral detail: how it walks the order book, returns like slip, shares_filled, max_fillable_usd, verdict, and per-leg details for baskets. It also explains the risk of partial fills converting directional risk, which is critical context beyond what annotations provide.

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

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

The description is well-structured: a concise opening sentence, organized breakdown of single-market and basket modes with return values, and a concluding advisory on usage. Despite its length, every sentence adds value, and the structure aids quick comprehension.

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

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

With no output schema, the description must cover return values, which it does exhaustively for both modes. It also explains edge cases (thin_legs, forced_directional_risk) and provides usage guidance. Four parameters are fully described in both schema and description, making the tool's operation 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 description coverage is 100%, baseline 3. The description significantly adds meaning: it explains the dual mode (market vs event), the interpretation of side defaults in basket mode, and how size_usd is interpreted as settlement notional in basket mode. This goes well beyond the schema's field descriptions, making parameter usage clear.

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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly links to sibling tools (polymarket_arbitrage, polymarket_edges) by stating when this tool should be used before them, providing strong differentiation.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the consequences of not using it (partial fills converting arb into directional risk) and clarifies required parameters (one of `market` or `event`), leaving no ambiguity about when to invoke 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 readOnlyHint, idempotentHint, and openWorldHint, but the description far exceeds that baseline. It discloses the matching mechanism (keyword/word overlap, not a shared resolution source), that unknown legs are never paired, the meaning of null temporal alignment, skipped-cross counters, and the gross-not-net fee disclosure. It also explains that compatibility_codes can be non-empty even when matched_pairs > 0.

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

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

The description is long but deliberately structured with capitalized section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose in the first sentence. Every sentence carries substantive information for a complex cross-venue tool. It is slightly repetitive in places (e.g., reminding 'in EITHER mode' multiple times), but the organization makes it scannable.

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

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

With no output schema and 3 optional parameters, the description carries the full burden of explaining return values and edge cases, and it does so exhaustively. It specifies the response shape (leg-by-leg prices, top_spreads_pp in percentage points), defines all safety codes, explains null semantics for temporal alignment, and explicitly states that spreads are gross not net tradeable edge. An agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema. It explains that `topic` selects from 10 named shortcuts, that the explicit event ticker/slug overrides the topic-mapped side, and that both modes run the identical token-overlap matcher. This gives the agent actionable guidance on how the parameters interact.

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 opens with a precise definition — 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — naming the exact resource and computation. It also differentiates itself from single-venue siblings (polymarket_edges, polymarket_arbitrage) by emphasizing the cross-venue nature and by listing its two operation modes.

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 context for when to use the tool: the `topic` mode for pre-mapped macro shortcuts and the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode for custom pairings. It also cautions that most pre-mapped topics return compatibility warnings and that pre-mapped does not equal tradeable. However, it does not explicitly name alternative tools or state when NOT to use this tool versus a sibling.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which the description reinforces by describing a non-destructive retrieval operation. The description adds context about scoping and the dual behavior (single key vs. list all). 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 three sentences with no waste. Each sentence serves a purpose: defining the action, giving use cases, and explaining scoping and related tools. Well structured and front-loaded with the key behavior.

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

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

Given one optional parameter and no output schema, the description adequately explains the two return modes and scoping. It could mention the return format (e.g., value or list), but overall it is complete for this simple tool.

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

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

The single optional parameter 'key' is documented in the schema, and the description adds meaning by explaining the behavior when omitted: 'omit the key argument to list all keys.' Schema coverage is 100%, and the description provides useful context beyond the schema.

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

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

The description clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes from siblings like remember and forget by describing when to use each, and provides concrete examples of stored context.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier') and mentions pairing with remember and forget. It does not explicitly state exclusions, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return field details, mark_read side effect, and polling suitability, enhancing transparency 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?

Three sentences, each earning its place: purpose, return structure, filtering and mark_read behavior, alternative endpoint. Front-loaded and concise with no extraneous text.

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

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

No output schema, so description compensates by describing return fields (source, citation_uri, raw payload). Parameters are covered with examples and behavioral context. Includes polling guidance and alternative access method, making it complete for a read-only, idempotent 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%, and description adds value with examples (type 'sec_8k', ISO timestamp) and behavioral explanation for mark_read. However, 'limit' and 'unread_only' parameters are not elaborated beyond schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, listing returned fields (source, citation_uri, raw payload). It provides a clear verb and resource, but does not explicitly differentiate from sibling tools like list_subscriptions or recent_changes.

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?

Gives specific usage guidance: filtering by type and since, using mark_read for read tracking, and noting polling works fine. Provides context but lacks explicit when-not-to-use or alternative tool recommendations.

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, etc.), the description details the fan-out to multiple sources, the GDELT→GNews fallback, USPTO soft-fail, and the return structure. This adds significant behavioral context without contradiction.

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

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

The description is a single efficient paragraph that front-loads the purpose with example queries, then covers sources, parameters, return format, and the sibling tool note. Every sentence contributes distinct information, with no wasted words.

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

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

Despite no output schema, the description covers the return structure (changes, total_changes, citation URIs), source behavior, parameter semantics, and provides a usage guideline. The tool's complexity is fully addressed.

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 explaining the `since` parameter's formats (ISO date, relative shorthand) with examples, clarifying `type` is limited to 'company', and specifying `value` can be ticker or CIK. 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 clearly states the tool returns a change feed for a company in a time window, with specific verb+resource from example queries. It distinguishes from the sibling entity_profile, making the purpose unambiguous.

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

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

Explicitly says when to use (change feed) and when not to (static profile), naming the alternative tool (entity_profile). Provides example queries that help the agent identify usage scenarios.

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

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

Annotations declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which align with the description's claim of a non-destructive write operation. The description adds valuable behavioral context: memory is key-value scoped by identifier, authenticated users get persistent memory, anonymous sessions retain 24 hours.

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 concise, well-structured paragraph. It front-loads the core purpose, then gives usage guidelines, and ends with behavioral details. No unnecessary words or repetition.

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

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

Given the tool's low complexity (2 parameters, no output schema, no nested objects), the description covers all essential aspects: purpose, usage, storage behavior, scoping, persistence, and companion tools. 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% and the description already explains the key-value pair concept. The description adds examples of key naming conventions (e.g., 'subject_property', 'target_ticker'), which provides extra semantic guidance.

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 saves data for later reuse and provides concrete examples (resolved ticker, target address, user preference, research subject). It also distinguishes from sibling tools 'recall' and 'forget' by naming them as companions.

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

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

Clearly specifies when to use ('when you discover something worth carrying forward') and explicitly mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

The description goes well beyond the annotations by disclosing key behaviors: it returns figi_candidates and asserts nothing on ambiguous matches, labels identifiers by source, states unresolved identifiers explicitly, and degrades gracefully if LEI/FIGI enrichment is unavailable. This is exactly the kind of behavioral context an agent needs and the annotations do not provide.

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

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

The description is dense and front-loaded with query examples and the core purpose. Although it is long, nearly every sentence carries useful information, including edge-case behavior and supported sources. It slightly over-elaborates inside long parentheticals, but remains organized and readable.

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 thoroughly explains what the agent should expect: source-labelled identifiers, an unresolved array, ambiguous figi_candidates, and graceful degradation. It also enumerates accepted input forms for both entity types and gives explicit value-format guidance. Nothing critical is missing for correct invocation.

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

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

The schema already covers both parameters at 100%, but the description adds meaning beyond the schema: it documents that 'company' also accepts ISINs and explains that non-US issuers resolve via GLEIF, and it gives brand/generic examples for 'drug'. It also explains why the value should be only the entity name, which helps prevent incorrect bond lookups.

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-plus-resource framing: it resolves a user-spoken NAME into canonical/official identifiers that other tools need, and it explicitly distinguishes itself from siblings by naming supported entity types. It also includes concrete query examples ('ticker for…', 'CIK for…'), which makes the purpose immediately recognizable.

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

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

It gives an explicit usage rule — 'Use FIRST whenever you have a name but need an ID' — and clarifies that it replaces 2–3 manual lookups. However, it does not name sibling tools as alternatives or state when NOT to use this tool, so there is room for more explicit exclusion guidance.

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

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

The description adds context beyond annotations: reveals internal call to ai_visibility_check, describes ranking and output format. Annotations already indicate readOnly, idempotent, etc., so description complements well without contradiction.

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

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

Two sentences that pack purpose, mechanism, use case, and output summary without fluff. 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, description adequately explains return: ranked list with score, confidence, signal density. Covers prerequisites, use case, and what the tool produces.

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 useful context for models ('supported models'), _apiKey ('passed to api.anthropic.com'), and context ('disambiguates common names'). Briefly explains entities as subject vs competitors.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and ranks results. It distinguishes from sibling tools that operate on single entities (e.g., ai_visibility_check).

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 a concrete use case ('does Claude know about us as well as our competitors?') and implies when to use this over ai_visibility_check (multiple entities). Could be more explicit about when not to use, but overall 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. It also details return data including summary, per-advisory detail, links, and alternative versions. 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 information-dense and each sentence adds value. However, it is a single long paragraph; better structural formatting (e.g., bullet points) could improve readability without losing content.

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 (composite with multiple sources, potential failures), the description covers key aspects: purpose, usage, behavioral traits, edge cases (partial failures), and return structure. No output schema, but the description adequately describes output components.

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

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

Schema description coverage is 100% with both parameters well-described. The description adds that package accepts scoped packages and version defaults to latest, but this is minimal additional context. Baseline 3 is appropriate as schema does the heavy lifting.

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, combining deps.dev and bundlephobia data. It specifies the verb 'scan' with the resource 'dependency' and distinguishes itself from sibling tools that focus on other domains.

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"'. Also specifies limitations: NPM ecosystem only and for other ecosystems use deps.dev directly, providing clear when-to-use and when-not-to.

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?

Disclosure extends beyond annotations, detailing embedding model (BGE-base-en), window size (500-char overlapping), token limit (200K char truncation with flag), and output structure (character offsets, similarity scores). 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?

Compact yet comprehensive. Front-loaded with core purpose, then usage guidance, then technical details. Every sentence adds value with no redundancy.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and scores) and covers all key aspects: input, behavior, limits, and integration with sibling tool. Complete for a 3-parameter 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%. Description adds practical meaning: text param explained as document text with max chars, limit param with default and range, query with natural-language examples. Adds value beyond schema.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes from sibling tools like ask_pipeworx_grounded. It clearly defines the action, input, and output.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. Clearly states when and how to use the tool.

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

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

Discloses beyond annotations: returning subscription id, persistence requirement, webhook auto-disable after 10 failures. Covers key behavioral traits but could mention general rate limits.

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

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

Front-loaded with core purpose, then details. A bit lengthy but every sentence provides value. Minor redundancy (e.g., phone verification mentioned twice) could be trimmed.

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

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

Given complexity (3 params, nested objects, no output schema), description covers return value, all parameters with examples, authentication requirements, and delivery channel behaviors. Complete for a subscription creation tool.

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

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

Adds significant meaning beyond schema: provides type-specific examples (e.g., sec_8k items), delivery channel details, and required phone verification context. Fully compensates for any schema gaps.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', with explicit return value. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states OAuth requirement and lists supported types with channel constraints (e.g., SMS cap, phone verification). Does not explicitly name alternatives but provides sufficient context for when to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the return format (category-bucketed examples with tool+argument shape) and the effect of the topic parameter, without contradicting annotations.

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

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

The description is informative and front-loaded with purpose, but it is somewhat verbose. Every sentence contributes value, but it could be slightly more concise without losing meaning.

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

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

Despite lacking an output schema, the description thoroughly explains the return format, parameter behavior, and usage context. It is complete for a simple onboarding tool with good annotations.

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

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

The schema coverage is 100%, and the description adds meaning by listing possible topic values and explaining that omitting the parameter gives a full cross-category spread. This adds value beyond the schema alone.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx and serves as an onboarding entry point. It distinguishes itself from sibling tools like ask_pipeworx by focusing on suggestions rather than direct queries.

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

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

The description explicitly says to use this tool first when unsure what Pipeworx can do and to learn how to call meta-tools. It provides clear context but does not explicitly state when not to use it or mention 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?

Adds significant behavioral context beyond annotations: 'Ownership is enforced', 'row is deactivated (not deleted)', and 'historical events stay available via recent_alerts'. Annotations indicate non-destructive and idempotent, which aligns with description.

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

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

Two sentences, no wasted words. Front-loaded with action, followed by constraints and side effects. Highly efficient and clear.

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

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

Completely covers purpose, constraints, side effects, and references sibling tool for historical view. Given single parameter and no output schema, no additional information is 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?

Only one parameter 'id' with schema description already clear. Description adds 'by id' but does not provide additional meaning beyond schema. Schema coverage is 100%, so baseline 3 applies.

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

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

Clearly states 'Cancel a subscription by id' with specific verb (cancel) and resource (subscription). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by adding ownership and deactivation details.

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 (cancel own subscription by id) and important constraints (ownership enforced, only own subscriptions). Provides context on what happens (deactivation not deletion) and mentions sibling 'recent_alerts' for historical events.

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 annotations already declare read-only, open-world, and idempotent behavior. The description adds significant transparency beyond that: it details the two pipelines, discloses failure modes (could_not_verify with verification_error), clarifies that could_not_verify is NOT evidence, and explains the meaning of unsupported. This directly prevents misuse and goes far beyond the structured 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 lengthy but well-structured: it opens with example phrases, states the core usage, explains pipelines, return values, and important caveats. Every section serves a purpose given the tool's complexity. While not minimal, it avoids fluff and is appropriately sized for the range of behaviors it must cover.

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

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

With no output schema, the description fully covers return values (verdicts, citation, reasoning), explains error semantics, and outlines the routing logic. It also accounts for the tool's safety profile via annotations. The description is complete enough for an agent to invoke the tool correctly and interpret results without ambiguity.

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

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

Schema description coverage is 100%, so the schema already fully documents both 'claim' and 'tolerance_pct' with examples and default behavior. The description does not add any parameter-specific meaning; it mentions 'exact percent-delta math' but does not elaborate on the parameters themselves. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources, returning verdicts. It uses specific verbs like 'check', 'verify', and 'confirm or refute', and distinguishes itself from sibling tools by focusing on fact-checking with structured verdicts rather than general search or research. The examples of invocation phrases make the purpose immediately actionable.

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 it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two verification paths (company-financial vs. other claims) and notes that it 'replaces 4–6 sequential calls,' implying a preference over multi-step alternatives. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the highest bar.

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