Data Ny

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 beyond annotations: it names the default model, clarifies that Anthropic calls are BYO-key with direct billing, and describes the per-model return payload. 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?

Three-sentence description front-loads the core action, then efficiently covers default behavior, billing, return structure, and use cases. No redundancy; every sentence contributes necessary information.

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

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

For a tool with 4 parameters, 100% schema coverage, and no output schema, the description adequately covers purpose, parameters, output shape, and use cases. It does not explain the meaning of 'signals' or 'confidence', but overall it gives an agent enough context 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 coverage is 100% and parameter descriptions are solid. The description adds extra meaning by identifying the specific default model (Workers AI Llama-3.3-70b), framing `_apiKey` as a BYO key with direct billing, and implying that omitting `models` uses the free default. These details are not fully 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?

Description uses specific verb 'probe' and names the resource (LLMs) plus the output (visibility score 0-100 per model). It clearly conveys the tool's function, but does not explicitly distinguish from sibling 'scan_competitor_ai_presence', so it lacks direct sibling differentiation.

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

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

Provides clear usage context via use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and describes the default/free option. However, it does not mention alternatives or when-not-to-use scenarios, so it stops short of explicit 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 the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context: it routes to a large pool of tools, returns structured answers with citation URIs, works on all tiers, and is a single fast call. This goes beyond the annotations and helps set expectations for latency 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 longer than average but each sentence serves a distinct purpose: preference over web search, scope of domains, routing mechanism, trigger phrases, examples, default placement, step-up alternatives, and breaking-news note. It's well-structured and front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), though it could be trimmed slightly without losing meaning.

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

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

For a tool with no output schema and a broad routing role, the description is remarkably complete. It explains what the tool does, when to use it, what it returns (structured answer with citations), how it relates to web search and siblings, and even covers edge cases like breaking news. The examples span diverse domains, and the alternative-step-up guidance ensures the agent has enough context to make appropriate choices.

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 parameter semantics thoroughly: all six parameters are aliases for 'question', and the schema description explicitly lists those aliases and provides examples. Schema coverage is 100%, so the description doesn't need to add much. It does contribute a few concrete example questions, but these are also present in the schema examples, so the marginal value is limited.

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: it answers factual questions by routing to 5,529 tools across 1,455 verified sources and returns structured answers with citations. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, making the primary use case unmistakable.

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

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

The description provides explicit guidance on when to use this tool: it should be preferred over web search for factual questions, and it lists trigger phrases like 'what is', 'look up', 'find', etc. It also names specific alternatives for when to step up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), giving clear conditional usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds valuable context beyond these hints: it is a beta/experimental version, no candidate is currently active, it matches ask_pipeworx exactly, and it is a full working router. This provides helpful nuance without contradicting 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 information-dense yet well-structured: it first defines the tool's identity, then current status, then usage instructions, and ends with a caveat. Every sentence carries useful meaning with no filler, though it is slightly longer than strictly necessary.

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 universal router with no output schema, the description covers key aspects: what it routes, how it differs from the stable version, current operational state, and usage instructions. The lack of a response format description is mitigated by stating 'same response shape' as ask_pipeworx, making it sufficiently complete.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description confirms 'same arguments' but adds no new parameter-level detail beyond the schema, 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 the 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by mentioning candidate routing improvements and its experimental edge, making the purpose specific and actionable.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router for comparison purposes. It names the alternative (ask_pipeworx) and gives a clear context, though it stops short of explicit 'when not to use' guidance.

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

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

Even though annotations already mark readOnlyHint=true and idempotentHint=true, the description adds rich behavioral context: it strictly extracts answers from the tool result, returns an explicit refusal with enumerated reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and includes an evidence quote. It also discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but well-structured, starting with the core purpose and then explaining mechanism, return format, usage scenarios, and cost trade-off. Each sentence earns its place. Slightly long, but the information is high-value and front-loaded.

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

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

Given the lack of an output schema, the description fully details the success return object (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and the explicit refusal object with reason enums. It also covers when to use, alternatives, and cost implications, making it highly 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 input schema has 100% coverage with all six parameters documented as aliases for 'question,' and the description does not add any additional parameter meaning. Baseline 3 is appropriate since the schema fully handles 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 opens with a specific, high-value purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding a strict extraction behavior using ONLY tool results. This gives a precise verb+resource+scope with sibling differentiation.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' followed by concrete examples. It also gives the exclusion: 'prefer ask_pipeworx for casual lookups' based on the cost of one extra LLM call. This clearly defines when to choose this tool over its sibling.

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

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

Annotations already set readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: resolver confidence levels and statuses (low_confidence_match, market_closed_or_inactive), news fallback behavior for 429 rate limits, wide-spread tradeability warnings, and cancellation-rule risks like refund_50_50. It even highlights a recurring 'pure-rules loss' scenario, far exceeding annotation baseline.

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 structured with capitalized section headers, but it is very long (over 600 words). It front-loads the primary purpose and each sentence generally earns its place, but the extensive fan-out examples and safety sections could be tightened. For a complex tool, the length is justifiable, though not concise in absolute terms.

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?

Since there is no output schema, the description carries full responsibility for explaining return values. It thoroughly details result.market, result.analysis, result.evidence, result.market_match_confidence, result.parent_event, news fields, and special statuses. It also covers edge cases such as closed markets, wide spreads, and rate limits, making it highly complete 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 input schema provides 100% coverage for all three parameters, including descriptions, defaults, and examples. The description restates the market parameter's accepted formats (slug, URL, question text) but adds no new parameter-specific semantics beyond the schema. With complete schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It enumerates the pipeline (resolve, classify, fan out, return evidence packet) and differentiates from siblings by focusing on single-bet research queries like 'should I bet on X'. This is a specific verb+resource 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 gives explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete query examples and warns to inspect resolver confidence and cancellation rules before sizing. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it lacks full when-not/alternative coverage.

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 adds limited behavioral context—it doesn't mention ordering, pagination, or any limitations. With strong annotations, the bar is lower, and the description just barely meets it by clearly stating the core function, but it doesn't go beyond what the annotations convey.

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, grammatically complete sentence of five words. It is perfectly front-loaded and contains zero wasted words.

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

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

The tool is simple with two clearly named parameters and an output schema. Annotations cover safety. The description is adequate for a basic understanding, but it doesn't explicitly state that resource_id identifies the dataset/resource, and it lacks any additional context about sorts, limits, or how distinct values are computed (e.g., nulls excluded). Given the output schema exists, return values are covered, so the description is minimally acceptable but not exemplary.

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 full burden of parameter meaning. The description only references 'column' indirectly ('in a column') and does not explain the resource_id parameter or any formatting/type details. The parameter names are self-explanatory, but the description 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 clearly states the tool returns distinct values for a column, and the input schema specifies the required resource_id and column. However, it does not explicitly distinguish from sibling data-access tools like 'query' or 'search_within', though the specific 'distinct values' function is clear.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions. Sibling tools such as 'query' and 'search_within' could serve similar data-retrieval purposes, and the description does not clarify how this tool should be selected over them.

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 many behavioral traits beyond the annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and the return of paired data with citation URIs. This is rich context that goes well beyond the readOnly/idempotent hints.

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

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

The description is information-dense but every sentence earns its place. It is front-loaded with trigger phrases for selection, then explains behavior, type-specific data, output format, and efficiency. There is no fluff or repetition of schema details.

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

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

Given there is no output schema, the description explains what the response looks like: results sorted by primary metric, paired data, and citation URIs. It also covers data sources, fiscal year handling, and the tool's advantage over sequential lookups. For a tool with only 2 parameters, this is a complete and self-contained description.

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 thoroughly describes both parameters (type and values) with 100% coverage. The description adds meaning by explaining what metrics each type pulls and giving concrete examples, which helps the agent decide how to populate the values. It does not introduce syntax beyond the schema, so a 4 is appropriate.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also distinguishes from siblings by explicitly preferring it over sequential single-pack lookups, and specifies the exact metrics for each entity type.

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 trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger'), a direct preference instruction ('ALWAYS PREFER over sequential single-pack lookups'), and type-specific guidance ('type="company" pulls...', 'type="drug" pulls...'). This gives clear when-to-use and when-not-to-use context.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds no additional behavioral context beyond 'search', such as pagination behavior, result format, or any side effects. It neither contradicts the annotations nor enriches 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 short sentence that directly states the purpose without any extraneous words. It is appropriately concise and front-loaded, earning full marks for efficiency.

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?

While the tool has an output schema (reducing the need to explain return values), the description fails to clarify how the three parameters should be used, what constitutes a valid query, or what the catalogue contains. Given the zero schema description coverage, the description is not complete enough for an agent to confidently 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?

The input schema has zero description coverage for its three parameters (limit, query, offset), and the tool description provides no explanation of their meaning or usage. The examples in the schema offer minimal hint, but the description itself adds no parameter semantics, leaving the agent without sufficient guidance on how to construct a valid request.

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 'Search dataset catalogue' uses a specific verb ('Search') and resource ('dataset catalogue'), which clearly states the tool's function. It distinguishes itself from sibling tools by explicitly mentioning the catalogue, 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?

There is no guidance on when to use this tool versus alternatives. The description only states what it does, not when it should be preferred or avoided. No exclusions or alternative tool references are provided.

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

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

Annotations cover read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral context: account/payment requirements, parallel decomposition, findings packet structure with gaps[], the promise to 'never invented' data, fetchable citation URIs, contradictions[] for standard/thorough, semantic excerpting ('not head-truncated'), and expected latency (15-60s). This far exceeds the annotation baseline.

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?

Despite being long, every sentence carries critical operational information: prerequisites, distinctions from alternatives, expected outputs, timing, and depth behaviors. It is front-loaded with the account requirement and structured logically from what it is, to when to use it, to behavioral nuances. No filler is present.

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 thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and the fetchability of citations. It also covers resource requirements, speed expectations, and how different depth settings affect behavior, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The input schema already explains both parameters in detail, including depth behavior and the open-ended nature of question. The description adds only minor extra context such as the paid plan for thorough and the purpose of decomposition, but does not fundamentally expand parameter meaning beyond the schema.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'in ONE call'. It distinguishes itself from ask_pipeworx by saying it 'decomposes your question into focused facets' and 'routes each to the right one of 5,529 tools', while explicitly noting it is 'NOT open-web search'.

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: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also excludes current-news use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes fallback when not signed in: 'If you are not signed in, use ask_pipeworx 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and each result is ready to call directly without a second schema lookup. It does not cover auth or rate limits, but given the read-only nature and the explicit output shape, it goes 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 three sentences, each earning its place: the first states the core purpose, the second gives usage context and domain examples, and the third adds return-value specifics and strategic guidance. It is front-loaded, free of fluff, and effectively communicates the tool's value in a compact format.

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 burden of explaining return values, which it does thoroughly: 'names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly.' It covers when to use, what domains it covers, and what the response looks like, making the tool self-explanatory for an AI agent selecting among many sibling tools.

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

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

The input schema covers all parameters with descriptions, including aliases for 'query' and a 'limit' with defaults. The description does not add significant parameter-level detail beyond what the schema provides, though it reinforces that 'query' is a natural language description by repeating the concept. With 100% schema coverage, the baseline is 3, and the description meets but does not exceed 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 starts with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by stating it is for discovering which tools exist, not for querying data directly. The explicit 'Call this FIRST' guidance and the list of covered domains further reinforce 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?

The description gives clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist for: [list].' It also advises calling this tool FIRST when many tools are available and one wants to see the option set, implying it is not for when a specific tool is already known. However, it does not explicitly name alternative tools or provide a 'when not to use' statement beyond the implication.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavior: fans out across multiple data sources, returns specific fields like cik, filings with URIs, fundamentals sorted by period_end, patents soft-failing after USPTO sunset, and a GDELT→GNews fallback for news. This adds significant non-obvious 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?

Although long, the description is densely packed and logically organized: starts with example queries, states the core action, lists output components, and ends with parameter guidance and an alternative. Every sentence carries necessary information, and the structure is front-loaded with the most critical guidance.

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

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

Given the complexity of the tool and no output schema, the description is remarkably complete: it enumerates return fields, limits (up to 5 filings), data source fallbacks, sort order, and dependency on resolve_entity. It equips an agent to invoke the tool appropriately and anticipate partial failures.

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 provides descriptions for both parameters, but the description enhances them with concrete examples ('AAPL', '0000320193'), clarifies zero-padded CIK format, and reinforces the unsupported-name limitation. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and gives multiple realistic user phrasings. It distinctly positions itself as an aggregate profile tool, differentiating from single-purpose lookups like SEC, XBRL, or news searches.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states names are not supported and directs users to use resolve_entity first when only a name is available, providing a clear alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds minimal behavioral context beyond stating the delete operation, which aligns with the annotations. No contradiction is present, but the description could have added more detail about side effects like irreversibility.

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 consists of two efficient sentences, front-loading the core purpose. Every sentence adds value, including the pairing hint with 'remember' and 'recall,' with no waste.

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

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

For a one-parameter delete tool with strong annotations, the description adequately covers when and how to use it. It could mention that deletion is idempotent or the response shape, but annotations already cover idempotency, so the description is sufficiently 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 schema's 'key' parameter is fully described as 'Memory key to delete' with 100% coverage. The description repeats this without adding new meaning, so it adds no value beyond the schema.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key,' making the tool's function clear. It also distinguishes itself from sibling tools by explicitly naming 'remember' and 'recall' as related operations.

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 usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It does not explicitly state when not to use the tool, but the positive conditions are sufficient for a simple deletion tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds that it fetches the page and extracts content, which is useful context. However, it does not disclose potential runtime behaviors like network failures, rate limits, or response size constraints. The added detail is on par with the date-range scoping in the calibration example, which earned a 3.

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

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

The description is three sentences: purpose, process, and use cases. It is front-loaded with the core action, contains no filler, and every sentence adds value. This is an exemplary concise structure.

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

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

For a simple tool with two parameters and no output schema, the description tells the agent everything needed: input (any URL), optional max_links, process (fetch/extract/emit), output (markdown text blob), and use cases. It is complete without being verbose.

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 for both parameters (url and max_links) with clear descriptions. The tool description does not add new parameter-specific semantics beyond what the schema offers, 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 clearly identifies the tool's function: generating a production-ready llms.txt file for any URL, with specific steps (fetching, extracting, emitting) and output format. It distinguishes itself from sibling tools like ai_visibility_check, which likely focus on auditing presence rather than producing the file.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for one's own project, or auditing a competitor. It does not name alternative tools, so it lacks 'when not to use' guidance, but the scenarios are clear enough for an agent to select it appropriately.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds useful context by stating it returns specific fields and that it lists only active subscriptions by default. It also implies the include_inactive parameter affects results, which is beyond the annotation. This is consistent with annotations and adds 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 two sentences, front-loaded with the action, and every sentence serves a purpose. The first sentence states the function and return fields, while the second provides usage context. No filler or redundant information.

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

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

For a simple read-only list tool with one optional parameter, the description covers the purpose, caller scope, return fields, and usage context. Although there is no output schema, the explicit field list compensates. With strong annotations, the description is complete and well-rounded.

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

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

The single parameter (include_inactive) has a comprehensive description in the schema (100% coverage), explaining its meaning and default behavior. The tool description does not add additional parameter context, but the schema is sufficient, 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 states the verb ('List') and resource ('the caller's active subscriptions'), providing a specific scope. It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on listing and reviewing subscriptions. The return fields are explicitly enumerated, 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 says when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance on when it is appropriate relative to alternative actions (subscribing or unsubscribing), even though it doesn't name the sibling tools directly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds no behavioral context beyond a generic noun phrase. It does not disclose what metadata is returned, any limitations, or additional side effects, though it does not contradict 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 extremely short but under-specified; it is not a case of efficient minimalism because it lacks essential information. 'Resource metadata.' is a single phrase that fails to earn its place as a useful tool description.

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

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

Even with helpful annotations and an output schema, the description is inadequate. It does not explain what constitutes a resource, how to identify it, or what metadata is returned, making the tool incomplete for an agent 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?

The schema description coverage is 0%, so the description must compensate, but it only says 'Resource metadata.' without explaining the resource_id parameter or its expected format. The parameter name is somewhat self-explanatory, but the description adds no meaning beyond the schema's name.

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 'Resource metadata.' is a noun phrase that restates the tool name without a verb, making it tautological. It does not clearly state what action is performed (e.g., 'Retrieve metadata for a resource'), providing only vague reference to a resource.

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 its 30+ sibling tools. There is no mention of context, use cases, or alternatives, leaving the agent without criteria for selection.

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

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

Discloses the claim_token flow, rate limit ('5 per identifier per day'), and that it's free with no tool-call quota impact. Also warns against pasting end-user prompts, adding context beyond the annotations. 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?

Though long, every sentence carries necessary information: purpose, when to use, exclusions, token mechanics, rate limit, roadmap impact. It is front-loaded with the primary action and organized logically, 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?

Despite no output schema, the description explains the return value (claim_token) and its later use. It covers use cases, exclusions, and operational details, providing a complete understanding for an agent to 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 coverage is 100%, so baseline is 3. The description adds extra semantics for claim_token (pass it later to read status) and clarifies the type enum via examples, enhancing the schema's field descriptions.

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

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

The description states the verb ('Tell') and resource ('Pipeworx team') clearly, and defines the scope as feedback for Pipeworx tools. It distinguishes from siblings by narrowing to bug/feature/praise reports specifically for this connection, unlike ask_pipeworx or query tools.

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

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

Explicitly states when to 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).' Also gives a clear exclusion: not for tools from other MCP servers, with a directive to file elsewhere.

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

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

Annotations already declare the tool safe and read-only, so the description adds value by disclosing caching behavior ('Cached 5min-1h'), data provenance ('derived from CF analytics-engine'), and privacy (no PII). This gives the agent a fuller picture of what to expect beyond the structured hints.

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

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

The description is well-structured and economical: a lead sentence stating the tool's output, a concise list of use cases, and technical notes on aggregation/caching. Each sentence serves a distinct purpose 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?

For a tool with a single optional parameter and no output schema, the description provides comprehensive context: return contents (tools, packs, volume), windows, caching, data source, and privacy. It leaves no significant gaps for an agent to infer the tool's behavior.

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

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

The schema description fully documents the 'window' parameter, including its enum values and trade-offs between shorter/longer windows. The tool description repeats the window options but does not add new semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume based on current AI agent usage. It distinguishes itself from siblings like discover_tools (which likely focuses on discovery rather than aggregate usage) and ask_pipeworx (Q&A) by emphasizing the self-aggregating, trend-based signal.

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 'Useful for' scenarios (discovering hot data sources, confirming canonical tools, checking alignment with other agents' needs). It lacks explicit alternatives or when-not-to-use guidance, but the use cases offer clear context for when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds deep behavioral context: it explains child-market traversal, the partition_check sum with a 3pp threshold, the Jaccard similarity anchor, placeholder filtering, and the fill check against live CLOB depth. It also warns that realizable_edge_pp ≤ 0 means 'do not trade it,' which is valuable safety guidance. No contradiction with annotations.

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

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

The description is front-loaded with a clear purpose and then organized into logical sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is long, but almost every sentence carries actionable details. Some redundancy (e.g., repeated emphasis on partition_check) and the volume of information might make it dense, but it remains well-structured and earns its length.

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

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

With no output schema, the description fully compensates by specifying the response shape: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check fields. It also explains the fill check output and the no-trade condition, making the tool's behavior complete and predictable 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 coverage is 100% and already includes descriptions for event and topic, but the tool description goes further by explaining the no-arg default behavior, giving concrete example slugs, distinguishing event vs topic semantics, and noting that full URLs are accepted. This adds meaning beyond the structured 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges by focusing on arbitrage detection and mentions three distinct modes (trending_scan, event, topic), leaving no ambiguity about the tool's core function.

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

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

It provides explicit guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' and explains which mode to use for specific situations ('event (recommended for a specific market)', 'topic (for cross-event scanning)'). It even names polymarket_fill_risk for custom sizing, directly addressing when not to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description enriches with extensive behavioral details: caching ('Cached 1h at the KV level keyed on all knobs'), special excluded segment behavior (Fed bets 'unreliable at meeting-month horizons'), design gates ('rare-by-design'), and diagnostics ('so callers can see WHY a segment is empty'). No contradiction with annotations.

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

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

The description is well-structured with named segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loads the core purpose. However, it is quite long and includes deep quantitative details (FRED log-returns, per-sport alphas) that, while informative, could be trimmed for more general comprehension without losing primary usage guidance.

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 complex tool with 9 parameters and no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), segment-specific behavior, and diagnostic counters, providing an agent with everything needed to interpret results and debug empty segments.

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?

Though schema coverage is 100%, the description adds crucial inter-parameter semantics: e.g., 'min_partition_leg_kelly applies to the per-leg Kelly inside top_legs instead,' and 'slippage_pp is subtracted from raw |edge| before ranking and Kelly sizing.' It also explains rationale behind defaults (zero trading fees but typical 20-50bp slippage), elevating beyond schema descriptions.

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

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

The opening sentence explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb (scan) + resource (Polymarket markets) + distinctive scope (top markets vs hundreds), and immediately frames the use case ('what should I bet on today'), distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description provides a clear when-to-use scenario ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and explains how to configure knobs for filtering tradeable edges. However, it does not explicitly name alternative sibling tools or state when not to use it, which would push it to 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?

With readOnly/openWorld/idempotent annotations already present, the description goes far beyond them by explaining snapshot write conditions (cache-miss), data gaps, 60-day TTL bounds, and that decay is based on daily closes net of slippage. This is valuable behavioral context for interpreting results, especially the 'openWorld' nature of data availability.

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?

While lengthy, the description is logically structured into purpose, args, response, and limits sections, and every part contributes necessary information that is absent from the schema/annotations. The response field definitions and caveats earn their place given the lack of an output schema.

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

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

The description is highly complete for a read-only telemetry tool: it explains response categories with field meanings, data availability caveats, historical bounds, and interpretation of signed edge values. This substitutes effectively for the missing output schema and leaves no major ambiguity for the agent.

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

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

The input schema already documents both parameters (100% coverage), so the baseline is 3. The description's Args section restates defaults and max values but adds no new semantic detail beyond the schema. Therefore a score of 3 is appropriate.

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

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

The description clearly states the tool tracks edge persistence and decay from daily snapshots, answering a specific question about edge age and shrinkage. This verb+resource framing distinguishes it from sibling tools like polymarket_edges, which compute 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 describes when to use (when edge persistence/decay matters) and provides strong contextual guidance via the 'fresh vs 3-week-old edge' example. It does not explicitly name alternative tools or include exclusion criteria, but the snapshot and TTL details help the agent judge applicability.

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, and the description does not contradict these. It adds rich behavioral context: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), and highlights risks like thin_legs and forced_directional_risk. It also explains behavioral nuances like size_usd interpreted differently in single-market vs basket modes.

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

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

The description is dense and information-rich but runs long as a single paragraph. Every sentence contributes value—mode details, defaults, outputs, and usage guidance—but it could be more scannable with bullet points or section breaks. Still, given the tool's complexity (two modes), thoroughness is justified and no fluff exists.

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 complex (two modes, four params, no output schema), and the description fully compensates: it lists all return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk), explains parameter defaults and clamping, and provides decision-relevant context like the dominant loss mode. An agent has everything needed to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly exceeds the schema by explaining mode-specific semantics. For example, it defines side defaults and auto behavior ('default auto — sell if partition sum > 1, buy if < 1'), clarifies size_usd as 'max spend on buys, target proceeds on sells' vs 'settlement notional' for baskets, and notes the clamp range. This adds substantial meaning beyond the schema fields.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It uses a specific verb ('check') and resource (order-book depth), and distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges as tools to precede it. The two modes (single-market and basket) are clearly delineated.

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 when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable) and the risk of partial basket fills, effectively teaching the agent when this tool is necessary.

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?

Although annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description goes far beyond them. It details compatibility_warning logic based on matched_pairs and skipped_cross_type, temporal_alignment semantics, and the meaning of skipped_cross_type/subtype counters. It even warns that aligned:false makes spreads mathematically meaningless. This is rich behavioral disclosure not available 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 well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Although it is long, every sentence provides necessary operational detail for a complex tool. It could be tightened in places, but the organization makes it navigable and the length feels earned.

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 documents the response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields, and temporal_alignment. It anticipates edge cases such as incompatible bet shapes (range_bucket vs cumulative_threshold) and unrelated events, making it a complete standalone reference despite 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 input schema already provides 100% coverage with descriptions for all three parameters, including allowed topic values and the override behavior of explicit tickers. The description restates these modes but adds little new parameter-level meaning beyond the schema. It clarifies that topic is a shortcut and explicit parameters are for custom pairings, which is essentially already present. Thus 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 first sentence clearly states the tool computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', specifying a concrete action and resource. This distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue rather than intra-venue comparisons. The detailed modes and safety fields reinforce its unique 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?

The description explicitly presents TWO MODES (topic shortcuts vs explicit ticker/slug) and explains when each is appropriate, including that explicit pairings are for custom use. It also issues a crucial caveat that most pre-mapped topics return compatibility warnings and 'pre-mapped ≠ tradeable'. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or state when this tool should not be used.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral details beyond these annotations, such as pagination behavior, result size, or rate limits, so it fails to disclose any extra traits.

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 short phrase, front-loaded and concise, but it is under-specified to the point of being almost terse. It does not waste words, but it also does not provide enough structural content to be highly rated.

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 7 parameters, an output schema, and rich annotations, the description should provide more context on how to construct queries or what is returned. The single sentence only states the tool's purpose, leaving significant gaps for an agent to use it correctly, especially given low schema coverage.

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

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

Schema description coverage is only 29%, with only 'where' and 'resource_id' described. The description does not compensate for the other five parameters (select, group, order, limit, offset), and 'SoQL query' provides no syntax or semantics for these fields, leaving the agent without parameter meaning.

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

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

The description 'SoQL query on a single resource' identifies the verb (query), resource (single resource), and query language (SoQL). It is clear but does not explicitly differentiate from sibling tools like 'search_within' or 'column_data', so it does not fully earn a 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions, leaving the agent without direction on tool selection.

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

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

The description adds behavioral context beyond annotations by stating 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of listing all keys when omitted. Annotations already disclose read-only, idempotent, and non-destructive nature, so this is additional useful 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 three sentences, front-loaded with the primary purpose, and every sentence provides meaningful detail without redundancy or 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?

For a simple one-parameter read-only tool with no output schema, the description fully covers purpose, usage context, scoping, and relationships to sibling tools, making it adequate 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?

The schema already covers the key parameter with 100% description, but the tool description adds meaning by explaining that keys come from prior remember calls and that omitting the key lists all saved keys, which goes beyond the schema's simple type description.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes itself from sibling tools like remember (save) and forget (delete) by describing the retrieval 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?

It explicitly says when to use the tool: 'Use to look up context the agent stored earlier' and explains the benefit ('without re-deriving it from scratch'). It also mentions pairings with remember and forget, but does not name an explicit alternative tool for the same retrieval task.

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

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

The annotations declare readOnlyHint=true and destructiveHint=false, but the description states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' implying a persistent state mutation. This contradicts the readOnlyHint annotation, so the score is 1 per the rubric.

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, front-loading the core action and including only relevant details: filters, mark_read behavior, and the HTTP alternative. Every sentence earns its place without redundancy.

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

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

With 5 optional parameters and no output schema, the description covers the return payload (source, citation_uri, raw event payload), filtering semantics, and the mark_read side effect. It omits pagination and explicit ordering beyond 'most recent,' but that is a minor gap for a feed-reader 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 all 5 parameters with 100% coverage. The description adds an example type ('sec_8k') and explains the follow-up effect of mark_read, but these are marginal enhancements over the schema's own descriptions. 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 'Pull fired events from your subscription feed,' which uses a specific verb and resource, and clarifies the scope as 'most recent alerts the evaluator has written.' This clearly distinguishes it from sibling tools like list_subscriptions and recent_changes.

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

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

The description provides clear usage context: polling works, mark_read affects subsequent calls, and there's an alternative URL for scripts. However, it does not explicitly name sibling tools or state when not to use this tool, so it stops 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses parallel fan-out across SEC, GDELT/GNews, and USPTO, the fallback chain, the PatentsView sunset soft-fail, and the exact return structure (changes[] grouped by source, total_changes, citation URIs). This adds substantive behavioral context that annotations alone would not provide.

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

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

The description is dense but well-structured: query examples, source fan-out, parameter syntax, return shape, and alternative tool guidance are all packed into a compact paragraph. Every sentence contributes practical guidance without fluff, and the key details are front-loaded.

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

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

Despite no output schema, the description adequately describes the return format (structured changes[] grouped by source, total_changes, citation URIs), covers edge cases (rate limiting, API sunset, fallback), and explains parameter formats. This is sufficient 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 coverage is 100%, and the description adds extra meaning: it clarifies that `since` accepts ISO dates or relative shorthand ('7d', '3m', '1y') and recommends '30d'/'1m' for typical monitoring. It also reinforces value semantics (ticker or zero-padded CIK). This exceeds 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 clearly identifies the tool as a change feed for a company over a time window, with concrete query examples ('What's new with X', 'updates on Acme'). It distinguishes itself from entity_profile by explicitly contrasting dynamic change feed vs. static profile, making its purpose unambiguous relative to siblings.

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

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

The description provides explicit usage context: queries about recent news/filings/patents within a window, and directly names the alternative entity_profile for static profile needs. It also explains fallback behavior (GDELT→GNews) and soft-fail conditions, giving clear guidance on when this tool should be selected.

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

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

Discloses scoping by identifier and retention policies (persistent for authenticated, 24h for anonymous), which are not covered by the annotations. The description adds valuable behavioral context beyond the idempotentHint and destructiveHint, 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 three sentences, front-loaded with the primary purpose, then usage trigger, then lifecycle and pairing. Every sentence contributes valuable insight with zero 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 write tool with full schema coverage and informative annotations, the description covers purpose, when to use, persistence, and related tools. No significant gaps remain for an agent 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?

While the schema fully documents both parameters, the description adds that memory is scoped by the agent identifier, which affects how keys should be chosen and clarifies the key-value design beyond the schema's basic field descriptions.

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

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

The description clearly states a specific action (save data) and resource (agent memory) with a clear purpose (reuse later). It explicitly distinguishes from siblings by naming recall and forget, making it 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?

Provides explicit 'Use when' scenarios with concrete examples (resolved ticker, target address, user preference, research subject). Also explains complementary use with recall and forget, and persistence differences for authenticated vs anonymous sessions, offering strong 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds significant behavioral context: graceful degradation (LEI/FIGI enrichment returns EDGAR IDs even if GLEIF/OpenFIGI fail), internal cascading lookups, and labeling of unresolved identifiers under `unresolved`. It also clarifies source labeling. 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 well-structured: it opens with realistic user queries, states the core purpose, then details supported types and edge-case behavior. Every sentence adds information (source labeling, unresolved handling, graceful degradation, cascading). Despite its length, it is front-loaded and efficient for the tool's complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers input formats for both types, the identifiers returned, source attribution, unresolved handling, degradation behavior, and the fact that it replaces multiple manual lookups. This gives the agent enough context to invoke correctly and set expectations.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains what each type returns (CIK/ticker/LEI/FIGI for company, RxCUI/ingredient/brand for drug) and gives concrete value examples. This helps the agent understand the purpose of each parameter beyond simple descriptions.

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

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

The description clearly states the core function: resolving user-spoken names to canonical/official identifiers that other tools require. It lists specific verb-object pairs (resolve name to identifiers) and distinguishes from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID.' The supported types (company, drug) and their enumerations make 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 provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks full exclusionary 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 (readOnly, idempotent, non-destructive), the description discloses that the tool 'Probes each entity... with ai_visibility_check', implying multiple network calls and potential rate-limit/cost implications. It also describes the return structure (ranked list with score, confidence, signal density). This adds meaningful behavioral context not present 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?

The description is three sentences, with the primary purpose front-loaded. Every sentence earns its place: the first states the core function, the second explains mechanics and output, the third gives a use case and example. 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?

The tool is moderately complex (multi-entity, optional models/API key, no output schema). The description covers the input semantics, the probing behavior, and the return fields (score, confidence, signal density). It does not explain default model behavior or failure modes, but these are partially covered by the input schema. Given the complexity and available annotations, the description 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics beyond the schema: 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the role of the entities array, which is not stated in the schema. It also reinforces the models/_apiKey relationship, adding value over the structured definitions.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (multiple entities), the verb (compare), and the outcome (ranked by score, surfaces most/least recognized). It distinguishes itself from siblings like ai_visibility_check (single-entity check) and compare_entities (generic comparison) by explicitly mentioning it probes with ai_visibility_check and ranks results.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and gives an example prompt. It implies this is for multi-entity comparison vs. a single check, but doesn't explicitly state when not to use it or name alternative tools. The guidance is clear enough for an agent to select this tool for competitive audits, though exclusions are absent.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail: it fans out across multiple external services, bundlephobia's first measurement can take 5-30s, and partial failures degrade gracefully with a `sources_failed` list. It does not contradict the annotations, and the added latency/failure context goes beyond the structured hints.

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

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

The description is dense but every sentence carries essential information: what it does, when to use it, what it returns, ecosystem scope, and failure behavior. It is a single block of text but reasonably well-organized; slightly long but justified by the tool's composite nature.

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 lists the exact summary fields, per-advisory detail, links, recent versions, ecosystem limitations, and graceful degradation behavior. For a tool with two simple parameters but a rich response, this description fully equips the agent to understand what will happen.

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 `package` and `version`. The description reinforces the meaning ('npm package name', 'specific version') but adds little beyond the schema, 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 a specific, outcome-oriented purpose: a composite 'should I add this npm package to my project' check. It names the exact data sources (deps.dev and bundlephobia) and the data each provides (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), clearly distinguishing this from sibling tools that target other domains.

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

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

Explicitly states 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion for non-NPM ecosystems, directing those to a direct deps.dev:version path. This is clear, practical guidance on when to invoke this tool 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses specific behavioral details: truncation at 200K chars with a flag, BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and character offsets for verification. These are valuable operational traits not present in the structured fields.

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

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

The description is three dense sentences that front-load the core purpose, then layer usage guidance and technical details. Every clause adds value—offsets, model, truncation—without repetition 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 compensates by explaining return values ('top-N passages with character offsets and similarity scores'), edge-case behavior (truncation flag), and the pairing with ask_pipeworx_grounded. It is complete for the tool's complexity and parameter set.

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 each parameter (text, query, limit) already having clear descriptions. The tool description adds contextual examples (SEC 10-K, articles) but does not provide additional parameter-specific semantics beyond what the schema already contains, 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 opens with 'Semantic search INSIDE a fetched record', which is a specific verb+resource construction. It distinguishes itself from sibling tools by explicitly contrasting with ask_pipeworx_grounded and clarifying that it operates on text already pulled from another source.

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: 'Use when the record is too big to cram into the prompt'. It also recommends a complementary workflow with ask_pipeworx_grounded, saying 'fetch with the gateway, ground over the relevant passages instead of the whole document', which clearly positions this tool relative to alternatives.

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

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

The description goes well beyond annotations, detailing account requirements, phone verification, SMS caps (10/day), webhook signing and auto-disable after 10 failures, and the always-on feed behavior. It explains delivery channel specifics and return value ('Returns the new subscription id'). Annotations already indicate this is a non-read-only, non-destructive operation, and the description adds rich behavioral context without contradiction.

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

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

The description is long but every sentence contributes essential information—purpose, auth, types, delivery options, webhook details, and rate limits. It is well-structured: starts with primary purpose, then requirements, then types, then delivery channels. No filler or redundancy; compact examples efficiently convey parameter details.

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

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

For a tool with 3 parameters (one nested), 5 subscription types, and 3 delivery channels, the description covers all critical aspects: return value, authentication, usage constraints, delivery channel mechanics, and webhook security. No output schema exists, so the description's mention of the returned subscription id is necessary and sufficient. It leaves no major gaps for a complex tool with rich sibling context.

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

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

The input schema already covers 100% of parameters with detailed descriptions and examples for each subscription type and delivery channel. The description text reiterates some examples (e.g., sec_8k items, polymarket topic) but adds no new meaning to parameter semantics beyond the schema. Since schema coverage is high, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It identifies a specific verb ('Create'), a resource (subscription), and differentiates from sibling tools like list_subscriptions and unsubscribe. It also specifies supported subscription types, making the tool's scope 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 gives clear context on when to use the tool (to set up persistent monitoring) and prerequisites (requires Pipeworx OAuth). It mentions 'pull via recent_alerts' as an alternative for consuming the feed, but doesn't explicitly contrast with other tools or state when not to use it. Thus, it provides good context but lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: results are drawn from a live catalog of thousands of tools, output is category-bucketed, and behavior varies based on whether topic is omitted or provided. 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 a dense paragraph but every sentence earns its place: example queries, return content, usage variants, and positioning. It could be slightly more scannable with bullets, but it is well-organized and not bloated.

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 conveys what the tool returns (category-bucketed example questions with tool+argument shapes) and covers both invocation modes (no args vs. topic). It also mentions the live catalog source, making it complete for an onboarding tool.

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

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

Schema coverage is 100% and already explains the topic parameter with allowed values and the 'omit for cross-category spread' behavior. The description only repeats examples (finance, pharma, betting) without adding new semantic information, so baseline 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point for new agents, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by being the 'FIRST' tool to use and explicitly names the meta-tools it helps you learn.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This tells when to use it, and the topic parameter is explained. However, it does not explicitly mention when NOT to use it or name alternative tools like discover_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?

Beyond the annotations (idempotentHint, destructiveHint), the description adds crucial behavioral details: ownership enforcement (only own subscriptions) and that the row is deactivated rather than deleted, preserving historical events. This is valuable context not present in 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 three sentences, front-loaded with the primary action, and every sentence adds unique value: the action, the ownership constraint, and the deactivation behavior. No wasted words.

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

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

For a simple one-parameter tool with rich annotations and full schema coverage, the description covers all essential aspects: what it does, who can use it, what happens to the data, and where historical data remains visible. No output schema is needed for this level of simplicity.

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

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

The schema already provides a complete description for the single parameter (id: 'Subscription id (uuid) returned by subscribe.'). The tool description adds no additional meaning beyond restating 'by id', so the schema carries the burden and a baseline score of 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by id, with a specific verb resource pair. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation and noting the deactivation behavior.

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: to cancel a subscription, with ownership enforcement. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous and the mention of recent_alerts implicitly points to related functionality.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description goes well beyond these by explaining the two-path routing (SEC EDGAR vs grounded pipeline), the meaning of each verdict especially could_not_verify versus unsupported, the inclusion of verification_error{stage,detail}, and the pipeworx:// citation format. This is substantial behavioral context that annotations do not capture, and there is 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 each sentence adds distinct value: purpose and trigger phrases, routing rules, return structure, error-handling caveats, and the efficiency benefit. It is front-loaded with the core function and uses punctuation to pack information efficiently. It is not overly verbose for the complexity it covers, though a slight tightening could improve scannability.

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

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

For a tool with no output schema, the description is unusually thorough. It lists all possible verdicts, explains the error object for could_not_verify, describes the returned actual value with citation and reasoning, and covers the fallback routing logic. This fully compensates for the lack of an output schema and leaves no major gaps for the agent to 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?

While the input schema already describes both parameters (100% coverage), the description adds meaningful operational detail for tolerance_pct: it gives the valid range (0.5–50), explains it overrides the claim wording, suggests 1–2 for hallucination detection, and states the default cap of 5. The claim parameter is also given additional examples in the schema, and the description reinforces them. This goes beyond 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 clearly states the tool's purpose as natural-language claim verification against authoritative sources, with specific trigger phrases like 'fact check' and 'verify the claim that'. It distinguishes itself from siblings by describing its aggregated pipeline that replaces 4-6 sequential calls, making the function's role unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', giving a clear when-to-use. It also differentiates between company-financial claims and other factual claims via the routing logic. However, it does not explicitly state when NOT to use the tool or name alternative tools, so it falls 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.