Bitfinex

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: default model is free, optional Anthropic probing requires BYO key with direct payment, and returns per-model structure. This goes beyond the annotations without contradicting them.

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

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

Four sentences, front-loaded with the core action, followed by key details and use cases. No filler or redundancy. 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?

The description effectively covers the tool's essential context: purpose, default behavior, cost implications, return format, and typical use cases. Since there's no output schema, the description's mention of per-model fields and combined view is important and well-handled. Sibling overlap or advanced nuances aren't addressed, but the overall completeness is strong for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the default model behavior and mention of `_apiKey` pass-through, but adds little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility. It specifies a concrete action and resource, but doesn't explicitly differentiate from similar siblings like scan_competitor_ai_presence, so it earns a 4 rather than 5.

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 clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs optional model choice. It doesn't explicitly say when not to use it, but the context is sufficient for an agent to decide. No exclusions or alternatives mentioned, so not a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context beyond annotations: it routes to 5,529 tools, fills arguments, returns stable citation URIs, and is described as 'one fast call'. It does not contradict annotations, and the additional context helps the agent anticipate routing behavior and output format.

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 key guidance and well-structured, but it is quite long (about 250 words) with a long list of examples and repeated usage guidance. While every sentence contributes information, it could be tightened without losing value. It is not as concise as ideal for an AI agent to quickly parse.

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

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

There is no output schema, so the description must explain return values, which it does ('returns the structured answer with stable pipeworx:// citation URIs'). It also covers routing, use cases, alternatives, and performance ('one fast call'). For a tool of this complexity (router to 5,529 tools), the description is remarkably complete.

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

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

Schema coverage is 100%, and the schema already describes the 'question' parameter and its aliases. The description does not add any new parameter-level semantics beyond examples of possible questions. It meets the baseline of 3 because the schema handles parameter documentation, but no extra value is added.

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: to answer factual questions by routing to relevant sources and returning structured answers with citations. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' and resource 'pipeworx' are clear, and the scope is precisely defined with examples.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' for ask_pipeworx_grounded or deep_research. It also covers breaking-news cases. This is exemplary usage differentiation.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals critical experimental behavior: candidate routing improvements may be enabled live, currently no candidate is active so it matches stable, and it 'falls back to nothing' confirming it is a full working router. This volatility is essential for the agent to expect potential behavioral differences.

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

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

The description is concise and well-structured, with each sentence delivering distinct information: the beta relationship, current operational state, usage instruction, and confirmation that it is a full router. It is front-loaded with the core definition and contains no fluff.

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

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

Given the tool's experimental nature, the description covers all necessary context: what it is, how it relates to the stable version, current state, usage guidance, and how results are evaluated. With no output schema, it still provides enough information for an agent to use it correctly.

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

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

The input schema fully documents all six parameters (question and its five aliases), so schema description coverage is 100%. The description adds no extra parameter meaning, so the baseline score of 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?

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with 5,529 tools and the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental routing improvements, 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?

The description explicitly tells agents to use it 'exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. This provides a clear condition for use, though it does not explicitly state when not to use it or mention alternatives beyond ask_pipeworx.

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, openWorld, idempotent, non-destructive), the description discloses extra LLM call cost, exact success/refusal response shapes, and the refusal_reason enum values. It adds meaningful context about evidence verbatim quotes and data truncation 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 longer than average but highly information-dense; every sentence covers a unique aspect: purpose, routing, extraction, response format, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured logically.

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

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

Despite lacking an output schema, the description fully specifies return values, success/refusal structures, refusal reason values, and practical usage guidance. It gives an agent everything needed to select and invoke the tool correctly, including tradeoffs versus the sibling 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 question parameter and all aliases with 100% coverage, so the description need not add parameter details. It adds no extra semantics beyond the schema, making the baseline score of 3 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 identifies a grounded, hallucination-resistant answer mode that routes through PipeWorx tools and extracts answers only from tool results. It distinguishes itself from ask_pipeworx by emphasizing extraction, evidence, and refusal behavior, making its 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?

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on... must not invent facts.' It also gives a clear alternative and exclusion: 'prefer ask_pipeworx for casual lookups,' and quantifies the cost tradeoff of one extra LLM call.

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 readOnlyHint annotation, disclosing resolver contract details (match confidence, match score, alternatives), blocking statuses like 'low_confidence_match' and 'market_closed_or_inactive', tradeability flags, and resolution-rule risk. This rich behavioral context helps the agent anticipate edge cases and trust the output, exceeding the baseline set by 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 long but extremely well-structured with clear headings like CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, and RESOLVER CONTRACT. The first sentence immediately states the purpose, and every section adds operational value, though the sheer length makes it slightly less concise than ideal.

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, no output schema, and rich annotations, the description is remarkably complete. It covers response shapes, resolver behavior, parent-event extraction, news fallback fields, safety mechanisms, and resolution-rule risk, leaving almost no ambiguity about what the agent can expect.

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 covers 100% of parameters with descriptions, including the enum 'depth' and the 'include_raw' flag with defaults. The description adds some examples for 'market' input and mentions fan-out behavior, but it does not substantially enhance the parameter semantics beyond what the schema already provides, so a 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 opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', which is a specific verb+resource statement that clearly distinguishes this from siblings. It further clarifies the input types and fan-out behavior, making the tool's 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?

The description explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear context for when to invoke the tool. However, it does not name alternatives or explicitly state when not to use it, so it falls short of a 5 on this dimension.

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, so the safety profile is covered. The description adds the return format (price levels with size + count) and emphasizes 'live' data, but does not disclose behavior like default length, precision semantics, or error handling. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the core purpose, followed by return format and usage. Every sentence earns its place with no redundant or filler 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?

Despite having annotations and an output schema, the input schema is bare and the description fails to explain key parameters and behavioral defaults. The tool is moderately complex (3 params), and the description only addresses the purpose and usage, leaving significant gaps in how to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It only hints at the meaning of 'symbol' via the example 'tBTCUSD', and completely fails to explain 'length' and 'precision'. The example in the schema (length:25, precision:'P0') is not elaborated, leaving the agent without necessary parameter semantics.

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 returning the Bitfinex order book (bids + asks) for a specific crypto pair, with a concrete example. It distinguishes itself from sibling market data tools (e.g., ticker, trades, candles) by specifying depth-of-book data with price levels, size, and count.

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

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

The description provides explicit use cases: 'live depth-of-book analysis, spread, market microstructure.' This gives clear context for when to use the tool, though it does not mention when not to use it or point to alternatives, which would earn a 5.

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 read-only, idempotent, non-destructive behavior. The description adds value by disclosing the return format (timestamped OHLCV) and timeframe range (1m through 1M), which supplements the structured metadata without contradicting it.

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

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

Two sentences, front-loaded with the core purpose, and every word earns its place. No fluff 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?

Despite good annotations and an output schema, the description is incomplete for input construction. The required 'section' parameter remains ambiguous, and no guidance is given on how to specify historical vs. latest data. This makes reliable invocation difficult without external examples.

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 0%, so the description must compensate. It only mentions the timeframe range and does not explain the required 'section' parameter, nor start/end/limit/sort. With 7 parameters, this is a significant gap.

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 OHLC candles for Bitfinex crypto pairs and mentions specific use cases like charting and backtesting. It does not explicitly distinguish from sibling tools like ticker or trades, but the resource and verb are specific enough.

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

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

The description explicitly states when to use: 'Use for charting, technical analysis, backtesting on Bitfinex.' This provides clear context, though it does not mention exclusions or alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and citation URIs in the response. This goes well beyond the annotations.

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

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

Although slightly longer than typical, every sentence carries substantive information—trigger phrases, usage priority, data sourcing, sorting behavior, and efficiency benefit. It is well-structured and front-loaded, with no 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?

Given no output schema, the description adequately explains the return format (paired data, citation URIs). It covers both entity types, the range of inputs, and the efficiency gain, making it complete for a tool of this complexity.

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

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

Although the schema covers both parameters with descriptions (100% coverage), the description adds deep semantic value: it explains exactly what data each type pulls (e.g., 10-K revenue/net income for companies, FAERS counts for drugs) and clarifies the expected formats for both parameters.

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 2–5 companies or drugs in a single call, with specific verbs ('compare', 'rank') and resource scope. It distinguishes itself from sibling tools by explicitly positioning it over sequential single-entity 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 trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger') and an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This leaves no ambiguity about when to use it versus alternatives.

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

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

The description adds substantial behavioral context beyond annotations: account/auth requirements, depth tier differences, gaps[] for unanswered facets, 'never invented' assurance, contradictions[] scanning, excerpting behavior, latency ranges, and citation_uri presence rules. These disclosures are rich and align with annotations (readOnly, openWorld, idempotent).

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 every sentence contributes unique information, and it is front-loaded with the critical account requirement. The structure uses semicolons and clauses to pack details without redundancy. Slight verbosity exists, but it is justified given the tool's complexity.

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

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

For a complex tool with no output schema, the description thoroughly covers return format (findings packet with evidence, confidence, source, citations, gaps[]), behavioral expectations, and edge cases (e.g., news topics yielding empty gaps). It provides enough context for an agent to invoke 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 covers 100% of parameters, so baseline is 3. The description goes beyond by explaining what each depth level does (gap recovery, contradictions scan) and clarifies the question parameter supports broad/multi-part queries. This adds meaningful context without repeating schema details.

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 function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition into facets and parallel routing. It explicitly differentiates from ask_pipeworx for single lookups and current news, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also states the account requirement and fallback for non-signed-in users, making usage conditions very 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond these, such as whether the status is current, delayed, or what actions are safe. It neither contradicts the annotations nor enhances 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 extremely short (three words) but under-specifies the tool's capabilities. It is concise in the sense of being short, but not well-structured or informative; it reads as a fragment rather than a meaningful sentence, lacking the detail needed for reliable invocation.

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

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

Despite having an output schema and supportive annotations, the description is too minimal to be complete. It fails to clarify what 'status' covers, how to format queries, or how it relates to sibling tools. The agent would be left uncertain about the tool's behavior and 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 schema has no description for 'keys', and schema description coverage is 0%. The tool description also fails to explain the parameter. While the schema example 'pBTCUSD,pETHUSD' hints at a comma-separated list of contract symbols, the description itself provides no meaning, placing full burden on the schema's sparse example.

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 'Perpetual contract status' is a noun phrase that restates the tool's title without specifying an action. It does not indicate whether the tool retrieves, checks, or lists status information, nor does it distinguish itself from siblings like derivatives_status_history or liquidations.

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 no guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions, leaving the agent to guess when 'perpetual contract status' is the appropriate choice.

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, so the agent knows it is a safe read operation. The description adds no behavioral context beyond what annotations provide—no mention of time ranges, pagination, or sorting. It does not contradict annotations, but it also does not add value.

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

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

The description is extremely concise—three words—and front-loaded. However, it is under-specified to the point of being almost terse. It contains no wasted words, but also no substantive 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?

With 5 parameters, 0% schema coverage, and no output schema details visible, the description is insufficient for an agent to correctly invoke the tool. The annotations confirm it is read-only, but the agent still needs parameter semantics and usage context. It is far from 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 0% and the description does not explain any of the 5 parameters (key, start, end, limit, sort). The agent has no idea what 'key' refers to (presumably a platform identifier) or how start/end/limit/sort behave. The description entirely fails to compensate for the lack of 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 'Historical derivatives status' clearly indicates it provides status information for derivatives, and 'Historical' distinguishes it from the sibling tool derivatives_status. However, it lacks an explicit verb (e.g., 'get', 'list'), making it a noun phrase rather than a specific action.

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 no guidance on when to use this tool versus alternatives. It does not mention derivatives_status or any conditions for using historical data. The 'Historical' prefix implies it is for past status, but there is no explicit when-to-use or exclusion.

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 annotations (readOnlyHint=true, idempotentHint=true), the description discloses key behavior: returns top-N tools with full input schemas and curated examples, ready to call directly. This adds useful context about the return format and eliminates a second lookup step. 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 long but front-loaded with the core purpose and contains no filler. Each sentence serves a purpose: what it does, when to use, what it returns, and the 'call first' guidance. The domain list is extensive but directly relevant to the tool's scope.

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

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

Given the absence of an output schema, the description fully specifies the return value: names, descriptions, full input schemas with examples, and readiness to call. It also covers the use case and scope. For a discovery tool, this is comprehensive and leaves no major 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 description coverage is 100%, so the baseline is 3. The description does not add extra meaning to parameters beyond what the schema already provides (e.g., query, limit, aliases). It mentions 'top-N' which aligns with the limit parameter, but this is minimally additive.

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 verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from the siblings, which are specific data/analysis tools, by positioning it as a discovery/search tool. The list of domains and return format further clarify its purpose.

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

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

Explicitly states when to use ('Use when you need to browse, search, look up, or discover what tools exist') and gives a directive to 'Call this FIRST' when many tools are available. It doesn't name specific alternative tools or state when NOT to use it, but the 'first step' guidance strongly implies a workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds transparency about the USPTO PatentsView API sunset in May 2025 and that the patents component 'soft-fails until reactivated'. It also discloses the parallelism ('in ONE parallel call') and the GDELT→GNews fallback chain. However, it does not mention potential rate limits or exact response format, though with good annotation coverage this is a minor gap.

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

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

The description is dense but packed with useful information. It front-loads the purpose with example questions, then lists data sources and output fields. It's a long sentence but each clause earns its place. The only minor issue is that the list of example queries could be shortened without losing meaning, but overall it is structured logically and efficiently.

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

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

Given no output schema, the description does an excellent job explaining what the tool returns: cik, company_name, recent_filings (with URIs), fundamentals (specific metrics), patents (with sunset note), news via GDELT→GNews, and LEI via GLEIF. It covers input constraints (names not supported) and sources. For a read-only info retrieval tool with good annotations and full param coverage, this 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 description coverage is 100%, so the parameters are already well-documented in the schema. The description adds further value by explaining the 'zero-padded CIK' requirement and giving concrete examples ('AAPL', '0000320193'). It also clarifies the 'type' enum is limited to 'company' and mentions person/place are coming soon. This goes beyond the schema, earning above the baseline of 3.

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

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

The description uses specific verbs ('tell me about', 'research', 'brief me', 'company profile') and clearly names the resource: a full cross-source profile of a US public company. It explicitly lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and the exact output fields, distinguishing it from sibling tools like resolve_entity or ticker. The scope is immediately clear.

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

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

The description provides explicit when-to-use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the alternative: 'use resolve_entity first if you only have a name.' It states what inputs are supported (ticker or CIK) and what is not (names). This is a textbook example of usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the basic behavioral profile is known. The description adds contextual use cases (clearing sensitive data) but no additional behavioral traits such as irreversibility or side effects beyond what annotations imply. This is consistent with annotations.

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

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

Two sentences with no fluff. The action is front-loaded, the use cases are efficiently listed, and the sibling pairing adds useful context in a compact way.

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 destructive tool with good annotations and no output schema, the description covers purpose, usage, and relation to siblings. It could add a note about irrevocability, but that's already implied by destructiveHint, so this is complete enough.

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

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

The input schema has 100% coverage: the 'key' parameter is described as 'Memory key to delete'. The description's 'by key' merely repeats what the schema already provides, so it adds no new semantic meaning. 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 starts with a specific verb ('Delete') and resource ('previously stored memory by key'), making the tool's function immediately clear. It also distinguishes itself from sibling tools by noting it pairs with 'remember and recall', which clarifies its role in the memory workflow.

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 guidance: 'context is stale', 'task is done', or 'clear sensitive data'. It mentions pairing with sibling tools but doesn't explicitly state when not to use it or name direct alternatives, so it falls just short of a 5.

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?

It describes the internal process: fetches the page, extracts title/description/key links, and emits standard markdown. This adds behavioral context beyond the annotations, such as the output being a single text blob ready to drop at site-root/llms.txt.

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

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

Three concise sentences with no fluff. The main action is front-loaded, and every sentence adds value: purpose, process, and use cases.

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 two-parameter tool with good annotations and no output schema, the description explains what it does, how it works, and what the output looks like, covering all essential context sufficiently.

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 with full descriptions (100% coverage). The description does not add parameter-specific details, so it stays at the baseline for schema-covered parameters.

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 verb+resource: 'Generate a production-ready llms.txt file for any URL.' It also clarifies the audience (AI crawlers) and output format, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description explicitly lists three use cases: client indexing, drafting for own project, and competitor audit. It provides clear context for when to use the tool, though it doesn't mention exclusions or compare directly with alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by specifying it pertains to forced margin liquidations, the data fields per row (pair symbol, timestamp, size, price), and the optional filter parameters. This goes beyond the annotations and clarifies the nature of the data.

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

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

The description is two sentences, front-loaded with the most critical information (what it is and the endpoint), followed by data row details and parameters. Every word contributes value; no fluff 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 the tool's simplicity, the presence of an output schema, and strong annotations, the description provides sufficient context: what data is returned, what question it answers, and the available filters. It lacks explicit details on sort order semantics or pagination, but these are minor gaps for a historical feed with optional parameters.

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 has no parameter descriptions (0% coverage), so the description must compensate. It names all four parameters (start, end, limit, sort) and gives units for start/end as 'ms epoch'. However, it does not explicitly explain what each parameter does (e.g., start/end as range, limit as row count, sort as ordering) beyond implying they are options. The example in the schema (sort: -1, limit: 20) provides a hint but not full semantics.

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 the 'historical feed of forced margin liquidations across Bitfinex pairs' and explicitly answers which positions got liquidated, when, and at what price. This distinguishes it from sibling tools like trades or candles by focusing specifically on liquidations.

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 (historical liquidation data on Bitfinex) but does not explicitly mention when not to use it or name alternatives. The scope is well-defined enough that an agent would understand its purpose, but it stops short of explicit exclusions or comparisons.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context like returning specific fields and the 'active' filter, but it does not disclose additional behavioral traits (e.g., pagination, response format) beyond what annotations and schema provide. No contradiction exists.

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

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

The description is two sentences: the first states the purpose, the second lists return fields and use cases. Every sentence adds value, no fluff, and it is appropriately sized for a simple tool.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers all essential aspects: scope, return fields, and practical use cases. Combined with strong annotations, the context is complete for an agent to select and invoke 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 description coverage is 100%, with the sole parameter 'include_inactive' already explained in the schema. The description does not add further meaning about the parameter, so the baseline of 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?

The description uses a specific verb ('List') and resource ('subscriptions') with a clear scope ('caller's active subscriptions'). It also enumerates the return fields, making the tool's function unmistakable and distinguishing 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?

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' However, it does not explicitly mention when not to use this tool or name alternatives, so it stops short of the highest level of 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?

Beyond the annotations (which only indicate readOnly=false), the description discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token workflow for reading replies, cost ('Free; doesn't count against your tool-call quota'), and the team's daily digest reading. This is rich behavioral context.

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

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

The description is lengthy but each sentence adds distinct value: purpose, use cases, exclusions, claim_token mechanics, rate limits, pricing. It's front-loaded with the core purpose and efficiently packs a lot of guidance into a single paragraph, though it could use structural breaks.

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 explains return behavior: filing 'returns a `claim_token`' and reading 'returns the status and, once resolved, what actually changed.' It also covers scope, limitations, and the dual-mode operation, making it fully self-contained.

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

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

The input schema already has 100% coverage with descriptions for all four parameters. The description adds extra semantics for claim_token by giving a concrete usage example: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' It also clarifies that no parameters are required, which is helpful for the read-flow.

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 function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by specifying it's for feedback about Pipeworx tools only, contrasting with ask_pipeworx or other tools, and even clarifies not to use for other MCP servers.

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 conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.'

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 destructiveHint false, but the description adds rich behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs agents about data source, privacy, and staleness, going well 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 compact and well-structured: a one-sentence summary, a numbered usage list, and a brief data-source/caching note. Every sentence earns its place with no filler 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?

For a simple tool with one optional parameter and no output schema, the description covers the return content, time windows, use cases, data derivation, and caching behavior. This is complete for the tool's complexity.

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

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

The schema covers 100% of parameters with a descriptive enum for 'window' explaining shorter vs. longer windows. The description reiterates the window options but adds no new parameter-level information, so the baseline score of 3 is appropriate.

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

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

The description opens with 'What other AI agents are calling on Pipeworx right now' and specifies it 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. This clearly states the verb and resource, and distinguishes it from siblings like discover_tools by focusing on agent usage trends.

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 numbered 'Useful for' list with three specific use cases, and contrasts window options with 'Shorter windows surface what's hot right now; longer windows show steady-state demand'. This gives clear context for when to use the tool, though it does not explicitly name alternative tools or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey that this is a safe read operation. However, the description adds no behavioral context (e.g., what status is checked, whether it reflects the current state, or any side effects). It neither contradicts nor enriches the annotations, so it falls short of the baseline for meaningful transparency.

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

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

The description is a single two-word fragment that is under-specified rather than concise. It does not provide enough information to be useful, and its brevity is a form of incompleteness, not efficient writing. A well-structured description would at least include a verb and clarify the scope of 'status'.

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

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

Given the tool's simplicity (0 params, output schema exists), the description should clarify what 'platform status' returns or covers. It does not. The annotations and output schema are available but the description fails to connect them or provide any real-world context. This is a clear gap for an otherwise minimal 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 tool has zero parameters and the schema is empty, so the baseline score is 4. There is no parameter information to document, and the description does not need to compensate for any missing schema coverage. The empty schema and description align perfectly.

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 is 'Platform status.', which is a direct restatement of the tool name and title. It lacks a specific verb or resource description, and does not differentiate from sibling tools like 'derivatives_status' or 'stats'. This is a tautology rather than a meaningful purpose statement.

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 no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply asserts a state without explaining the context in which 'platform status' is useful. The agent is left to infer any usage conditions from the tool name alone.

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 readOnly/openWorld/idempotent annotations, the description discloses important behaviors: no-arg default scan scope, per-event partition_check logic, cross-event similarity threshold (≥0.30 Jaccard), placeholder filter, fill-check mechanics against CLOB depth, and the meaning of realizable_edge_pp ≤ 0. 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 long but highly structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds technical value; it could be slightly tightened but the density justifies the length for a tool with this many behavioral modes.

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

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

The tool has no output schema, so the description compensates by detailing response fields (opportunities[], partition_check{}, placeholders_filtered, thin_legs[]). It covers all operational states: no-arg, event, topic, fill-check failure, and placeholder edge cases. Given the tool's complexity, this is fully specified.

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?

While schema descriptions already cover both parameters, the tool description adds substantial semantics: it explains what each mode does internally (walks child markets, checks ordering, sums YES prices), provides concrete examples of valid slugs, and clarifies nuances like cross-event catching May 31 vs Jun 30 patterns. This far exceeds the schema's baseline.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by naming the detection techniques and upstream tool for 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?

Provides explicit usage modes: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also names an alternative: 'For custom sizing use polymarket_fill_risk.' Event vs topic selection is explained with recommendations and examples, making when-to-use unambiguous.

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 this as read-only, idempotent, and open-world. The description adds extensive behavioral context: how the three model families work, the output structure, the tradeable-edge knobs, the exclusion of Fed bets due to unreliable signals, the 24h-move warning, and even the caching behavior. This is far beyond the annotations.

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

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

The description is a single dense block of text, approximately 500 words, with no section breaks or bullets. It repeats default values already present in the schema (e.g., slippage_pp 0.3, min_edge_pp 0.5) and includes overly specific model details (per-sport α values) that may not be necessary for tool selection. This makes it harder to scan and parse.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the response contract (by_segment, fed_candidates, _diagnostics), the meaning of key fields, the effect of each knob, and even the caching key. An agent has enough information to call this tool correctly and interpret results.

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

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

Even though the schema covers 100% of parameters, the description adds crucial interplay details: how min_partition_leg_kelly applies to per-leg Kelly inside top_legs because parent Kelly is always 0, how slippage_pp is subtracted before ranking, and what min_liquidity/max_spread_pp filter. It also gives practical guidance like 'Bump for very thin partitions' and 'Set to 2 to require tight books.'

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also provides a use case ('what should I bet on today') that distinguishes it from other Polymarket tools like arbitrage or fill risk.

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

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

The description gives clear context for when to use the tool: when agents want to discover betting opportunities without paging hundreds of markets. It also explains the response structure and filtering knobs. However, it does not explicitly mention alternative tools or when not to use it, though the purpose is distinct enough.

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

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

Even with readOnlyHint/openWorldHint/idempotentHint annotations, the description adds substantial non-obvious behavior: tracked[] and expired[] categories, derived trend/decay fields, snapshot gaps caused by cache-misses, signed edge_pp_net values, and the 60-day TTL limit. 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 long but every paragraph earns its place: purpose, parameter recap, response contract, and data caveats. It is front-loaded with the core question and structured via ALL-CAPS labels ('RESPONSE', 'LIMITS'), making it scannable despite density.

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 enumerates the response format, explains edge cases like expired opportunities and missing snapshot dates, and documents limitations of TTL and daily-close decay. The agent can invoke the tool confidently without additional documentation.

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

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

Both days and window are fully described in the schema with defaults and allowed values; the description largely restates these (lookback, default 14/max 30, snapshot family). It adds no extra semantics or format details beyond what the schema already provides, so the baseline score of 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?

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses the exact question it answers, making the verb/resource relationship explicit. By contrasting fresh vs old wide edges, it also differentiates from the sibling polymarket_edges tool that surfaces current edges.

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

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

It provides clear context for when the tool is relevant—whenever edge age/decay matters rather than the current snapshot—and links to the underlying polymarket_edges snapshot pipeline. It does not explicitly name an alternative tool or state when not to use it, so it falls short of full prescriptive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial context: it lists exact returned fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains mode-specific behavior (walking the ladder, settlement notional), and discloses the risk of forced directional risk in baskets. 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?

The description is long but every section earns its place. It is tightly structured with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS. The core purpose is front-loaded in the first sentence, and the rest uses dense, precise language without fluff.

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

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

This is a two-mode, complex tool with no output schema. The description compensates fully by enumerating all return values for both modes, explaining edge cases (thin_legs, forced_directional_risk, max_clean_notional_usd), and giving a threshold for when to use it. Nothing important is missing.

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

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

Even though schema coverage is 100%, the description enriches each parameter's meaning. For size_usd it distinguishes 'max spend on buys, target proceeds on sells' and in basket mode 'settlement notional S (shares per leg).' It explains default behavior for side in basket mode (auto from partition sum) and the clamp range. This is far 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 opens with a specific, vivid definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates two modes (single-market and basket) and explicitly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges as the tools to precede.

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, actionable guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround is not capturable on thin books) and warns about partial basket fills. This is model guidance with clear alternatives.

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

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

The description adds rich behavioral detail beyond the readOnlyHint annotations: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0), temporal_alignment semantics, skipped_cross_type/subtype explanations, and the explicit statement that aligned:false means 'spreads are mathematically meaningless.' It fully discloses failure modes and limitations, complementing the annotation set with 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?

The description is longer than typical but every sentence carries functional information, including edge-case warnings. It is front-loaded with the core purpose, then modes, then response fields, then safety fields. It uses clear labels and section-like capitalization, making it navigable despite 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?

With no output schema, the description must explain return values, and does so explicitly: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype. It also covers prerequisites (same resolving question), failure modes, and interpretation guidance, making it fully self-contained for a tool of this complexity.

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

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

Schema coverage is 100% for all three parameters, but the description goes beyond the schema by explaining the two-mode behavior, how explicit overrides interact with the topic mapping, and the specific value set for topic (fed, btc, etc.). It provides concrete examples and clarifies the meaning of each parameter in the context of the tool's workflow.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the resource and scope. It distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and explicitly detailing two operating modes (topic shortcuts vs. explicit event pairings).

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 clear context for when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and cautions that 'pre-mapped ≠ tradeable' with a note that most topics return compatibility warnings. However, it does not explicitly contrast this tool with specific alternatives like polymarket_arbitrage or other sibling tools, so it misses the 'when-not-to-use' dimension.

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 destructiveHint false. The description adds valuable behavioral context: scoping to an identifier (IP, key hash, account ID) and the dual-mode behavior (retrieve vs list) when key is omitted. 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?

Three sentences, each contributing meaning: function, usage examples, scoping and lifecycle pairing. No filler or redundancy; front-loaded with the core action.

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 retrieval tool with one optional parameter and no output schema, the description covers operation modes, scope, and relationship to sibling tools. An agent can confidently invoke it correctly without further clarification.

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

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

Schema description coverage is 100% — the property 'key' is described as 'Memory key to retrieve (omit to list all keys)'. The tool description essentially restates this same information, adding no new semantic details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys when the key is omitted. It names the resource type (saved values) and pairs with siblings 'remember' and 'forget', effectively distinguishing its role.

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

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

Explicitly says to use for looking up stored context (ticker, address, research notes) without re-deriving, and directly references 'remember' to save and 'forget' to delete. This provides clear when-to-use context and covers the primary alternatives.

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

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

The description discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the idempotentHint:true and readOnlyHint:true annotations, as marking read changes state and makes repeated calls non-idempotent. Score is 1 due to 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 two sentences, front-loaded with the core action, and every phrase earns its place: purpose, return contents, filters, side effect, and alternative endpoint. 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?

With no output schema, the description appropriately lists key return fields (source, citation_uri, raw event payload) and covers filtering, mark_read, and an alternative access URL. Minor gaps like limit semantics are covered by schema descriptions, so the description is sufficiently complete for typical use.

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

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

Despite 100% schema coverage, the description adds meaning beyond the schema: it gives an example type ('sec_8k'), clarifies 'since' as ISO timestamp, and explains the consequence of mark_read on future calls. This goes above the baseline for high 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?

The description opens with 'Pull fired events from your subscription feed', a specific verb and resource that clearly identifies the tool's function. It distinguishes itself from siblings like list_subscriptions and recent_changes by specifying 'recent alerts' with source, citation_uri, and raw payload.

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 practical context: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This tells the agent when the tool is appropriate and offers an alternative for programmatic access. It doesn't explicitly exclude sibling tools, but the use case is well-defined.

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 annotations (read-only, idempotent, open-world, non-destructive), the description reveals multi-source parallel fan-out, fallback mechanisms, API sunset soft-fail, and the exact return shape (changes[] grouped by source + total_changes + pipeworx:// citation URIs). This gives substantial behavioral context not inferable from annotations alone.

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

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

The description is detailed yet efficient, front-loading query examples for recognition, then systematically covering sources, fallback behavior, parameter semantics, and return format. Every sentence contributes new information without restating schema or annotations.

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 and high complexity (multiple upstream APIs, fallbacks, parameter formats), the description provides a complete mental model: input acceptance, source-specific behavior, soft-fail conditions, and output structure. The explicit pointer to entity_profile covers the sibling distinction, making it self-sufficient for an 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 covers 100% of params, but the description adds value by providing concrete examples for `since` (ISO date or relative shorthand like '7d', '3m', '1y'), recommending '30d' for typical monitoring, and reinforcing that `value` is a ticker or CIK. This bridges the gap between schema types and practical usage.

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

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

The description clearly states it's a 'change feed for a company in the last N days/weeks/months' with specific source fan-out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from siblings by explicitly naming entity_profile as the alternative for static profiles, and uses concrete natural-language query examples to clarify intent.

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 guidance: use for time-boxed changes ('this week/month/quarter') and recommends entity_profile for static profiles regardless of window. It also details fallback behavior (GDELT preferred, GNews on rate-limit/5xx, USPTO soft-fail) which informs when the tool may return partial or degraded results.

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 flag this as non-read-only and idempotent. The description supplements with persistence details (authenticated users persistent, anonymous 24h retention) and scoping by identifier, which are not visible in 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, each earning its place: purpose, when-to-use, storage details, and tool pairing. No fluff, well front-loaded.

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

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

For a simple two-param tool with no output schema, the description fully covers storage, retention, scoping, and companion tools. The agent has everything it needs to invoke correctly.

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

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

Schema covers both key and value at 100% with examples, so baseline 3. However, description enriches semantics by framing them as a 'key-value pair scoped by identifier' and giving domain-specific examples (ticker, address, preference), adding value beyond schema.

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

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

The description opens with a specific verb ('Save data') and clarifies the resource (key-value store) and scope (across conversations/sessions). It distinguishes itself from sibling tools like recall and forget, explicitly positioning it as the storage action in the memory trio.

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 concrete when-to-use guidance ('discover something worth carrying forward') with examples, and explicitly mentions companion tools (recall, forget). It also notes authentication-dependent persistence, helping the agent decide when memory is reliable.

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

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

The description discloses internal cascading through endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling for identifiers, and explicit reporting of unresolved identifiers under 'unresolved'. This adds behavioral context beyond the readOnly/idempotent annotations, with 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?

The description is lengthy but well-structured: example queries upfront, followed by purpose statement and a clear 'SUPPORTED TYPES' breakdown. Every sentence adds useful detail, though it could be slightly tighter without losing value.

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

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

With no output schema, the description carries the full burden of explaining return values. It covers both entity types, identifier sources, unresolved handling, degradation behavior, and internal cascading, making it comprehensive for a complex tool.

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

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

The description richly expands on the schema by detailing accepted values for 'type' (company/drug) and 'value' (ticker, CIK, name, brand/generic), plus what each type returns with data sources. The schema descriptions are basic, while the description provides the real semantics.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools. It provides a specific verb (resolve), resource (entity names), and scope (company/drug identifiers), and distinguishes itself from siblings by positioning as the prerequisite lookup step.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also explains supported types and input formats, and notes that it replaces 2-3 manual lookups, reinforcing when to choose 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the probing mechanism (calls ai_visibility_check per entity), ranking logic, and that it returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and gives agents a clear expectation of the tool's 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?

The description is two sentences, front-loaded with the core purpose, and includes a concrete use-case example and return summary. Every sentence contributes meaningfully, with no filler 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 the complexity (4 params, 1 required) and lack of output schema, the description adequately covers what the tool does, how it works (probes each entity, ranks), and what it returns (ranked list with score, confidence, signal density). It omits explicit constraints like the 2-8 entity limit, but that is in the schema and not essential for selection. The use-case example adds practical context. Minor gap: it doesn't mention that most/least recognized is determined by score, but that is implied.

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 baseline is 3. The description does not add additional meaning beyond the schema; it mentions 'your brand + N competitors' which loosely aligns with the 'entities' parameter, but all semantic details (e.g., first entity is the subject, models supported, API key requirement) are already in the schema. No extra value is contributed here.

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, uses ai_visibility_check to probe each entity, ranks by score, and identifies most/least recognized. This specific verb+resource combination distinguishes it from single-entity tools like ai_visibility_check and generic compare_entities.

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

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

The description explicitly states a use case: competitive AI-marketing audits, with an example question. It implies when to use this tool over alternatives (when comparing multiple entities) but does not explicitly mention when not to use it or name alternative tools beyond referencing ai_visibility_check. This is clear but not exhaustive.

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

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

The description adds behavioral context far beyond the annotations: it discloses that this is a composite call fanning out to two services, that partial failures degrade gracefully, that bundlephobia's first measurement can take 5-30 seconds, and that sources_failed will list timeouts while the rest still returns. This is valuable information not present in readOnlyHint/idempotentHint/etc.

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

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

Every sentence earns its place: first sentence defines purpose and sources, second gives usage triggers, third lists return shape, fourth scopes the ecosystem and points to alternative, fifth explains failure behavior. There is no redundancy or filler; the density is high but well-organized with dashes and semicolons.

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

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

Despite having no output schema, the description enumerates the full return block (summary fields, per-advisory detail, links, alternative versions) and explains edge-case behavior (new-version timeout, sources_failed list). For a two-parameter tool with this complexity, the description covers all essential aspects of use and output.

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

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

The input schema already provides 100% coverage with clear descriptions for both parameters ('package' and 'version', including the default behavior for version). The description adds no additional parameter-specific detail beyond what the schema contains, so the baseline of 3 is appropriate.

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

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

The description starts with a specific, compound purpose ('should I add this npm package to my project' check in ONE call) and details exactly what it fans out to (deps.dev and bundlephobia) and which metrics are returned. It clearly distinguishes from any sibling tool by scoping to NPM packages and naming the alternative for other ecosystems.

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 the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion/alternative instruction: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is clear guidance on when to use and when not.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description goes further by disclosing technical details such as BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap, and truncation flagging. It also explains the return format (offsets and scores). This adds substantial behavioral context beyond the annotations 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?

The description is four sentences long and front-loaded with the core action. Every sentence adds unique value: purpose, use cases, integration with another tool, and technical constraints. There is no fluff or repetition, and the structure flows logically from definition to guidance to implementation details.

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

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

Given the lack of an output schema, the description does a good job of explaining what the agent can expect: top-N passages, character offsets, and similarity scores. It also covers input limits and truncation behavior. However, it does not specify the exact JSON structure of the returned passages (e.g., field names), which would be useful for an agent consuming the result. This minor gap prevents a 5.

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 baseline is 3. The schema already documents each parameter (text, query, limit) with clear descriptions and examples. The tool description adds contextual framing ("text you already pulled") and return behavior, but it does not significantly enhance per-parameter meaning beyond what the schema provides. Thus, a 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 opens with a specific verb and resource: "Semantic search INSIDE a fetched record." It clearly explains the input (text already pulled) and output (top-N passages with character offsets and similarity scores). It also differentiates from sibling tools by emphasizing the targeted search within a record and its pairing with ask_pipeworx_grounded, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: "Use when the record is too big to cram into the prompt." It also provides context with examples (SEC 10-K, article, long tool result) and recommends a workflow with ask_pipeworx_grounded, including a clear integration pattern. This is strong usage guidance beyond a vague rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond this—it does not explain what 'key' refers to, what data is returned, or any constraints like pagination or format. The description is neutral but uninformative.

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

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

The description is very short, but this is under-specification rather than effective conciseness. It omits critical information needed to invoke a tool with 8 parameters and provides no structure or context. The brevity does not serve the agent's needs.

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 8 parameters, 0% schema description coverage, and a vague two-word description, the tool is far too underspecified. Even though an output schema exists, the description does not explain the tool's core concept, valid keys, or parameter interactions. This is completely inadequate for correct tool selection and use.

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

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

Schema description coverage is 0% (no property descriptions), so the description must compensate by explaining parameter meanings. The description only mentions 'key', and even that is unclear. The other 7 parameters (end, side, sort, limit, start, symbol, section) are completely unexplained, leaving the agent without meaningful 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?

Description 'Statistics by key' vaguely indicates the operation is about retrieving statistics, but there is no specific verb or resource context. It does not differentiate the tool from sibling data tools like candles, trades, or tickers, leaving the exact purpose unclear.

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

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

No usage guidance is given. The description does not state when to use this tool over alternatives, what scenarios it suits, or any prerequisites. There is no mention of comparison to sibling tools, making it impossible for an agent to decide when stats is the correct choice.

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 annotations (readOnlyHint=false, idempotentHint=true), the description adds significant behavioral detail: the OAuth account requirement, the persistent vs. non-persistent nature, the delivery channel specifics (phone verification, 10/day SMS cap, webhook auto-disable), and the return of a new subscription id. This gives the agent a thorough understanding of side effects and prerequisites.

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 information-rich, covering prerequisites, types, and delivery options in a compact paragraph. Every sentence contributes new details, though the length is at the upper limit. The front-loaded main action and structured flow (create → return → requirement → types → delivery) make 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?

For a complex tool with nested objects and no output schema, the description covers all essential aspects: return value, authentication, type-specific parameters, delivery channels, limits, and verification requirements. It is sufficiently complete for an agent to invoke the tool correctly without additional external knowledge.

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. The description adds extra semantic value by providing concrete examples for each type (e.g., items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE") and clarifying the phone verification requirement for SMS. These details complement the already-rich schema rather than merely repeating it.

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 verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of a subscription and mentioning the returned subscription id. The supported types and delivery channels further clarify its unique role.

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

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

Provides clear usage context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, and explicitly mentions the always-on feed as an alternative to pull via recent_alerts. It does not explicitly name alternatives like 'use list_subscriptions to manage existing subscriptions,' but the context makes the when-to-use 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=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail beyond this: it explains the return structure ('category-bucketed example questions'), the source ('drawn from the live catalog of thousands of tools'), and modality ('Call with no arguments for the full spread, or pass topic to focus'). This gives the agent a clear picture of what will happen when invoked.

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

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

The description is somewhat long, but it is front-loaded with high-value information: the natural-language trigger examples, the output summary, and the usage directive. Every sentence contributes necessary context for a discovery tool. Minor redundancy exists (e.g., 'what can I ask' is repeated in multiple forms), but structural clarity is strong.

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 only one optional parameter, no output schema, and a low complexity profile, the description is complete. It explains what the tool returns, when to use it, how to call it (with and without arguments), and how it fits into the broader tool ecosystem. No significant gaps remain.

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

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

The schema covers 100% of parameters, but the description adds value beyond it by explaining the no-argument invocation ('Call with no arguments for the full spread') and providing concrete examples of valid topic values ('finance', 'pharma', 'betting'). It also clarifies the meaning of omission ('Omit for a cross-category spread'), which is not present 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 uses a specific verb and resource: it is 'the onboarding entry point' that 'returns category-bucketed example questions' with 'the exact tool + argument shape.' It clearly distinguishes itself from sibling tools by emphasizing its role as the first-stop discovery mechanism and by explicitly naming the meta-tools it helps the agent learn to call.

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

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

The description explicitly says to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' This gives clear context on when to use it. It does not explicitly state when not to use alternatives like discover_tools, but the guidance is specific enough for effective 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 the operation read-only, idempotent, and non-destructive. The description adds transparency by enumerating the exact data returned (bid/ask, last trade price, 24h volume, change percentage), which is useful beyond the annotations. No additional behavioral traits like rate limits or error handling are mentioned, but the annotations cover the safety profile.

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 one sentence, front-loaded with the purpose and exchange, and includes an example and return fields. Every word 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?

For a simple one-parameter read-only tool with an output schema present, the description is complete: it identifies the data source (Bitfinex), scope (single-pair live), provides a concrete example, and lists return fields. Annotations cover safety, so no critical information is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It provides the example 'tBTCUSD' and implies the Bitfinex symbol format, but does not explain the full symbol convention or behavior for invalid symbols. This is adequate but not comprehensive for a single parameter.

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

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

The description clearly states it is a Bitfinex single-pair live ticker and specifies the return fields (bid/ask, last price, 24h volume, change percentage). It distinguishes itself from sibling tools like tickers, candles, and ticker_history through the 'single-pair' and 'live' scope.

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

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

The description provides clear context that this is for a single live pair, implying it is appropriate for retrieving current data for one symbol. It does not explicitly name alternatives or exclusions, but the 'single-pair' and 'live' framing effectively communicates when to use it versus multi-pair or historical tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the exchange source, symbol format, epoch time units, and the return fields (bid/ask/last per timestamp), which enrich the agent's understanding.

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

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

The description is a single, information-dense sentence that front-loads the core purpose and includes only essential details. No filler 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 the rich annotations (read-only, open-world, idempotent), the presence of an output schema, and the compact description covering purpose, key parameters, and return shape, the tool is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It explains 'symbols' with an example format, 'start/end' as ms epoch, and 'limit' as an optional count, effectively compensating for the empty schema descriptions.

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

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

The description states a specific action ('historical ticker snapshots') for a specific resource (Bitfinex pairs), clearly distinguishing it from sibling tools like current ticker, candles, or trades. The mention of one or more comma-separated pairs further clarifies scope.

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

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

It clearly implies use for historical data retrieval with optional start/end and limit, making the intended scenario evident. However, it does not explicitly name alternatives or state when not to use it, leaving some implicit differentiation.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the exchange source (Bitfinex), the live nature, and the special 'ALL' option—context beyond the annotations. It also lists returned fields (bid/ask, last, daily change, volume), which is useful even with an output schema present.

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

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

Two concise sentences: the first captures purpose and scope, the second gives input syntax and output summary. No redundant detail, perfectly front-loaded.

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

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

For a one-parameter, read-only, annotated tool with an output schema, the description fully covers what it does, how to use it, and what it returns. It is self-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?

The input schema has zero description coverage for the 'symbols' parameter. The description fully compensates by explaining the comma-separated format and the special 'ALL' value, with concrete examples (tBTCUSD,tETHUSD).

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 provides multi-symbol live tickers for Bitfinex crypto pairs, with specific output fields. The plural 'tickers' and 'multi-symbol' wording distinguishes it from the sibling 'ticker' tool.

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

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

Describes exactly how to pass symbols ('comma-separated' or 'ALL') and what it returns. It does not explicitly name alternative tools for single-symbol or historical data, but the context strongly implies this is for multiple live tickers.

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 hint, covering the safety profile. The description adds that start/end are in milliseconds epoch and mentions 'recent' trades, but it does not disclose default time windows, pagination behavior, or rate limits. This is adequate but not rich.

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

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

The description is a single sentence that front-loads the exchange and data type, includes an example, and lists optional parameters. Every phrase is informative with no 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?

The tool is relatively simple, has an output schema, and annotations cover safety. The description conveys the core purpose and all parameter names. However, it leaves some gaps such as the default time range implied by 'recent' and the exact semantics of sort order. Given the output schema exists, this is nearly complete.

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

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

The description names all parameters (symbol via 'pair', start/end, limit, sort) and specifies that start/end are in ms epoch, which adds meaning beyond the schema (which has no descriptions). However, it does not explain the values for sort order (e.g., -1 vs 1) or the meaning of 'recent' when start/end are omitted. With 0% schema description coverage, this partial compensation earns a 3.

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

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

The description clearly identifies the resource (Bitfinex crypto exchange) and the specific data returned (recent trade tape with trade ID, timestamp, amount, price). It distinguishes itself from sibling tools like candles or ticker by focusing on per-execution trades. The example symbol 'tBTCUSD' clarifies the expected input format.

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

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

The description implies the tool is for retrieving recent trade data for a pair, but it does not explicitly state when to use this tool over alternatives like ticker or candles, nor does it mention any exclusions or prerequisites. Usage guidance is only implicit through the description of the data content.

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, the description discloses that the row is deactivated not deleted, preserving historical events via recent_alerts, and that ownership is enforced. This adds value beyond the annotation flags.

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, action-first, no filler. Each clause adds value: cancellation, ownership, deactivation 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 a single parameter with full schema coverage and clear behavioral disclosure, the description covers all essential aspects for invoking the tool correctly. It explains the effect (deactivation) and downstream impact (recent_alerts availability).

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 fully describes the 'id' parameter with 100% coverage, including its source from subscribe. The description adds no new parameter-specific details beyond reaffirming 'by id,' so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the action and resource. It distinguishes from sibling tools like subscribe (creating) and list_subscriptions (viewing).

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 context that ownership is enforced, implying you use it for your own subscriptions. It doesn't explicitly name alternatives but the context is clear enough for an agent to select it when cancellation is needed.

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, but the description adds crucial behavioral details: the critical distinction between could_not_verify (check did not happen and must not be used as evidence) and unsupported (no source covers it). It also warns callers about verification_error{stage,detail}. These are non-obvious behaviors 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 long but every sentence earns its place. It is well-structured: intent examples → usage → routing → output semantics → critical error warning → efficiency claim. Despite length, there is zero fluff; the density is justified by the tool's complexity.

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

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

With no output schema, the description fully specifies return values: verdict types, grounded/structured actual value with pipeworx:// citation, and reasoning. It explains the two possible error statuses and their meanings, and gives parameter semantics. An agent has everything needed to invoke and interpret 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 coverage is 100% with both params described. The description adds extra value for tolerance_pct: it explains the range (0.5–50), the default behavior (implied by wording, capped at 5), and a specific use case (set 1–2 for hallucination detection). The claim param is illustrated with concrete examples.

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

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

The description clearly identifies the tool as natural-language claim verification with specific verb+resource ('verify... against authoritative sources') and lists concrete user intents ('Is it true that…', 'fact check'). It distinguishes itself from generic research tools by describing the dual routing (SEC EDGAR fast path vs grounded pipeline) and specific verdict 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?

Explicit usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the tool replaces 4–6 sequential calls, indicating its efficiency and purpose. However, it doesn't explicitly name alternative tools for exclusion (e.g., deep_research for open-ended questions).

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