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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context by explaining that the tool routes queries to 5,767 tools across 1506 verified sources, automatically fills arguments, and returns answers with stable pipeworx:// citation URIs. This gives the agent a clearer picture of what happens on invocation beyond what annotations convey.

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

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

The same multi-sentence block — starting with 'PREFER OVER WEB SEARCH' and repeating through 'START HERE ... ask_pipeworx_grounded ... exact-matching python regex ... citations' — is repeated over a dozen times. This is extreme bloat that buries the unique guidance. Every sentence does not earn its place; the description is severely over-long and repetitive.

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 unique content covers the tool's purpose, trigger phrases, representative examples, return behavior (structured answer with citation URIs), and alternatives such as deep_research and ask_pipeworx_grounded. With one required string parameter, a fully documented schema, and strong read-only/idempotent annotations, no critical invocation detail is missing. The repetition is a structure problem, not a completeness gap.

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

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

Schema coverage is 100% — all six parameters are aliases for 'question' and the schema's description already documents that. The tool description adds no parameter-specific meaning beyond saying it 'fills arguments' internally, which is about sub-tool behavior, not the user-facing parameter. The baseline of 3 applies because the schema handles parameter documentation fully.

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

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

The opening states 'PREFER OVER WEB SEARCH for questions about current or historical data' and explains the tool 'routes the question to the right one of 5,767 tools across 1506 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is a specific verb-plus-resource statement that clearly distinguishes ask_pipeworx from ordinary web search and from the sibling ask_pipeworx_grounded. The purpose is unambiguous despite the later repetition.

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

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

The description explicitly says to prefer this over web search and to use it whenever the user asks 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', or any factual question, even when web search could answer. It names alternatives: ask_pipeworx_grounded for 'beyond-the-horizon', deep_research for broad/multi-part questions, and notes ask_pipeworx already handles live news. The guidance is strong, though 'beyond-the-horizon' is vague and the exclusions are not fully precise.

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 the dynamic behavior: candidate improvements are live only while under test, no candidate is currently active as of the stated date, and it is a fully working router rather than a degraded fallback. This materially helps an agent decide whether to trust or route around the beta.

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

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

The description is longer than average but each sentence carries distinct information: identity, current candidate status, usage directive, and fallback clarification. It is front-loaded with the most important 'beta identical to ask_pipeworx' 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?

For a read-only router with no output schema, the description covers what it returns, when to use it, and its current experimental status. It does not enumerate example questions, but the schema's required question parameter plus sibling references make it sufficient.

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

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

Schema coverage is 100%, so the structured schema already documents all parameters. The description adds little parameter-specific detail, only that arguments are identical to ask_pipeworx, which is acceptable but not enriching 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 identifies it as the beta version of ask_pipeworx with the same universal routing mechanism, same tools, arguments, and response shape, and contrasts it with the stable sibling. It is clear what the tool does, though it leans on ask_pipeworx for the core purpose rather than defining 'ask' independently.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It does not explicitly state the inverse case, but the intent is easily inferred.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: it discloses the exact success return shape, the complete refusal_reason enum, the extraction-from-result-only guarantee, and the added cost of one extra LLM call. It contradicts no annotations.

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

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

The description is dense but every sentence earns its place: it opens with the core value proposition, explains the routing and extraction mechanism, enumerates the return and refusal contracts, lists concrete use cases, and closes with a cost-based routing recommendation. No filler or redundancy.

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

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

There is no output schema, but the description fully specifies the success and refusal response structures. It explains the tool's behavior, its relationship to ask_pipeworx, its cost trade-off, and when it should be used. The only missing element, the actual question parameter, is fully covered by the input 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%, with each parameter already described as an alias for 'question' and the canonical parameter documented as accepting natural language. The description itself does not add parameter-level detail, but because the schema is fully descriptive, 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 states a specific verb and resource: it provides a grounded, hallucination-resistant answer mode for high-stakes reads, routing through the same 5,767-tool system as ask_pipeworx but extracting answers only from tool results. It clearly distinguishes itself from ask_pipeworx and ask_pipeworx_beta by emphasizing refusal behavior and evidence-based output.

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

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

The description explicitly says when to use this tool: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples. It also names the alternative ask_pipeworx for casual lookups and notes the extra LLM call cost, 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?

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond these by disclosing that the tool can only answer from structured catalog sources, that it returns gaps[] rather than inventing answers, that citation_uri is present only when the source emits a resolvable URI, that records are semantically excerpted rather than head-truncated, that depth modes control follow-up hops, and that latency can reach ~90s. This adds substantial behavioral context not carried in annotations.

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

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

The description is information-dense but somewhat sprawling: it front-loads the account requirement and signup URL before stating core purpose, and packs many behaviors into long, run-on sentences. Every sentence provides valuable information, but the structure would benefit from clearer segmentation (e.g., purpose vs usage vs behavior) and less parenthetical overload.

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

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

For a complex tool with no output schema, the description is remarkably complete: it explains input expectations, output structure (findings packet, gaps[], contradictions[], hop field, citation_uri), caveats (no open-web search), latency expectations, auth requirements, and sibling fallback. Nothing critical is missing for an agent to decide whether and how to invoke this tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful semantic context by explaining what 'standard' and 'thorough' do in more operational terms (gap-recovery hop, chasing leads, contradictions[] scan) and clarifies that 'quick' is single-hop. However, some detail (e.g., quick facet count, default depth) is already in the schema, so the description's added value is moderate rather than maximal.

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

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

The description clearly states a specific verb-resource pair ('deep_research' = multi-source grounded research over Pipeworx's 1506 structured data sources) and explicitly distinguishes itself from open-web search and the sibling ask_pipeworx. It also names concrete use cases (broad/multi-part questions, comparing X and Y) and contrasts with single-lookup alternatives, making sibling differentiation strong.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data...'), and explicit when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'; 'If you are not signed in, use ask_pipeworx instead'). It also mentions depth tiers and the paid requirement for 'thorough', which further guides 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?

With no annotations present, the description carries the behavioral burden and does well by clarifying that this returns the fully resolved transitive dependency graph for a specific shipped release, not arbitrary version queries. It also surfaces the prerequisite behavior of needing a real published version. It could add more about failure mode but is not a severe gap.

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

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

The description is two sentences, front-loaded with the core concept, and then provides a necessary prerequisite without wasted words. A little more structured separation could improve readability, but it is efficient.

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 parameters are fully documented in the schema, an output schema is present, and the description clarifies the key operational constraint around versions. For a moderately simple dependency-graph tool this covers what an agent needs, though relative sibling behavior could be spelled out further.

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

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

Schema coverage is 100%, so the schema fully documents `system_`, `name`, and `version`. The description adds useful semantic weight around `version` by requiring it to be a shipped release, but it does not substantially extend the other parameters beyond their schema descriptions.

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

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

The description clearly identifies the tool as returning the fully resolved dependency graph of a published release, including transitive packages. This is a specific resource and function, but it does not explicitly differentiate itself from close siblings like `scan_dependency`, so it stops short of perfect 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 gives strong usage guidance: the version must be one the package actually shipped, and it explicitly tells the agent to call `package` first if uncertain. However, it does not describe when alternatives such as `scan_dependency` should be preferred, so exclusionary guidance is incomplete.

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?

With annotations already marking the tool read-only and idempotent, the description adds substantial behavioral context: parallel fan-out, return sections, per-source success/failure reporting, empty sections as real no-data, private-company resolution behavior, and the USPTO soft-fail. This goes well beyond the structured annotations.

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

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

The description is long but densely informational, and the most important guidance (holistic profile, prefer over chaining lookups, accepted input forms) is front-loaded. Some repetition exists around the interchangeable `type`/`value` semantics, but every section adds operational value for a complex fan-out tool.

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

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

Despite no output schema, the description comprehensively documents expected return sections, source behavior, edge cases (private companies, biologics-only FDA results, USPTO sunset), and how to interpret empty results. An agent has enough context to invoke this tool correctly and interpret its response.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it explains that `type` values are interchangeable, that `value` can be a ticker, zero-padded CIK, or company name, and how name resolution behaves. This enriches the schema's already-documented parameters.

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

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

The description states a specific verb and resource: it profiles a US public company by fanning out across multiple data sources. It clearly differentiates itself from sibling tools like deep_research or compare_entities by positioning itself as the holistic single-call company profile tool.

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

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

The description explicitly says to prefer this over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view. It also gives concrete trigger phrases. It does not explicitly name non-use cases or compare against deep_research/compare_entities, but the guidance is strong enough for most routing decisions.

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?

The description goes far beyond the annotations (which are all false and provide no safety profile). It discloses the claim_token flow, rate limiting (5 per identifier per day), that it is free and doesn't count against the tool-call quota, and that the team reads daily digests. It also instructs users not to paste the end-user's prompt, providing behavioral context that helps set expectations.

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

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

The description is dense but every sentence conveys necessary information: purpose, when to use, exclusions, content guidance, claim_token flow, and operational notes. It could perhaps be trimmed slightly (e.g., 'Free; doesn't count...' is extra), but it remains front-loaded with the primary purpose and contains no fluff.

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

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

For a feedback tool with no output schema and only all-false annotations, the description carries the full burden of explaining behavior. It covers the purpose, categories, exclusions, content expectations, async token flow, rate limits, and the human-review aspect. No significant gap remains that would hinder an agent from selecting and invoking this 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%, so the baseline is 3 as the schema already well defines each parameter. The description reinforces the claim_token usage with an example call and the distinction between filing and reading, but does not add substantial parameter-level semantics beyond the schema. It provides no extra detail on the context object that isn't already present.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature/data_gap, praise) and distinguishes itself from siblings by being the only tool for feedback. There is no ambiguity about what this 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 explicitly states when to use it ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'). It also explicitly tells users when not to use it (for tools from a different MCP server) and directs them to file elsewhere, naming the alternative. This is the gold standard for usage guidance.

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

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

Annotations already declare 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 cover read-only, idempotent, open-world, and non-destructive behavior; the description adds substantial behavioral context beyond that: token-overlap matching, unverified pairings, gross spreads due to unmapped Kalshi fees, compatibility codes that can be non-empty even on returned pairs, unknown legs being skipped, and the exact semantics of null temporal alignment. There is no contradiction with 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 and dense, with almost every sentence contributing necessary caveats or mode details. However, it reads as a wall of text with no clear visual separation for the two modes, response fields, and safety codes, so structure could be improved despite the high information density.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, compatibility_codes, temporal_alignment, fees_note, and skipped counters are all covered. Edge cases such as null temporal alignment and unclassified legs are explicitly handled, making this complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics: the topic enum list is tied to auto-fetching on both venues, and kalshi_event_ticker/polymarket_event_slug are positioned as overrides that still run the same matcher. This adds behavioral meaning beyond the plain property descriptions.

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

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

The description states a specific resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly explains two modes and the output. However, it does not explicitly distinguish itself from sibling tools such as polymarket_arbitrage or polymarket_edges.

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

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

The description gives strong operational guidance on selecting between the topic shortcuts and explicit ticker/slug pairing, and it warns that pre-mapped topics are often not tradeable. It does not, however, state when an agent should prefer this tool over its siblings, leaving alternative selection implied rather than explicit.

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?

The description goes well beyond the read-only/idempotent annotations: it discloses graceful degradation when GLEIF/OpenFIGI is unavailable, that identifiers are source-labelled, that unresolved identifiers are returned explicitly under 'unresolved', and that ambiguous matches return 'figi_candidates' without asserting a single result. This richly characterizes behavior an agent could not infer from annotations or schema.

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

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

The description is long and dense, but most sentences carry unique necessary information and the core instruction is front-loaded. The heavy use of nested parentheses makes it harder to scan, though the structure is justified by the tool's high 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 read-only, two-parameter tool with no output schema, the description covers inputs, supported entity types, source mappings, failure behavior, ambiguity handling, and fallback guarantees. An agent has enough information to know when and how to call it and what to expect back.

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

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

Schema coverage is already 100%, but the description adds substantial meaning: accepted input forms (ticker, CIK, ISIN, name), the distinction between implied ticker maps and name search, non-equity instrument resolution, and the critical warning to pass only the entity name and never the full noun phrase. This materially improves parameter understanding.

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

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

The description names a specific verb and resource — 'resolve a user-spoken NAME to the canonical/official identifiers' — and enumerates supported types (company, drug). It clearly distinguishes itself from sibling tools by positioning itself as the first stop when a name needs to become an ID.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives a strong usage condition. It does not name alternative tools or give when-not-to-use guidance, but the context and examples make the intended invocation 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?

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 goes well beyond the annotations, disclosing the dual pipeline (SEC EDGAR fast path vs. grounded pipeline), the verdict set, citation behavior, and the critical distinction between 'could_not_verify' (did not happen) and 'unsupported' (no source found). It also warns against treating 'could_not_verify' as evidence.

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 trigger phrases and a clear use statement, then organizes routing, output, and error semantics in logical order. It is somewhat long, but every sentence carries substantive information, so it remains efficient relative to its 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 still explains the return structure (verdict values, actual value, citation, reasoning) and the meaning of error states. It covers the main usage scenarios and edge cases, making the tool self-contained 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 parameters are already well-documented. The description adds meaningful context about 'tolerance_pct' overriding the implied tolerance and the default cap, which helps callers calibrate behavior beyond basic 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 concrete trigger phrases and states 'natural-language claim verification against authoritative sources.' It clearly identifies the verb (verify) and resource (claims), and distinguishes itself from general query tools by focusing on fact-checking and evidence-based verdicts.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two execution paths and notes this tool replaces multiple sequential calls, but it does not name specific alternative tools, so it falls just short of a 5.

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

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

Annotations already mark the tool as read-only and idempotent, so no mutation danger is claimed. Beyond annotations, the description reveals a key behavioral constraint: a guessed or cross-package version 'will not resolve', which directly affects whether the agent can expect valid results and helps establish preconditions.

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, both purposeful: the first announces scope, the second gives the essential precondition and alternative. No filler, and the most important constraint is placed up front.

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 an output schema is present and all parameters are fully documented in the input schema, the description covers the key user-facing information: what is returned, the exact-version requirement, and the fallback sibling tool. Nothing critical is missing for an agent to invoke this 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%, and the input schema already thoroughly documents `name`, `system_`, and `version`. The description's version guidance largely mirrors the schema text ('call `package` first', 'version numbers are not transferable'), so it adds no meaningful parameter semantics beyond what is available.

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 states the tool provides 'Security advisories, license and dependency metadata' for 'ONE specific published release of a package', which is specific and distinguishes it from broader package-level tools. It emphasizes the exact-version scoping immediately, making it clear this is a version-scoped lookup rather than a general scan.

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?

Includes explicit guidance: 'Requires an exact version that this package actually shipped' and tells the agent to 'call `package` first to list them' if a version isn't known. It also warns against guessing or reusing versions from other packages, preventing an obvious misuse.

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