Deps Dev

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: that it probes external LLMs, requires a BYO Anthropic key (with direct billing), and returns per-model structured output. This goes beyond the annotations without contradicting them.

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

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

Three sentences, each earning its place: first states the core function, second explains configuration and cost, third describes output and use cases. Front-loaded and free of wasteful content.

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

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

No output schema exists, but the description discloses the return structure ({score, confidence, signals, raw_response} plus combined view). Combined with full schema coverage and rich annotations, the tool is well-understood. Minor gap: no mention of error behavior (e.g., invalid API key or model failure).

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

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

Schema covers 100% of parameters with descriptions. The description adds context about the default model and the cost implications of _apiKey, but largely repeats schema information. Baseline 3 applies because the schema already documents each parameter adequately.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and outcome (visibility score 0-100 per model). It is clear but does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, which may overlap in competitive monitoring use cases.

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 context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving implied usage guidance. It does not explicitly mention exclusions or alternative tools, but the listed use cases make the intended scenarios clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the tool's routing behavior, that it fills arguments automatically, returns structured answers, emits stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. This is substantial behavioral context that annotations do not capture.

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 (~200 words) but every section earns its place: it front-loads the priority instruction, provides domain coverage, gives usage guidance, examples, and alternative tools. The density is justified for a central default tool, though it could be tightened slightly without losing key information.

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

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

Given the tool's complexity as a meta-router and the absence of an output schema, the description provides a complete picture: it explains the source corpus, routing behavior, citation format, supported domains, example queries, and escalation paths to sibling tools. The agent has enough context to select and invoke this tool appropriately.

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

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

The schema already documents the 'question' parameter and five aliases at 100% coverage. The description adds value by providing concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifying that the tool accepts natural-language requests, which helps the agent form effective queries beyond the schema's alias list.

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

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

The description clearly identifies the tool as a fact-lookup router that answers factual questions about real-world data by selecting from 5,358 tools across 1,395 sources and returning structured answers with citation URIs. It uses a specific verb ('routes', 'returns') and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use guidance, naming alternatives: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions, and notes that ask_pipeworx already handles breaking news. It also lists concrete example queries and trigger phrases.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and the description complements this by explaining beta status, candidate routing, and that it is a full working router with no fallback failure. It adds context on live experiment comparisons, which aligns with and enriches the annotation 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 four sentences longer than the minimal two-sentence example, but every sentence contributes unique beta-context info. It is front-loaded with 'Beta version of ask_pipeworx', making the core distinction immediately clear.

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

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

With a single required parameter, strong annotations, and full schema coverage, the description is sufficiently complete. It references the same response shape as ask_pipeworx and clarifies the beta nature, though it doesn't spell out the exact response structure, which is acceptable given no output schema and sibling reference.

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

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

Input schema covers 100% of parameters with descriptions for each alias, so baseline is 3. The description only says 'same arguments', which adds no additional meaning beyond the comprehensive schema.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,358 tools and arguments. It distinguishes itself from the stable ask_pipeworx and grounded variant by being the experimental edge, satisfying the specific verb+resource+distinction criterion.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', giving a clear when-to-use scenario. It also notes it currently matches ask_pipeworx exactly, but does not explicitly name ask_pipeworx as the stable alternative, so it slight misses a full when-not-to-use.

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

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

Discloses behavioral traits beyond annotations: exact return shape, refusal reasons, the constraint of using only tool result content, and the extra LLM call cost. Annotations declare read-only and open-world hints, and the description enriches this with concrete failure modes and output schema. No contradiction with annotations.

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

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

The description is long but every sentence provides critical information: mechanism, comparison, output format, use cases, cost tradeoff. It is front-loaded with the core purpose and structured with explicit refusal reasons. No wasted words.

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

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

Despite having no output schema, the description provides a full return contract including success and refusal shapes. It covers when to use, when not to use, cost implications, and comparative behavior. For a tool of this complexity, the description is complete.

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

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

Schema coverage is 100% — all six parameters are documented as aliases for 'question'. The description adds no additional parameter-specific meaning, but the schema already fully explains the single semantic parameter. Baseline 3 is appropriate since the description does not need to compensate.

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: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from ask_pipeworx by emphasizing grounded extraction and the refusal mechanism. The verb 'extracts' with specific output structure makes the function 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?

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). Names the sibling tool directly and explains the cost tradeoff. This is exemplary 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?

The description extensively discloses behavioral traits beyond the annotations: resolver contract (market_match_confidence, alternatives), low-confidence short-circuit behavior, closed/inactive market handling, wide-spread illiquidity warnings, news fallback logic, and cancellation-rule risk. It even mentions that resolved markets usually surface via the low_confidence_match path and that both routes are blocking. This adds far more context than the readOnly/openWorld/idempotent hints 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 long but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Most sentences provide valuable details, but some examples (e.g., Hormuz bet, NVDA-vs-AAPL) are verbose and could be condensed without losing critical information. It earns a 4 for organization but not a 5 due to 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 accounts for return values and edge cases: result.market, result.analysis, result.evidence, resolver fields, parent_event extractor, news fallback fields, and status codes for low-confidence/closed markets. It also includes cancellation-rule risk and liquidity warnings. The description is complete enough for an agent to use the tool correctly, given the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the market parameter's accepted formats (slug, URL, question text) but does not add substantial new meaning beyond the schema. It repeats examples from the schema and clarifies the 'depth' and 'include_raw' behavior that is already in the schema 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and mechanism (pulling Pipeworx data with fan-out). It also differentiates from siblings by focusing specifically on bet research with category-specific data packs and market-vs-model comparison.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives examples of fan-out for various bet types. However, it does not explicitly mention when not to use it 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.

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond this by detailing exactly what data is pulled for each type (company: 10-K revenue/net income/cash/long-term debt from SEC EDGAR; drug: FAERS counts, FDA approvals, trials), how off-calendar fiscal years are handled, and that results are sorted by primary metric. It also discloses the output format (paired data + citation URIs). This is rich behavioral context 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 compact yet information-dense. It front-loads the core purpose and trigger phrases, then systematically covers data sources, sorting, and output format. Every sentence earns its place; there is no filler or repetition of what the schema already provides. The length is appropriate for a tool with this complexity.

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

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

For a tool with only 2 parameters, no output schema, but non-trivial behavior, the description is remarkably complete. It covers supported entity types, data sources, fiscal-year handling, sorting, and output citation URIs. It gives enough context for an agent to correctly invoke the tool without needing external documentation, making it fully contextualized.

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 significant meaning beyond the schema: for 'type' it explains what each enum value actually retrieves, and for 'values' it gives concrete examples and clarifies output sorting behavior. It doesn't cover edge cases like invalid tickers, but the added context is clearly valuable.

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 trigger phrases and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly identifies the verb (compare), resource (companies/drugs), and scope, while distinguishing itself from sequential single-entity lookups. This fully achieves purpose clarity.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists concrete trigger phrases like 'X vs Y' and 'rank these companies.' It also contrasts the tool against sequential lookups, making when-to-use and when-not-to-use unambiguous, even though a specific sibling name isn't given.

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?

Despite annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds substantial context: account/plan requirements, parallel tool routing, gaps[] for unanswered facets, no invention, citations with hop fields, contradiction scanning, semantic excerpting, and expected latency. This goes well beyond the annotations.

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

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

The description is long but every sentence is information-dense and earns its place. It front-loads critical access requirements, then explains the core mechanism, alternatives, behavioral nuances, and performance expectations. No fluff or redundancy 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?

For a complex tool with high risk of misuse, the description covers all necessary context: use cases, alternatives, limitations (e.g., gaps for non-structured topics), output format (findings packet with evidence, confidence, source, citations, gaps, contradictions), and timing. Since there is no output schema, the description appropriately explains return values.

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 both params have descriptions, but the description adds meaningful semantic detail: it explains the depth levels in more depth (quick=3, standard=5 default with gap recovery, thorough=8 paid with iterative hop) and clarifies that the question can be broad/multi-part. This enriches the schema substantially.

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: grounded multi-source research across Pipeworx's structured data sources in one call, decomposing questions into facets and routing them to 5,358 tools in parallel. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and clarifying 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?

Explicit when-to-use guidance is provided: best for broad/multi-part questions over structured data, while single lookups should use ask_pipeworx and breaking/current news should prefer ask_pipeworx. It also states account requirements and that ask_pipeworx works on every tier if not signed in, plus depth-level recommendations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return type (resolved dependency graph) but does not elaborate on behavior such as whether transitive dependencies are included, pagination, or rate limits.

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

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

The description is extremely concise at one short phrase. It is not verbose and the core idea is present, but it reads more like a fragment than a full sentence, slightly undermining clarity.

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 three required parameters and an output schema, the description is minimal but not entirely inadequate. It conveys the primary purpose, but omits details about the graph structure, scoping, or relationship to sibling tools like scan_dependency, leaving room for ambiguity.

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

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

Schema description coverage is 0%, and the description only repeats the parameter names (system, name, version) without adding meaning. The examples in the schema hint at valid values (NPM, MAVEN) but are not part of the description, so the description fails to compensate for the lack of parameter documentation.

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

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

The description clearly states the tool returns a resolved dependency graph for a given system, name, and version triple. It is specific enough to distinguish it from generic query tools, though it lacks a verb and does not explicitly differentiate from sibling tools like scan_dependency.

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. There is no mention of suitable scenarios, prerequisites, or explicit exclusions, leaving the agent to infer usage from the description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds beyond annotations by explaining the return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is valuable behavioral context not captured in 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 well-structured: purpose statement, usage context, return behavior, and priority instruction. The domain list is somewhat lengthy but serves as concrete examples, so it earns its place. It is not overly verbose yet front-loads the essential 'find tools' message.

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 a read-only discovery utility with no output schema. The description covers what it does, when to use it, what it returns (including immediate callability of results), and the input style. Annotations handle safety. This is fully 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 description coverage is 100% – every parameter, including aliases, is described with natural language expectations and examples. The description does not add new parameter-level detail beyond the schema, though it implicitly illustrates query formulation through its domain list. At baseline for full schema coverage, a 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task' – a clear, specific verb+resource pair that immediately distinguishes this as a discovery tool. It further differentiates from siblings by listing concrete domains (SEC filings, FDA drugs, etc.) and explicitly stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

Provides explicit when-to-use context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies when not to use it by saying '(not just one answer)', directing agents to direct lookup tools for single answers.

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

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

Beyond annotations (read-only, open-world, idempotent), it discloses that the call fans out across multiple sources, returns a specific list of fields, soft-fails on the USPTO PatentsView API due to sunset, and uses a fallback chain (GDELT→GNews). This adds meaningful behavioral context.

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

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

The description is dense and front-loaded with examples, then details the fan-out structure and return fields. Every sentence adds useful information, though it is longer than strictly necessary; still, given the complexity, this is appropriately sized.

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 full responsibility for explaining return values. It does so comprehensively: cik + company_name, recent_filings with pipeworx URIs, fundamentals fields, patents, news, and LEI. It also explains the patents soft-fail and name resolution prerequisite.

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 well: type enum with only 'company' and value with ticker/CIK examples and the name-not-supported caveat. The description adds example values but no substantive new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: building a full cross-source profile of a US public company in one parallel call. It includes concrete example queries and explicitly distinguishes this tool from chaining single-pack lookups and from resolve_entity.

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?

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also says names are not supported and to use resolve_entity first if only a name is available, giving clear when-to-use and 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds 'previously stored' and 'saved earlier' context but does not disclose additional behavioral traits beyond annotations (e.g., what happens if the key doesn't exist). No contradiction found.

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

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

Two sentences, no filler. The first sentence front-loads the action and object; the second provides usage context and sibling references. Every word earns its place.

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

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

The tool is simple (1 required parameter, no output schema). The description explains what it does, when to use it, and how it relates to sibling tools. It does not describe return values or error behavior, but that is not expected given the lack of output schema and the annotations covering safety.

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 for the single parameter 'key' with description 'Memory key to delete'. The description adds no extra meaning beyond the schema; it only repeats 'by key'. The schema already does the heavy lifting.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and the resource ('memory'). It distinguishes the tool from siblings like 'remember' (store) and 'recall' (retrieve) by explicitly naming them in the usage guidance.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools ('Pair with remember and recall'), giving clear situational 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 as readOnly, openWorld, and idempotent. The description adds valuable process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output as a single text blob, providing context beyond the structured data.

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

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

The description is compact and front-loaded, with the main purpose in the first sentence, process in the second, and use cases in the third. Every sentence adds value and there is no redundant information.

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

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

For a tool with only two parameters and no output schema, the description fully covers what it does, how it works, output format, and use cases. It is self-sufficient for an agent to decide when to use it and what to expect.

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

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

Schema description coverage is 100%, so the parameters url and max_links are well-documented in the schema. The description adds no additional parameter-specific details beyond saying it fetches the page, which is already implied. Baseline 3 is appropriate since the schema carries the load.

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: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb and resource, and distinguishes itself by explaining the output format and use cases, which sets it apart from sibling tools like scan_competitor_ai_presence.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It lacks explicit alternatives or when-not-to-use guidance, but the context is sufficient for most selection scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating it returns active subscriptions and lists specific fields, which is useful beyond the annotations. No contradictions found.

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

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

The description is three concise sentences, front-loaded with the core action, followed by return fields and usage guidance. Every sentence adds value with no 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 list tool with one optional parameter and no output schema, the description is complete: it states the purpose, scope, return fields, and when to use it. The sole parameter is documented in the schema, and the return format is explicitly enumerated.

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

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

Schema description coverage is 100%: the only parameter, include_inactive, is fully described in the schema. The description does not add extra meaning beyond the schema, but the baseline of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and differentiates from siblings like subscribe and unsubscribe by focusing on the listing action. It also enumerates the returned fields, leaving no ambiguity about what the tool does.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent exactly when to invoke this tool relative to subscribe and unsubscribe workflows.

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. The description adds that it fetches metadata and the type of return data, but does not disclose additional behavioral aspects like error handling on invalid package names or rate limits. Given the strong annotation coverage, this is adequate but not rich.

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

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

The description is a single sentence that is front-loaded with the core action ('Fetch deps.dev metadata'), enumerates the ecosystem values, and lists the return values. Every phrase adds value with no wasted words.

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

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

The tool has only two parameters and an output schema, so the description covers the essential aspects: what it does, how to call it, and what to expect. It omits edge-case details like invalid ecosystem handling, but for a simple read-only lookup, this 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?

Schema coverage is only 50% because 'name' lacks a description. The description compensates by explicitly explaining that 'name' is an open-source package name and 'system_' is one of the supported ecosystems, listing all allowed values. This adds meaning beyond the schema, especially for the undocumented 'name' parameter.

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

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

The description clearly states the tool fetches deps.dev metadata for an open-source package by ecosystem and name, and specifies the exact return values (version list, latest version, linked source repository). This distinguishes it from sibling tools like 'dependencies' or 'scan_dependency' by focusing on package metadata rather than dependency relationships.

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

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

The description implies its usage context: when you need package metadata from deps.dev. However, it does not explicitly mention alternatives or when not to use it, such as 'use dependencies instead for dependency analysis'. This is clear context without exclusions, so a 4 is appropriate.

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 important behavioral traits beyond the annotations, which are all false and offer little safety/side-effect info. The description states 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota,' plus the social effect 'team reads digests daily and signal directly affects roadmap.' No contradiction with annotations exists.

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

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

The description is concise yet information-dense. Every sentence earns its place: purpose, use-case categories, content guideline, roadmap impact, rate limit, and quota exemption. It is front-loaded with the core action and uses clear, scannable language 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?

For a feedback tool with 3 parameters (including a nested object) and no output schema, the description fully covers what, when, how, and consequences. It also explains the social effect and rate limiting, which are critical for agent decision-making. Nothing essential is missing.

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

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

The schema already provides 100% parameter coverage with rich descriptions for type, context, and message. The description adds extra guidance for message content: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes slightly beyond the schema by prescribing how to formulate the message, meriting a score above the baseline.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This distinguishes it from all sibling tools, none of which are feedback-related. The verb 'Tell' plus the resource 'Pipeworx team' makes the purpose unmistakable.

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

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

Explicitly lists 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).' It also provides a negative constraint: 'don't paste the end-user's prompt.' This gives the agent clear decision criteria with no ambiguity.

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds valuable context: caching behavior (5min-1h), aggregation from CF analytics-engine, absence of PII, and the exact data shape (pack, tool, count). This goes beyond the annotations without contradicting them.

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

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

The description is moderately sized with five sentences, each providing distinct value: purpose, return data, use cases, data source, and caching. The use-case list is a bit verbose but not wasteful. It is front-loaded and well-structured.

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

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

With no output schema, the description sufficiently explains return content (top tools, top packs, total call volume) and even the underlying data format. It also covers caching and the source of the signal, making it quite complete for a straightforward read-only 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 for the only parameter (window) is 100%, so the baseline is 3. The description adds meaningful interpretation: shorter windows surface what's hot right now, longer windows show steady-state demand. This extra semantic context justifies a 4.

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

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

The description clearly states what the tool does: it returns trending AI agent calls, specifically top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings by focusing on aggregated trending signals rather than general discovery or querying.

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 provides three concrete use cases, which is strong guidance. However, it does not mention when not to use the tool or suggest alternative tools, so it falls short of the 5-level criteria for explicit when-not/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 extensively discloses behavioral traits beyond annotations: fill check against live CLOB depth, semantic anchor Jaccard similarity, partition filter placeholder handling, and when not to trade (realizable_edge_pp <= 0). These add significant context beyond the readOnly/openWorld/idempotent 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 provides necessary operational detail. It is front-loaded with the core purpose, then organized by mode, with filters and fill-check explanations. Dense but not wasteful.

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

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

Given no output schema, the description explains the response structure (opportunities[], partition_check fields, fill_check fields) and covers failure/edge-case behaviors. It is complete for a complex tool with multiple modes.

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 solid parameter descriptions, but the tool description adds substantial meaning: examples of event slugs, full URL acceptance, topic seed question examples, and details on how each mode behaves. This goes well beyond the schema 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific modes (trending_scan, event, topic). It is a specific verb+resource+scope, but it does not explicitly distinguish itself from the sibling tool polymarket_edges, which may overlap in 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?

Provides explicit guidance: call with no args for trending_scan, pass event for a specific market, pass topic for cross-event scanning. It recommends event mode for specific markets and points to polymarket_fill_risk for custom sizing, giving clear when-to-use and alternative 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 description goes well beyond the read-only/idempotent annotations, explaining the three model segments, how edge is calculated net of slippage, the special 'kelly_fraction_half=0' behavior for partition_overround, the 24h-move warning, the Fed-signal unreliability caveat, and caching behavior. This gives agents a detailed mental model of what happens inside the tool.

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

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

The description is dense and front-loaded with the purpose, then systematically details segments, knobs, response structure, diagnostics, and caching. Every sentence carries technical substance, but the sheer length and packed parentheses make it somewhat overwhelming. An even more structured breakdown would improve clarity, but it is still 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?

With no output schema, the description carries full responsibility for explaining the response format. It enumerates the top-level keys (by_segment, fed_candidates/fed_note, _diagnostics), the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the diagnostics funnel counters that help explain why a segment is empty. This is remarkably complete for a tool with 9 parameters and no structured output definition.

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

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

Although schema coverage is 100%, the description adds significant meaning: it groups min_liquidity and max_spread_pp as 'tradeable-edge knobs', explains that min_partition_leg_kelly applies to per-leg Kelly because parent-level Kelly is 0 by design, and gives rationale and example values (e.g., 'set to 5000 to drop thin-book opportunities'). This is far 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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage (different focus) and explains the intended use case ('what should I bet on today').

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: it is built for discovering opportunities without paging hundreds of markets, and mentions the 'what should I bet on today' use case. However, it does not explicitly name alternative tools or state when not to use this tool, 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.

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds extensive behavioral context: snapshots are written on cache-miss so gaps occur, history is bounded by a 60-day TTL, decay uses daily closes net of default slippage, and expired opportunities are detailed with lifespan. No contradiction with annotations.

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

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

The description is front-loaded with the core question and example, then structured into Args, RESPONSE, and LIMITS sections. Despite being long, every section earns its place by explaining behavior that is not obvious from the schema or annotations, making it appropriately sized for a telemetry tool with no 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?

With no output schema, the description fully documents the return structure: tracked[] with fields, expired[] with lifespan_days, and snapshot_dates[] with explanation of gaps. It also covers limitations (TTL, daily closes, net slippage), making the tool safe to invoke without additional 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?

Schema coverage is 100%, so baseline is 3. The description adds conceptual meaning by calling days a 'lookback' and window a 'snapshot family,' which clarifies how parameters relate to the data collection process. It also notes defaults ('default 14, max 30') that align with the schema, reinforcing but not merely repeating it.

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

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

The description clearly states a specific purpose: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence rather than current edges, and uses a concrete example to illustrate the distinction.

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 this tool—when you need to know edge persistence and decay. It implicitly contrasts with polymarket_edges by saying it is 'built from daily polymarket_edges snapshots,' and notes that a fresh wide edge is a different trade from a 3-week-old one. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already note readOnlyHint=true, but the description adds substantial behavioral context: 'walks the ladder', 'returns top_of_book, vwap_fill_price, slippage_pp', and warns that 'theoretical overround on thin books is not capturable' and that 'partial basket fills convert an arb into an unhedged directional position'. This goes far beyond the annotation hints, revealing internal logic and failure modes. 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: purpose sentence, mode requirements, SINGLE-MARKET and BASKET sections, and a closing usage directive. Every sentence carries essential operational detail, so it's not padded. However, it could be slightly tightened in the BASKET section, which lists many output fields in one breath. Still, for the tool's complexity, it's near-optimal.

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

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

Given there is no output schema, the description fully enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.). It also explains edge cases like forced_directional_risk and max_clean_notional_usd. For a complex dual-mode tool with no output schema, this is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning: it explains that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode, clarifies default side auto-selection based on partition sum, and notes the clamp range. This substantially enriches the bare 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines the tool's role as a fill-risk validator. It also distinguishes itself from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as the signals/trades it should precede, establishing a 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?

Usage guidance is explicit: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also details two modes (single-market vs basket) and explains when each applies, with a clear warning about thin books and partial fills. This is strong when-to-use and alternative differentiation.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the agent knows the tool is safe to call repeatedly. The description adds substantial behavioral detail: compatibility_warning conditions, temporal_alignment flag, skipped_cross_type counters, and the nuance that non-equivalent bet shapes mean no arbitrage exists. These insights go well beyond what annotations provide and are crucial for correct interpretation of results.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and organized with capitalization for readability. It is front-loaded with the core purpose and every sentence adds operational value; there is no filler. The length is justified by the tool's complexity, so it earns a 4 rather than a lower score for verbosity.

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

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

With no output schema, the description carries the full burden of explaining the response shape and edge cases. It does so thoroughly: matched spread, top_spreads_pp, compatibility_warning scenarios, temporal alignment, and skipped counters are all described. For a tool with this level of cross-venue matching complexity, the description is complete enough for an agent to know what results to expect and how to interpret them.

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 all three parameters with examples and descriptions, so baseline is 3. The description adds meaning by listing the full set of topic shortcuts, explaining the override relationship between topic and explicit identifiers, and connecting parameters to tool behavior (e.g., custom pairings). This lifts it above baseline, though not to 5 because a few edge-case param behaviors could be more explicit.

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 clear statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the specific verb+resource (compute/show spread between two venues) and the two modes add further specificity. This distinguishes it from siblings like polymarket_arbitrage, which focuses on a single venue's arbitrage opportunities.

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

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

The description explains both invocation modes (topic shortcuts vs explicit kalshi_event_ticker/polymarket_event_slug) and provides a strong caution that pre-mapped topics often return compatibility_warning, implying when the tool may not be useful. It does not explicitly reference alternative tools by name, but the contextual guidance on interpreting results and the 'pre-mapped ≠ tradeable' warning provide solid usage direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by disclosing what the tool returns: scorecard scores, version count, and linked package references, and clarifies acceptable repository types. This goes beyond the annotations without contradicting them.

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

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

The description is a single, well-structured sentence that front-loads the primary action ('Fetch deps.dev project metadata'), includes a concrete example, and states the return fields. Every element earns its place with no redundant or filler content.

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

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

Given the tool's simplicity (2 params, no nested objects, output schema present) and the annotations covering safety, the description is largely complete. It explains the return contents and input format, but does not mention any limitations (e.g., public-only repos or rate limits), which could be useful but is not essential given the output schema.

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

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

Schema coverage is 100%: both parameters (project_key and project_type) have descriptive values (example for project_key, enum-style hint for project_type). The description reinforces the project_key example but adds no new parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses the specific verb 'Fetch' and names the exact resource ('deps.dev project metadata'), with clear scope ('for a GitHub, GitLab, or Bitbucket repository') and an illustrative example (project_key="facebook/react"). This distinguishes it from sibling tools like 'package' and 'dependencies' by focusing on repository-level metadata.

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 clearly implies when to use it: when you need project metadata for a hosted repository. However, it does not explicitly list alternatives or conditions where another tool should be used instead, such as 'package' for package-level metadata, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which convey the safety profile. The description adds that the tool accepts queries by hash or repo URL, but it does not describe behaviors like pagination, result limits, or error handling. This is acceptable given strong annotation coverage, but the description contributes only modestly beyond annotations.

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

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

The description is a single sentence, front-loaded with the verb and resource, and contains no superfluous content. It is highly concise and well-structured for quick parsing.

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

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

The tool has one parameter with good schema examples, an output schema, and comprehensive annotations, so the description does not need to explain return values or safety. However, it omits details about the breadth of query types ('etc.') and any limitations, making it adequate but not completely self-sufficient.

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

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

The schema has 100% coverage with a description and examples for the single 'query' parameter. The tool description adds concrete semantics by specifying query criteria (hash, repo URL, etc.), enriching the abstract 'Query body' from the schema. This elevates the value beyond the schema alone, though the 'etc.' remains vague.

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: querying packages/versions with specific criteria like hash or repo URL. The verb 'query' and resource 'packages/versions' are specific, though the trailing 'etc.' introduces some vagueness and does not explicitly distinguish this tool from siblings like 'package' or 'dependencies'.

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

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

The description implies when to use the tool—when you need to query packages/versions by hash, repo URL, or similar identifiers—but it does not explicitly mention alternatives or when not to use it. The context is reasonably clear but lacks explicit 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?

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description need not repeat them. It adds valuable context about scoping to the agent's identifier and the behavior of omitting the key argument to list all keys.

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 tight sentences cover operation, use case, and companion tools, with no filler or repetition.

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

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

The tool is simple (one optional parameter, no output schema), and the description covers purpose, usage, and scoping. However, it never explicitly describes the return value's shape, relying on inference from 'retrieve a value' and 'list all saved keys.'

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 fully documents the `key` parameter with 100% coverage, but the description enriches it with concrete examples (target ticker, address, research notes) and clarifies the omission behavior.

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

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

The description opens with a precise action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This explicitly names the sibling tools `remember` and `forget`, distinguishing it from related memory 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?

It states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides alternatives: 'Pair with remember to save, forget to delete.'

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details beyond this: each event carries source, citation_uri, and raw payload; mark_read:true changes read state so subsequent calls only show newer events; and the feed is persisted. It also notes polling works, enriching the understanding of tool behavior without contradicting annotations.

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

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

The description is front-loaded with the core action in the first sentence, then logically covers return format, filtering, state behavior, and alternative access. It is slightly long but every sentence earns its place, with no redundant or vague phrasing.

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 sufficiently explains the return payload (source, citation_uri, raw event payload) and covers filtering, state mutation, polling, and an alternative external endpoint. The 5 parameters are well documented in the schema, and the description's additional examples make the tool fully understandable 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%, so all parameters are already described. The description adds meaning by giving a concrete example for 'type' ('sec_8k'), specifying the ISO timestamp format for 'since', and explaining the state-changing effect of mark_read on future calls. It does not cover limit and unread_only, but those are adequately handled by the schema.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from siblings like list_subscriptions, which manages subscriptions, not events. It also specifies the return type ('recent alerts') and filtering capabilities, making the tool's purpose unambiguous.

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

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

The description provides clear context by stating the tool pulls events, supports polling, and mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly name sibling tools as alternatives or state when not to use the tool, so it falls short of full exclusion guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context beyond those hints: parallel fan-out to SEC EDGAR, GDELT/News fallback on rate limits or 5xx, USPTO soft-fail until reactivated, and the structured return shape with citation URIs.

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 dense, the description earns its length for a multi-source, multi-parameter tool. It is front-loaded with natural-language query examples, then explains sources, parameters, and output in a compact flow. No filler or redundant repetition.

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

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

With no output schema, the description compensates by naming the output fields: changes[], total_changes, and citation URIs. It also covers all relevant sources, fallback logic, and soft-fail behavior, making it complete enough for invocation and result interpretation.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds practical guidance on 'since' formats ('7d', '30d', '3m', '1y') and even recommends '30d' or '1m' for typical monitoring, which goes beyond the schema text.

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 opens with concrete user-intent examples and states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly contrasts with entity_profile, which is for static profiles, making the purpose and scope 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?

Gives explicit when-to-use context with sample phrasings and clearly names the alternative: 'Use entity_profile instead when you want the static profile...' It also describes source fallbacks and soft-failure behavior, helping decide if this tool fits the request.

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 the annotations: persistence differences for authenticated users, 24-hour retention for anonymous sessions, and scope by identifier. It does not contradict the idempotentHint or readOnlyHint annotations. It lacks details on overwrite behavior or errors, but idempotence is already annotated, and the added storage context is valuable.

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

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

The description is four sentences, each serving a distinct purpose: core function, usage guidance, storage details, and pairing with related tools. It is front-loaded with the primary action, avoids redundancy, and contains no filler.

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

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

Given the simple two-parameter tool with full schema coverage and no output schema, the description covers all essential aspects: purpose, when to use, storage behavior, retention, and related tools. It leaves no significant gaps for an agent to know how to select and invoke this tool.

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

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

The schema description fully covers both parameters (key and value) with examples. The description adds usage context but does not significantly expand parameter semantics beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, specifies the key-value storage format, and distinguishes itself from the sibling tools recall and forget by naming them as counterparts. The verb 'save' and resource 'data' are specific, and examples of content (ticker, address, preference) clarify the 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?

It explicitly states when to use the tool ('Use when you discover something worth carrying forward') and provides concrete examples. It also names the alternatives (recall for retrieval, forget for deletion), giving clear guidance on when to use this tool versus related ones.

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 traits. The description adds valuable context: returns specific fields (ticker, CIK, company_name, citation URIs; RxCUI, ingredient, brand), accepts ticker/CIK/names, auto-disambiguates, and reveals internal cascading through lookup endpoints. This goes beyond the annotations and gives expectations about behavior and cost.

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

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

The description is moderately long but well-organized, with a heading for supported types and a clear logical sequence. The opening example phrases are illustrative rather than wasteful, and each sentence adds relevant detail. It is slightly dense in the supported-types section but remains scannable.

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

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

For a two-parameter lookup tool with no output schema, the description adequately explains the return fields for each type, accepted input forms, and internal behavior. It doesn't cover edge cases (ambiguities, errors), but it provides enough for an agent to select and invoke the tool correctly in common scenarios.

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 detailed descriptions for both parameters. The description reinforces accepted input formats and adds 'auto-disambiguated' behavior, but largely echoes the schema. It does not significantly extend the parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description uses the specific verb 'resolve' and clearly states it maps a user-spoken NAME to the canonical/official identifier other tools require. It enumerates supported types (company, drug) and their outputs (ticker, CIK, RxCUI), effectively distinguishing it from siblings like entity_profile. The opening example phrases reinforce the intended use.

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 FIRST whenever you have a name but need an ID.' This provides strong when-to-use guidance, but it does not name alternative tools or state when not to use it (e.g., when you already have an ID). The mention of replacing 2-3 manual lookups adds practical 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 description adds meaningful behavioral context beyond the annotations by explaining the probing process (calls ai_visibility_check per entity), the ranking logic, and the return format (ranked list with score, confidence, signal density). It also notes the first entity is treated as the subject, which is useful and not captured by 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 concise, front-loaded with the core purpose, and each sentence adds value. The structure flows logically from what it does, to how it does it, to when to use it, and what it returns. No fluff or redundant wording.

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 provides a complete picture for a tool with moderate complexity and no output schema. It covers the purpose, the process, the return value format, and a realistic use case. Since the schema richly documents all parameters, the description effectively fills the gaps left by structured fields.

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 each parameter described in the schema. The description adds no additional parameter-level semantics beyond what the schema already documents; it only reinforces the entities concept. Baseline 3 is appropriate since the schema carries the full burden of parameter documentation.

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 ('Compare') and resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and mentions the underlying probing mechanism, 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 provides clear context for when to use this tool, citing competitive AI-marketing audits and giving an example use case. It implies the tool is for comparing multiple entities, which differentiates it from single-entity checks, but it does not explicitly name alternatives or state when not to use it.

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior, latency expectations (5-30s for first bundlephobia measurement), the sources_failed field, and ecosystem limitations. This is rich behavioral context that helps the agent anticipate real-world behavior.

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

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

The description is compact yet complete: first sentence states purpose, second gives usage, third enumerates output, fourth notes limitations, fifth explains failure handling. No redundant words; it earns its length.

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

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

For a tool with two external services, no output schema, and partial-failure modes, the description covers purpose, output structure, latency, failure handling, and ecosystem scope. It leaves no significant gaps for an agent to trip over.

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

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

Schema coverage is 100%, so the description need not add parameter meaning. It does add context about the version's effect on first-measurement latency, but that's behavioral rather than semantic. 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 states exactly what the tool does with a specific verb and resource: a composite 'should I add this npm package to my project' check fanning out across deps.dev and bundlephobia. It lists the concrete data points returned, distinguishing it from sibling tools like 'dependencies' or 'package'.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions and alternatives, noting NPM-only in v1 and that other ecosystems fall under deps.dev:version directly.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals concrete behavioral details: the embedding model (BGE-base-en), similarity metric (cosine), windowing strategy (500-char overlapping windows), output characteristics (character offsets and similarity scores), and truncation behavior with a 200K char cap and flag. This far exceeds annotation coverage.

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: it opens with the core action, states the use case, explains the value proposition with offsets, gives a sibling-tool pairing, and closes with technical specifics. Every sentence contributes unique information 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?

Even without an output schema, the description fully explains what the agent will receive (top-N passages, character offsets, similarity scores). It covers input limits, truncation, algorithm, and intended workflow, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining how 'text' and 'query' interact ('pass the text you already pulled plus a natural-language query'), providing concrete query examples, and giving behavioral context like the 500-char windows and top-N results. This enriches parameter understanding beyond the schema.

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

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

The description uses a specific verb and resource ('Semantic search INSIDE a fetched record'), clearly distinguishing it from sibling tools like ask_pipeworx_grounded by focusing on searching within already-fetched text. It also states the exact scope (top-N passages with offsets and scores), leaving no ambiguity.

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

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

The description explicitly states when to use the tool ('Use when the record is too big to cram into the prompt') and provides a clear pairing with ask_pipeworx_grounded, explaining the workflow: fetch with the gateway, ground over relevant passages. This is excellent guidance for 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?

Beyond annotations (readOnly=false, idempotent, non-destructive), the description discloses multiple behavioral traits: OAuth requirement, always-on feed with pull mechanism, webhook signing secret returned only once, webhook auto-disable after 10 failures, and SMS 10/day cap. This is rich, actionable context that annotations alone do not provide.

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

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

The description is dense but well-organized: purpose, requirements, types, delivery channels. Each sentence contributes necessary information, such as OAuth prerequisites, phone verification, and webhook HMAC specifics. It is long, but every detail earns its place, with no filler or repetition.

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

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

Despite no output schema, the description compensates by stating 'Returns the new subscription id.' It comprehensively covers all subscription types, delivery channels, constraints (SMS cap, auto-disable), and prerequisites (OAuth). For a tool with this complexity, the description is complete and leaves no critical gaps.

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

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

The input schema already provides elaborate descriptions for all parameters (100% coverage), including type-specific filters and delivery formats. The description largely repeats these details (e.g., sec_8k items, sms format) and adds only minor extras like the OAuth requirement and webhook secret reveal. These extras are more behavioral than parameter semantics, so the description adds limited 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 opens with 'Create a proactive monitoring subscription to a live-data event stream,' clearly specifying the action (create), resource (subscription), and context (live-data event stream). It further differentiates from siblings by detailing supported subscription types and delivery channels, making the tool's purpose unmistakable.

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

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

The description provides clear context for when to use the tool, such as the OAuth account requirement and the always-on feed, but does not explicitly name alternatives like list_subscriptions or unsubscribe. The context is strong enough to infer usage, yet explicit exclusions or comparisons 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?

Beyond the read-only/idempotent annotations, the description discloses that results are drawn from the live catalog and include tool+argument shape for each question, and that it returns category-bucketed examples. It clarifies the tool's role as an onboarding/exploration aid, not a query tool itself.

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

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

The description is longer than typical but each sentence provides distinct value: example questions, return content, parameter behavior, and usage priority. It is front-loaded with the purpose and ends with actionable guidance. Slightly verbose but well-structured.

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

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

The description covers what the tool returns, how to invoke it with and without topic, and when to use it, despite having no output schema. It also names related meta-tools, making the tool's position in the ecosystem clear.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, with the schema already listing allowed values. The description adds a few examples ('finance', 'pharma', 'betting') but no significant new semantic information.

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 onboarding entry point for discovering what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It uses specific verbs and distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the 'what can I ask' starter.

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 use this tool FIRST when unsure what Pipeworx can do, and mentions learning to call meta-tools such as ask_pipeworx, entity_profile, compare_entities. Also explains the no-argument vs topic behavior, giving clear context for invocation.

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

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

Discloses that the row is deactivated rather than deleted, and explains the consequence (historical events remain available via recent_alerts). This goes beyond the annotations' safety hints, which only indicate non-destructive and idempotent behavior.

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

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

Two sentences with no filler. The first sentence states the action, the second adds constraints and side effects. Everything present earns its place.

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

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

Given the simple tool signature (one param, no output schema), annotations already describe safety profile. The description covers purpose, ownership, and the deactivation behavior, plus its relationship to recent_alerts. No gaps remain.

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

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

Schema coverage is 100% — the id parameter is fully described as 'Subscription id (uuid) returned by subscribe.' The description adds nothing beyond 'by id,' but the schema already carries the burden.

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 'Cancel a subscription by id,' which is a specific verb+resource pair. It further clarifies the ownership constraint, distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

States when to use (cancel a subscription by id) and an explicit constraint ('you can only cancel your own subscriptions'). Does not explicitly contrast with alternatives like list_subscriptions or subscribe, but the purpose is clear enough.

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

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

The description discloses the tool's behavioral specifics beyond annotations: it returns verdicts with defined categories, uses structured vs grounded pipelines, provides verbatim evidence with citations, and performs judgment. It also notes the tolerance parameter's override and default behavior. This complements the readOnly/openWorld/idempotent hints 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 dense and slightly long, but every sentence contributes important information: purpose, routing logic, output format, and efficiency gains. The structure front-loads example queries and core function, making it easy to scan. However, the 'replaces 4–6 calls' claim is somewhat non-essential for invocation.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description covers all necessary context: input types, output format, tolerance rules, data sources, and routing. It is complete enough for an agent to select and invoke the tool correctly without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by giving concrete examples for the claim parameter and explaining tolerance_pct semantics (override, default cap, and use case for hallucination detection), which enriches understanding beyond the schema.

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

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

The description explicitly names the function as natural-language claim verification with example queries, clearly identifying the verb (verify/validate) and resource (factual claims). It also distinguishes itself from sibling tools by detailing its consolidated pipeline that replaces 4–6 sequential calls, making it 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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It further provides routing guidance (financial claims via SEC EDGAR fast path, any other claim via grounded pipeline), effectively telling the agent when and how to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by specifying the data categories (deps, advisories, license) and the scope (single version), which is useful context beyond the annotations.

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

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

The description is a single, concise sentence that is front-loaded with the core message. It contains no redundant words and is easy to parse quickly.

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 three required parameters and an output schema, so the description does not need to explain return values. However, it lacks usage guidance and parameter semantics, making it minimally viable but with clear gaps in actionable 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?

Schema description coverage is 0%, and the description does not explain any of the three parameters (system_, name, version). The schema provides examples but the description fails to compensate for the lack of parameter semantics, such as valid system_ values or the meaning of the version field.

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 'Single version of a package (deps, advisories, license)' clearly indicates the tool provides information about one specific version of a package and its associated dependencies, advisories, and license. It distinguishes from siblings like 'dependencies' or 'package' by focusing on a single version, though it lacks an explicit verb like 'get' or 'retrieve'.

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 such as 'dependencies' or 'scan_dependency'. There is no mention of scenarios, exclusions, or prerequisites, leaving the agent to infer usage from the sparse description.

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