Samgov

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: default model (Workers AI Llama-3.3-70b, free), cost implications for Anthropic (BYO key, pay Anthropic directly), and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

The description is three sentences with no wasted words. It front-loads the core action and then adds details inline. Each sentence serves a distinct purpose: main action, key parameter nuances, and use cases.

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

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

Given the tool has 4 parameters, no output schema, and simple return objects, the description covers inputs, outputs, and use cases adequately. It could mention rate limits or pagination, but those are not implied. The description is complete for the complexity level.

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 description adds meaning beyond schema: explains default for 'models', reason for '_apiKey', and purpose of 'context'. This is above the baseline of 3 for full schema coverage.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the output ('score visibility 0-100 per model'). It distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among listed siblings.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to provide an API key for Anthropic. However, it does not mention when not to use this tool or compare it to similar siblings like 'scan_competitor_ai_presence'.

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, so the description does not need to re-cover safety. It adds useful behavioral context: the tool routes to one of many tools, fills arguments autonomously, and returns stable citation URIs. There is no contradiction, and the added routing/citation behavior is genuinely informative.

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 most important instruction (prefer over web search), then explains mechanics, usage cues, examples, and alternatives. It is longer than strictly necessary, and 'even if web search could also answer it' appears twice, but the length is largely justifiedgiven the tool's broad scope and many sibling alternatives.

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

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

Given the tool's complexity, open-ended scope, and absence of an output schema, the description is complete. It explains what the tool does, what it returns (structured answer with citation URIs), when to use it, when not to use it, and which sibling tools apply to which cases. No critical selection or invocation context is missing.

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

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

Schema coverage is 100%, with the question parameter fully described and aliases documented. The description reinforces natural-language usage and gives examples but does not add meaning beyond the schema. Per the rubric, a 3 baseline is appropriate when the schema carries the parameter documentation 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 what ask_pipeworx does: it routes a factual question to the right tool from thousands of verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It emphasizes being preferred over web search and gives concrete examples, making its purpose unambiguous and distinct from sibling tools.

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

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

The description explicitly says when to use the tool: whenever the user asks factual questions about real-world data, even if web search could answer it. It also names alternatives and exclusion conditions: use ask_pipeworx_grounded for a single clear target, use deep_research for broad multi-part questions, and use ask_pipeworx for breaking news. This is strong when/when-not 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/non-destructive, and the description adds the behavioral trait annotations cannot express: the router's behavior is volatile, with candidate improvements enabled live whenever one is under test. It discloses the current inactive state (last retired 2026-07-26) so the agent knows behavior now matches ask_pipeworx exactly, and clarifies this is a full working router, not a partial fallback.

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

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

Four dense sentences, each earning its place: identity, current state, usage condition, and guarantee. The core fact (beta of ask_pipeworx, identical router) is front-loaded. Slightly long, but the tool count (5,798) and the retirement date add concrete specificity rather than filler.

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

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

For a universal router exposing 5,798 tools, the description covers identity, current state, when to use, and the experimental comparison mechanism. It also discloses the return contract via 'same response shape' reference to ask_pipeworx. With annotations covering the safety profile and schema covering all parameters, the only minor gap is relying on the sibling for response-shape detail rather than stating it directly.

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

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

Schema coverage is 100% — all six parameters are documented as aliases for question — so the schema carries the parameter burden. The description only says 'same arguments' as ask_pipeworx, which adds no meaning beyond what the schema already provides. Baseline 3 is appropriate since the description neither needed nor provided extra parameter detail.

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?

States a precise identity: a beta version of the ask_pipeworx universal router with the same 5,798 tools, same arguments, and same response shape. It explicitly names the sibling it parallels (ask_pipeworx) and marks itself as the experimental edge, so an agent can differentiate it from ask_pipeworx and ask_pipeworx_grounded without inspecting schemas.

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

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

Gives an explicit use condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also frames the relationship to the stable router and explains the experimental purpose (results are compared to decide merges), which tells the agent when this variant is appropriate versus its stable sibling.

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

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

The description substantially exceeds the annotations by detailing the exact success return shape, the refusal contract with specific refusal_reason values, and the constraint that answers come only from tool results. It also conveys the extra LLM call cost, which is meaningful behavioral transparency beyond readOnlyHint/idempotentHint.

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 first, then behavior/return contract, then usage guidance and tradeoff. It is longer than some, but nearly every sentence conveys decision-relevant information; the tool/source counts are somewhat extraneous but minor.

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?

Without an output schema, the description fully compensates by specifying the success response fields and all refusal reason values. It also covers when to use, when not to use, the comparison to ask_pipeworx, and the extra cost — leaving no critical gap for correct invocation and expectation-setting.

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 the 'question' parameter and its aliases. The tool description does not add parameter-specific details, but it does not need to since the parameter is simple and fully documented. A baseline 3 is appropriate because the description adds no extra semantic value for parameters.

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

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

The description opens with a specific, distinctive purpose — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the mechanism: same routing as ask_pipeworx, then extraction only from the tool result. It clearly differentiates itself from the sibling ask_pipeworx by adding grounded/refusal behavior.

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

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

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on'), gives concrete examples of high-stakes domains, and names the alternative ('prefer ask_pipeworx for casual lookups') along with the tradeoff ('costs one extra LLM call'). This is ideal guidance for an agent deciding between siblings.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes far beyond, detailing fan-out logic, response shapes, resolver contracts, parent event extraction, news fallback mechanisms, and resolution-rule risk. No contradictions with annotations.

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

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

The description is lengthy but well-organized with clear sections (purpose, classifiers, fan-out examples, response shapes, resolver contract, etc.). Every sentence adds essential information for a complex tool, making it appropriate despite its size.

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

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

For a tool with 3 parameters, no output schema, and many behavioral nuances, the description is exhaustive. It covers all edge cases: low-confidence resolution, closed markets, wide spreads, resolution-rule risk, news fallback, and parent events. No critical information seems missing.

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

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

Schema coverage is 100%, so the description's role is supplementary. It adds valuable context: explains that 'market' accepts slug, URL, or question text; clarifies 'depth' levels (quick vs thorough) and 'include_raw's effect on response size. This enhances usability beyond the schema alone.

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

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

The description explicitly states the tool researches Polymarket bets by pulling Pipeworx data, with specific input formats (slug, URL, question text). It clearly distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on comprehensive evidence gathering for a single bet.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and covers important safety checks like low-confidence matches and closed markets. While it doesn't explicitly list when NOT to use it, the use cases are clear and the detailed guidance offsets this minor omission.

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

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

The description discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). This adds substantial context beyond the annotations which already indicate read-only, idempotent, and non-destructive 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 concise, using bullet-like phrases and front-loaded example triggers. Every sentence adds value, covering purpose, usage, data sources, and output format without redundancy.

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

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

Given the tool's moderate complexity (2 parameters, no nested objects, no output schema), the description fully covers inputs, data sources, output format, and sorting. It provides enough detail for an AI agent to understand 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?

Even with 100% schema coverage, the description adds significant meaning: for 'company' it specifies pulling latest 10-K metrics, for 'drug' it specifies FAERS counts. It also provides examples and constraints (tickers/CIKs, drug names, max/min items). The baseline is 3 due to high schema coverage, but the extra detail 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 the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes from sequential lookups by specifying it as a preferred alternative, and provides example trigger phrases.

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 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. It provides clear context for when to use, though it does not explicitly mention when not to use. The coverage is strong but lacks explicit exclusions.

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

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

The description goes far beyond the annotations: it explains the decomposition and parallel-routing mechanism, the findings packet shape (verbatim evidence + confidence + source + fetched_at + citation), the gaps[] array, contradiction detection, hop fields, semantic excerpting, and expected latency (15-60s, up to ~90s for thorough). It also explicitly states the tool never invents missing answers.

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

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

The description is information-dense and front-loaded with the critical account gate and top-level purpose. Its length is justified by the tool's behavioral complexity, but it is a long single block and could benefit from light sectioning. The content is rich without wordiness.

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 its complexity (decomposition, multiple depth tiers, latency variance, citation semantics, auth requirements), the description is exceptionally complete. There is no output schema, so the description carriers the full burden of explaining the return shape — and it does.

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

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

Schema coverage is 100% and the depth parameter is already well-documented in the schema. The description adds meaningful context about depth semantics: how 'standard' and 'thorough' add gap-recovery hops and contradictions, while 'quick' is a single hop. It also explains the account requirement for thorough, which is not in the schema.

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

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

The description opens with a clear statement that this is grounded multi-source research across 1517 structured data sources, and explicitly distinguishes itself from open-web search. It names the sibling ask_pipeworx as the alternative for open-web/news needs, making differentiation concrete without relying on sibling names alone.

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

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

It explicitly says when NOT to use it: if not signed in, use ask_pipeworx; for breaking news or live 'what the world is saying' queries, prefer ask_pipeworx because deep_research returns empty gaps for topics outside the structured catalog. It also gives example use cases ('compare X and Y's regulatory + financial exposure') and describes depth levels for when each 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context: it returns top-N most relevant tools with schemas and curated examples, and results are ready to call directly. No contradictions.

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

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

Description is well-structured: it starts with core purpose, lists example use cases, and ends with guidance. It is moderately long but each sentence adds value. A slight reduction in the list of domains could improve conciseness.

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

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

Given the high schema coverage (100%) and no output schema, the description provides sufficient context: it explains input (query), output (top-N tools with schemas), and usage hint. No gaps are evident.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining that 'query' accepts natural language descriptions and specifies aliases (task, q, description, search). This clarifies parameter usage 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?

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and notes that results include full schemas, making it easy to understand its function. This distinguishes it from sibling tools like deep_research or validate_claim which have different purposes.

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

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

Explicit guidance is provided: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use this tool and implies it is for discovery rather than direct answer retrieval.

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

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

The annotations already declare the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: patents soft-fail after API sunset, empty sections are real no-data conditions, private companies return resolved:false with a notes line, and sources_used/sources_failed report per-company outcomes. This goes well beyond the structured hints.

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

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

The description is long but well organized and front-loaded with usage triggers and the preference directive before the detailed return sections. Each clause carries a distinct fact about a source or behavior, though some parameter guidance is redundant with the schema, preventing a perfect score.

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

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

With no output schema, the description carries the full burden of documenting return values, and it does so thoroughly: it enumerates every returned section, the underlying data sources, fallback behavior, and failure semantics such as expected empty FDA sections and resolved:false for private companies. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, and the schema already documents the type enum and the accepted value forms (ticker, zero-padded CIK, company name). The description repeats these forms and adds the EDGAR name-resolution behavior, but it does not meaningfully add beyond what the schema already states.

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 defines the tool as a 'full cross-source profile of a US public company in ONE parallel call' and opens with concrete user-phrase triggers ('Tell me about X', 'research Acme', 'brief me on Tesla'). It explicitly differentiates the tool from chaining single-pack SEC/XBRL/news lookups, which makes the purpose and scope unambiguous.

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

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

The description gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clearly states acceptable inputs (ticker, CIK, or company name) and how the tool handles private companies, leaving no doubt about when to invoke it.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent but adds little beyond what annotations already 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?

Three concise sentences, front-loaded with purpose and usage. No superfluous 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?

Simple tool with 1 required parameter, no output schema. Description sufficiently covers purpose, usage, and effect for agent decision-making.

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

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

Schema coverage is 100% for the single parameter 'key'. Description repeats 'Memory key to delete' which matches schema; no additional semantics added.

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

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

The description clearly states specific action 'Delete a previously stored memory by key', distinguishing it from siblings like remember and recall.

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

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

Explicitly states when to use: stale context, task done, or clearing sensitive data. Mentions pairing with remember and recall, but no explicit when-not-to-use.

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

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

Discloses the process (fetch, extract, emit) and output format (single text blob). Annotations already indicate read-only, non-destructive, idempotent behavior, so description adds valuable process details without contradiction.

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

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

Three efficient sentences with front-loaded purpose. Every sentence adds value; 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?

No output schema, but description states output is a single text blob ready for site-root. For a simple generation tool with clear input and output, this is sufficient.

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

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

Schema coverage is 100%, and description provides additional context: example URL format for the 'url' parameter, and default/max values for 'max_links'. Adds meaning beyond schema.

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

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

The description clearly identifies the tool as generating an llms.txt file for any URL, with specific verb and resource. It distinguishes from sibling tools by focusing on a unique output format and use cases like AI indexing.

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

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

Explicitly lists when to use: getting client site indexed, drafting for own project, auditing competitor. Lacks explicit when not to use or alternatives, but context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by stating the default behavior (active only) and listing return fields, going beyond annotation info.

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

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

Two sentences, no wasted words. Front-loaded with purpose, then return fields, then usage guidance. Efficient 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?

For a simple one-parameter read-only tool, the description covers purpose, return fields, and usage scenarios. No output schema needed, but a note on pagination or limits would elevate it further. Still 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% (single boolean parameter with description). The description adds context by mentioning 'active' and tying it to the include_inactive parameter, providing meaning beyond the schema.

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

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

Clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). Distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reading existing 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?

Provides explicit usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel.' Does not mention alternatives or when not to use, but the context is sufficient for a simple 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?

Despite annotations being all false, the description richly discloses behavior: rate limit ('5 per identifier per day'), cost/free status ('Free; doesn't count against your tool-call quota'), the claim_token return mechanism, and the fact that the team reads digests daily. This goes far beyond the annotations and gives the agent accurate expectations for side effects and follow-up.

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

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

The description is long but every sentence earns its place: all major aspects (purpose, usage, scope, claim token behavior, rate limits) are necessary for correct use. It is front-loaded with the primary purpose and then logically organized, making it easy to parse despite the 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 no output schema, the description fully covers the return behavior (claim_token), the two-phase feedback follow-up workflow, constraints (daily limit, quota), and appropriate content guidelines. It gives the agent all necessary context to decide when and how to invoke the tool correctly.

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

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

The input schema already provides 100% parameter coverage, so the base baseline is 3. The description adds extra practical semantics, especially for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' It also instructs the agent to describe issues in terms of Pipeworx tools rather than pasting user prompts, adding value to the message and context parameters.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the resource (Pipeworx team) and the feedback categories (bug, feature, data_gap, praise), which clearly distinguishes it from sibling research and subscription tools.

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

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

Provides explicit when-to-use guidance with concrete examples ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog') and explicit exclusions, stating that feedback about tools from other MCP servers should be filed elsewhere. This fully clarifies when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: caching duration (5min-1h), data source (CF analytics-engine), no PII, and self-aggregating nature. This goes beyond annotations without contradiction.

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

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

The description is concise (~100 words), front-loaded with the main function, and uses bulleted use cases for clarity. Every sentence is purposeful 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?

Given the tool's simplicity (one param, no output schema, rich annotations), the description covers return values, parameter effect, caching, data source, and use cases completely. 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% with one parameter (window). The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the enum values.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It specifies the resource (trending data) and action (retrieve), and includes concrete use cases. This distinguishes it from siblings like 'discover_tools' by focusing on current call volume.

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 three explicit use scenarios: discovering hot data sources, confirming canonical tools, and checking use case alignment. While it does not mention when not to use or alternatives, the use cases serve as effective guidelines.

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

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

Annotations indicate readOnlyHint and idempotentHint, but the description adds extensive behavioral details: semantic anchor with Jaccard similarity ≥0.30, partition filter dropping placeholder slugs, fill check against live CLOB depth, and explanation of when not to trade. These details go well beyond annotations, enhancing transparency.

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

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

The description is fairly long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the basic usage and then details. Every sentence serves a purpose given the complexity, though it could be slightly more concise without losing clarity.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities array, partition_check results, fill check details). It covers edge cases like skipped_low_similarity, placeholders, and provides trade advice. The description is 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%, but the description adds significant meaning: for `event` it explains single-event mode, gives examples of slugs, and describes the partition check and monotonicity checks. For `topic`, it explains cross-event scanning and the union of markets. This adds substantial 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 clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and explains what each does, making the purpose specific and differentiating from sibling tools.

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

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

The description explicitly recommends when to use each mode: `event` for a specific market, `topic` for cross-event scanning. It also advises against trading when realizable edge is ≤0 and directs to `polymarket_fill_risk` for custom sizing, providing clear usage guidance and 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 details beyond annotations, including caching (KV level keyed on knobs), response structure (by_segment, diagnostics), and filter effects (tradeable-edge knobs drop opportunities). It aligns with readOnlyHint and idempotentHint, with no contradictions. The disclosure of why segments might be empty is particularly 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 comprehensive but verbose, spanning multiple paragraphs with detailed model explanations and response fields. While front-loaded with purpose, the density of information may overwhelm agents scanning briefly. It could be more concise by moving some model details to a separate reference.

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

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

Given the tool's complexity (9 parameters, nested response, three segments), the description is remarkably complete. It explains each segment's methodology, response fields (edge_pp_net, kelly_fraction, etc.), tradeable-edge knobs, diagnostics for empty segments, and even caching policy. No output schema exists, so the description fully bears the burden of explaining outputs.

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 descriptive parameter descriptions. The tool description adds context by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining their interplay (e.g., min_liquidity and max_spread_pp drop opportunities where edge isn't realizable). This provides meaningful semantic value beyond individual parameter descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly frames it for 'what should I bet on today' and distinguishes it from paging through hundreds of markets. The purpose is specific and distinct from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 strong usage guidance by stating the tool is built for discovering betting opportunities and mentions tradeable-edge knobs and caching behavior. It lacks explicit 'when not to use' guidance or differentiation from siblings, but the context is clear enough for an agent to understand appropriate use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: response structure (tracked, expired, snapshot_dates), meaning of fields (trend, decay_pp_per_day), signed values (negative = SELL YES), limitations (60-day TTL, snapshotting start date, daily closes not intraday). This goes well beyond the annotations.

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

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

The description is relatively lengthy but every sentence adds value. It is front-loaded with the core question. A slight restructuring could improve readability, but it remains efficient for the complexity.

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

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

Given the tool's complexity (multiple output arrays, computed fields, limitations) and no output schema, the description thoroughly covers the expected response structure, field meanings, and constraints. It is complete enough for an agent to understand what the tool returns and its limitations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new parameter semantics beyond the schema, only mentions defaults ('default 14, max 30' for days, 'default 1wk' for window) which are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from sibling tools like polymarket_edges by focusing on historical trends rather than current snapshots.

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

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

The description explains when to use the tool (to analyze edge persistence and decay), implicitly contrasting fresh vs aged edges. It does not explicitly state when not to use it or mention alternatives, but the context and sibling list provide differentiation. A clear usage context is 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?

The description adds significant behavioral context beyond the annotations: it explains that the tool checks live order-book depth, walks the ladder, and returns a verdict (clean|degraded|cannot_fill). It also discloses the risk of partial basket fills and names 'forced_directional_risk' legs. No contradiction with annotations (readOnlyHint=true, destructiveHint=false).

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 fairly long but well-structured, with single-market and basket modes clearly separated. It front-loads the essential purpose and then details returned fields. Every sentence earns its place, though some redundancy could be trimmed; however, the complexity justifies the length.

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

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

Given no output schema, the description comprehensively lists all return fields for both modes, including edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk. It covers the risk of partial fills and provides a thorough understanding of what the tool returns, ensuring the agent can correctly interpret results.

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

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

Schema description coverage is 100%. The description enriches each parameter: it explains how size_usd is interpreted differently for buys vs sells and basket mode, clarifies the default behavior for side in basket mode ('sell if partition sum > 1, buy if < 1'), and specifies the clamp range for size_usd. This adds substantial meaning beyond the schema.

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

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

The description clearly identifies the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying both single-market and basket modes with concrete examples. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by stating its use case: checking fill risk before executing trades.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against using it for small trades and explains the risk of partial basket fills converting an arb into an unhedged directional position, providing clear context for 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?

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing matching limitations, fee assumptions, gross-vs-net spreads, compatibility codes that can be non-empty even with matched pairs, the meaning of null temporal alignment, and why unclassified legs are never paired. This is rich, honest behavioral disclosure that meaningfully shapes invocation 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 long, but it is well-organized with capitalized sections for modes, response fields, safety fields, and codes, and the core purpose is front-loaded. A few points are repeated across the compatibility-code explanations and the closing warning, so it is slightly less tight than a perfect 5.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, per-entry flags, skipped classifications, temporal_alignment semantics, and the fees caveat, leaving the agent with enough context to rely on the 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% and each parameter already has a description, so the baseline is 3. The description adds value by explaining that both modes run the same token-overlap matcher, that explicit parameters override the topic-mapped side, and that the same disclosures apply in both modes, which is not stated in the schema alone.

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

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

The opening sentence states a clear, specific purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly names the resource and output concept, but does not explicitly contrast itself with sibling tools like polymarket_arbitrage or polymarket_edges, so it stops short of full sibling differentiation.

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

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

The description gives strong guidance for the tool's two operating modes: pre-mapped topics vs. explicit event tickers/slugs, and it explains when custom pairing is appropriate. However, it never tells the agent when to choose this tool over related siblings such as polymarket_arbitrage or polymarket_edges, so alternative selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds behavioral context: scoping to identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. 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 concise: three sentences that front-load the core purpose, then add context and scope. Every sentence earns its place—no fluff, no repetition.

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

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

Given the single optional parameter, no output schema, and comprehensive annotations, the description is complete. It explains scoping, key behavior, and relationships to sibling tools. No gaps.

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

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

Schema coverage is 100% with a clear parameter description. The description adds meaning by stating 'omit to list all keys,' clarifying behavior beyond the schema. This helps the agent understand the optional parameter's effect.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list), the resource (saved values/keys), and gives concrete use cases (ticker, address, notes). It effectively distinguishes itself from siblings remember and forget.

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

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

The description advises when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It implies not to use when fresh information is available and mentions pairing with remember/forget. Though it doesn't explicitly state 'when not to use,' the guidance 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?

Annotations already indicate a safe, idempotent read operation. The description adds transparency by detailing the return fields (source, citation_uri, payload), the effect of mark_read, and even mentions an alternative endpoint, fully aligning with and extending the annotation hints.

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

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

Concise and well-structured: the first sentence immediately states the purpose, and subsequent sentences add essential details about filtering, mark_read, polling, and an alternative access method. Every sentence adds value without unnecessary fluff.

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

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

Given the tool's moderate complexity (5 optional params, no output schema), the description fully covers what the tool does, what it returns, how to filter, the side effect of mark_read, and even alternative access. No significant gaps remain.

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

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

Schema coverage is 100%, but the description adds meaningful context: provides a concrete example for 'type' (e.g., 'sec_8k'), explains that 'since' uses ISO timestamps, and clarifies that mark_read flags events as read so subsequent calls return only newer ones—value beyond the schema descriptions.

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

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

The description clearly states the verb 'pull' and resource 'fired events from your subscription feed,' distinguishing it from sibling tools like 'list_subscriptions' or 'subscribe' by focusing on consuming fired events rather than managing 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?

Provides clear usage context: filtering by type and ISO timestamp, the mark_read parameter for controlling read state, and note that polling works. However, it lacks explicit guidance on when to use this tool vs. alternatives (e.g., when to use 'search_within' or 'list_subscriptions' instead).

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

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

The description adds significant context beyond annotations: explains fallback logic (GDELT preferred, GNews when rate-limited/5xx), USPTO API sunset soft-failure, accepted date formats and recommendations, and return structure with grouped changes, total count, and 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?

The description is comprehensive but slightly lengthy. It front-loads the core purpose and examples efficiently, but every sentence earns its place. A minor reduction for verbosity; still very 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?

Given the tool has 3 parameters, no output schema, and no nested objects, the description is thorough. It covers data sources, error handling, return format, and sibling differentiation, ensuring an agent can use it correctly.

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

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

All three parameters have schema descriptions (100% coverage). The description adds further value: for 'since' it gives examples and recommends '30d' or '1m', for 'value' it clarifies ticker or CIK format, and for 'type' it confirms only 'company' supported.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and gives specific examples like 'What's new with X' and 'latest on Y'. It lists data sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling tool 'entity_profile'.

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

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

The description provides explicit usage examples and a clear 'when not to use' directive: 'Use entity_profile instead when you want the static profile... regardless of window'. It also explains fallback behavior between GDELT and GNews, and notes soft-failure for USPTO.

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 (idempotentHint=true, non-destructive), the description adds valuable context: memory is scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. 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 concise (3 sentences), front-loaded with the core purpose, and every sentence adds unique value. No redundancy.

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

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

Given the low complexity (2 parameters, no nested objects, no output schema), the description is complete: it explains purpose, usage, pairing, and retention behavior. No gaps.

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

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

Input schema has 100% coverage with descriptions for both parameters (key and value). The description adds examples of keys and values but does not significantly enhance schema meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations, with specific examples like 'resolved ticker', 'target address'. It distinguishes itself from sibling tools recall and forget by explicitly pairing with them.

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

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

The description explains when to use the tool ('discover something worth carrying forward') and explicitly pairs with recall and forget. However, it does not state when not to use it or provide explicit alternatives, though the guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive intent; the description adds substantial behavioral context beyond that: unresolved identifiers are 'stated explicitly under `unresolved` rather than omitted', enrichment 'degrades gracefully' if GLEIF/OpenFIGI are unavailable, internal calls cascade through multiple endpoints, and ambiguous matches return `figi_candidates`. This is exactly the kind of runtime nuance an agent needs.

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 long, but nearly every clause carries essential information: supported types, ambiguous-match behavior, unresolved handling, and graceful degradation. The opening user-phrase examples are excellent front-loading. The main weakness is the run-on parenthetical structure, which could be broken into clearer bullets or sentences without losing fidelity.

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

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

For a tool with no output schema, the description thoroughly covers what the agent will receive: sourced identifiers, `unresolved` field, `figi_candidates` for ambiguity, drug result shape including RxCUI and citation, and failure-mode behavior when upstream services are down. Combined with full schema coverage and safety annotations, nothing critical is missing for correct invocation.

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

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

Even though schema description coverage is 100%, the description adds critical parameter semantics not present in the schema: the `value` parameter's warning to 'Pass the ENTITY NAME ONLY' and to avoid 'the question's full noun phrase', with bond-issuer examples. It also explains what each `type` accepts and how ISIN input behaves, materially improving the agent's ability to input correct values.

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

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

The description opens with concrete user phrasings ('What's the ticker for…' / 'find the CIK for…') and immediately states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly enumerates supported entity types and the identifiers returned per type, which clearly distinguishes this resolver from sibling tools like entity_profile or sam_entity_search.

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

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

The description gives a strong trigger directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies when ambiguity arises ('when a name matches more than one instrument it asserts nothing and returns figi_candidates'). However, it does not name specific sibling alternatives or state when NOT to use this tool, so the guidance stops short of explicit exclusion.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds highly valuable behavioral context: exact UEI/CAGE/legal-name matches rank above fuzzy hits, active registrations sort above expired ones, and the mirror field discloses snapshot date/age with a clear caveat that the data may legitimately be weeks old. 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?

Four dense sentences with the core purpose front-loaded. Every clause adds information — search types, returned fields, ranking behavior, and freshness caveat. The description is longer than average but earns its length for a tool with this complexity; only minor trimming of the returned-fields list would tighten it.

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?

Output schema exists and annotations cover the safety profile, so the description only needs to explain behavior, ranking, freshness, and live-mode conditions — all of which are present. An agent has enough context to decide when to use the tool, what results to expect, and how to interpret stale mirror data.

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

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

Schema description coverage is 100% with detailed per-parameter descriptions. The main description echoes the business_name acceptance of legal/DBA names or exact UEI/CAGE codes and the live:true API-key caveat already in the schema, but does not add substantially new parameter-level meaning beyond the structured definitions.

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

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

States a specific verb and resource: 'Look up federal contractors registered in SAM.gov by business name, UEI, or CAGE code.' It clearly distinguishes SAM entity search from sibling tools like sam_search_opportunities and sam_search_exclusions by focusing on entity registrations and their attributes.

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: keyless mirror use, monthly snapshot staleness, live:true for current data, and 10-request/day cap. However, it does not explicitly name alternative tools or give when-not-to-use guidance versus closely related siblings like entity_profile or resolve_entity, so it stops 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 the operation read-only, idempotent, non-destructive, and open-world. The description adds meaningful behavior beyond those flags: it reveals the automatic posting-date resolution, the fallback to a one-year search window, and the full set of returned fields. This is more than a bare restatement, though the safety profile remains mostly annotation-driven.

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 focused sentences: the first states what the tool does and returns, and the second explains the date-range caveat and parameter usage. Every sentence carries operational value, the critical differentiating details are front-loaded, and there is no redundant restatement of the name or 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 a full output schema, complete parameter documentation, and annotations covering safety, the description provides the missing contextual pieces: sibling differentiation, return-field expectations, and the SAM.gov date-window workaround. Nothing an agent needs to invoke the tool correctly is left unexplained.

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

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

The input schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds value by explaining the functional relationship between posted_from/posted_to and the automatic date resolution, noting they are only needed for solicitations older than a year. That goes beyond the schema's MM/DD/YYYY placeholder and justifies slightly above 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 and resource: 'Get full details for a federal contract opportunity by solicitation number.' It enumerates the returned fields and explicitly contrasts them with 'the fields sam_search_opportunities does not carry,' which distinguishes it from its closest sibling without needing to inspect schemas.

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

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

It names sam_search_opportunities as the alternative that lacks the detailed fields, so an agent can choose between lookup-by-number and search. It also gives explicit date-parameter guidance: SAM.gov's one-year cap, automatic posting-date resolution, and the instruction to pass posted_from/posted_to 'only for an older solicitation,' which is a clear when-not-to-use constraint.

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 it readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavior beyond that: it searches a keyless local snapshot refreshed daily, defaults to excluding terminated exclusions unless include_terminated is set, and describes the returned fields (exclusion type, program, agency, dates). This fully sets expectations for a read-only lookup 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 compact and front-loaded: the first sentence states the core purpose and audience, the second summarizes filters and results, and the final sentence handles sibling differentiation. Every sentence earns its place, and there is no redundant material.

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 search tool with no output schema, the description is complete: it covers what the tool searches, why it is used, what filters exist, what fields come back, how data freshness works, and how it differs from the adjacent sanctions tool. The required parameter is obvious from the schema and examples, and pagination defaults are covered in the schema.

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

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

Schema description coverage is 100%, and the schema's parameter descriptions are already detailed, including the meaning of name, UEI, include_terminated, classification, and offset. The main description lists some filters (name, state, classification) but does not add meaningful parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Search the SAM.gov Exclusions list — parties DEBARRED, suspended, or otherwise excluded.' It clearly states the question this tool answers ('is this company/person barred from federal contracting') and distinguishes it from OFAC sanctions, making the purpose unmistakable even among SAM and sanctions-related siblings.

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

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

The description explicitly names the use cases: KYB, vendor-vetting, and procurement due diligence. It also gives a direct exclusion rule by stating this is distinct from OFAC sanctions and is 'the federal procurement debarment list,' referring to the alternative sanctions_screen. This gives an agent 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 adds significant behavioral context beyond the readOnly/idempotent/openWorld annotations: it discloses the title-weighted relevance ranking, the mirror freshness field, the 30-day default date range, and the snapshot-versus-API-key behavior. No contradiction with annotations.

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

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

The description is dense but purposeful: it front-loads the core search function, then explains ranking behavior, return fields, defaults, and aliases in a compact paragraph. Every sentence contributes useful information, though the single long paragraph could be slightly more scannable.

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

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

For a 12-parameter tool with a required keyword, the description covers return values, defaults, aliases, freshness, ranking, and the keyless workflow. The output schema exists, so return-value details are already structured. Nothing critical is missing for an agent to call 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 coverage is 100%, so the baseline is 3, but the description adds value by explaining aliases (q/query/keywords), the 30-day default when posted_from/posted_to are omitted, and the meaning of the _apiKey parameter in relation to snapshot freshness. This goes beyond the 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 and resource: 'Search active federal contract opportunities by keyword, NAICS code, set-aside type, posting date range, and procurement type.' It clearly distinguishes this from sibling SAM tools like entity search, exclusions, and opportunity retrieval by emphasizing active contract opportunities searched without an API key.

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

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

The description explains when to use this keyless snapshot search of SAM.gov and notes that an API key is only needed for postings newer than the snapshot (via the _apiKey parameter). It doesn't explicitly name alternative tools or state 'use X instead' for specific cases, but the context around the keyless snapshot and daily refresh provides practical 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/non-destructive, so the bar is to add context beyond that. The description adds the data source (public daily SAM.gov Contract Opportunities extract), no-API-key behavior, the ability to interpret plain phrasing or codes, and the `mirror` freshness field — all genuinely useful behavioral disclosures not captured by annotations.

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

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

The description is dense but not bloated: it front-loads the core function, then gives query examples, data-source rationale, accepted input forms, and return fields. Minor redundancy with the schema's parameter descriptions prevents a 5.

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

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

Given the rich output schema, annotations, and complete parameter descriptions, the prose covers everything an agent needs to invoke correctly: required set_aside, optional filters, keyless operation, snapshot freshness, and return contents. Nothing structurally important is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description reinforces the set_aside flexibility (codes vs. ordinary phrasing) but adds little beyond what the schema's set_aside property already states. 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 a specific verb ('Find'), a precise resource ('federal contract opportunities reserved for a specific class of small business'), and enumerates the set-aside categories. It also names example questions it answers, which disambiguates it from broader sibling tools like sam_search_opportunities and sam_get_opportunity.

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 makes clear it is the right tool for set-aside-specific queries and emphasizes it works keylessly from a local SAM.gov snapshot, which differentiates it from live/API-backed siblings. It does not explicitly say 'when not to use' or name alternatives, but the context is strong enough for an agent to route correctly.

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

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

Description adds behavioral details not in annotations: it probes each entity with ai_visibility_check, ranks by score, treats first entity as 'subject', and returns a ranked list with score, confidence, signal density per entity. Annotations already indicate read-only, idempotent, non-destructive, and open-world. 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?

Three sentences, each meaningful. First sentence states core action, second explains process, third provides use case. No redundant or filler content. Essential information is front-loaded.

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

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

Given no output schema, the description adequately describes return values (ranked list with score, confidence, signal density). Parameter semantics are handled by schema and description addition. The tool's purpose, input, and output are fully explained for an AI agent to select and invoke correctly.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). Description adds value by clarifying that the first entity in the array is treated as 'subject' for narrative, and implicitly notes that models default to workers-ai (as supported models listed in schema). This extends beyond the schema's 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?

Description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check to probe, rank, and surface differences. It explicitly targets competitive AI-marketing audits, distinguishing it from similar tools like compare_entities or single-entity ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question ('does Claude know about us as well as our competitors?'). It implies that for a single entity, ai_visibility_check is more appropriate, but does not explicitly list when not to use this tool or name alternatives beyond the underlying probe.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds detailed behavior: partial failure degradation (sources_failed), retry semantics (first measurement timeout), and exact return structure (summary block with fields, advisories, links, alternatives). No contradictions with annotations.

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

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

Description is long but front-loaded with the core purpose, then branching into detail. Every sentence provides essential context (ecosystem, failures, output structure). Minor redundancy ('NPM ecosystem only in v1' appears twice), but overall well-organized and 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?

Despite no output schema, description enumerates 8 summary fields, per-advisory details, links, and alternative versions. Covers failure modes, timeout behavior, and ecosystem scope. Comprehensively explains the tool's return value for agents to interpret results.

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

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

Schema coverage is 100% with clear field descriptions. Description adds value by noting scoped packages (@types/node) accepted and that version defaults to latest. Also explains that the tool aggregates data from multiple sources, helping understand the parameter roles in a composite context.

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

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

Description uses specific verbs ('scan', 'composite check') and clearly identifies the resource (npm package) and the multi-source fan-out (deps.dev, bundlephobia). Distinguishes from sibling tools by explicitly stating the ecosystem scope (NPM only) and the single-call nature.

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

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

Explicitly states when to use ('is X safe / popular / small', 'what does adding lodash cost me'), ecosystem limitations (NPM v1; other ecosystems via deps.dev:version directly), and timeout behavior (bundlephobia first measurement 5-30s). Provides clear alternatives for non-NPM packages.

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. The description adds significant behavioral context: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char limit with truncation and flagging, and that each passage includes character offsets for verification.

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 paragraph of 5 sentences, front-loaded with the core purpose. Every sentence adds value: usage context, pairing suggestion, technical details, and limits. No redundant or vague information.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is complete. It explains input semantics, output format (top-N passages with offsets and scores), limits, and technical details. The pairing suggestion also provides broader 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 some context, like examples for the query parameter and the character limit on text, but it largely repeats schema descriptions. Since schema already provides adequate descriptions, no extra credit is needed.

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: 'Semantic search INSIDE a fetched record.' It specifies the action (search), the resource (a record), and the output (top-N passages with offsets and scores). It also distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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 advises when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow involving ask_pipeworx_grounded, helping agents decide between tools.

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

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

The description adds valuable behavioral context beyond annotations (e.g., OAuth requirement, phone verification, webhook signing, auto-disable on failures). However, it contradicts the idempotentHint=true annotation because each call creates a new subscription (non-idempotent). This contradiction lowers the score.

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 purpose and prerequisites, followed by detailed type and delivery information. It is dense but well-organized. However, it is somewhat lengthy; separating type details into a structured format could improve conciseness.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers all essential aspects: prerequisites, supported types with examples, delivery options with limitations, and critical details (webhook signing, auto-disable). It leaves no major gaps for an agent to invoke the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description significantly enriches schema by providing concrete examples for each type and delivery channel, explaining constraints (e.g., phone verification, daily SMS cap, webhook HMAC details), and clarifying required vs optional fields. This is far beyond the schema's minimal descriptions.

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

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

The description clearly states the tool 'Create a proactive monitoring subscription to a live-data event stream' and explicitly distinguishes from siblings like 'list_subscriptions' and 'unsubscribe'. It specifies supported types and delivery channels, 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 provides explicit context: requires a Pipeworx OAuth account, lists supported types with examples, and details delivery options. It implicitly distinguishes from other tools by focusing on subscription creation. However, it does not explicitly state when not to use this tool (e.g., for one-off queries).

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds value by detailing the output structure (category-bucketed example questions with tool+argument shapes) and the live catalog source. This context is 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 front-loaded with example queries but is somewhat verbose. It could be more concise by removing redundant phrasing like 'give me ideas / show me examples' since it's covered by 'what can I ask?'. However, each sentence adds some value.

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

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

For a tool with no output schema, the description provides a good understanding of what is returned (category-bucketed examples with tool shapes). It also explains the optional parameter and when to use it. Slightly lacking on potential limits or cross-category behavior details, but sufficient for a discovery 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% with description for 'topic' parameter. The description repeats the valid values but does not add new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point, using verbs like 'returns' and 'use this FIRST'. It specifies the resource (category-bucketed example questions with tool+argument shapes) and distinguishes from siblings by positioning as the introductory 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?

Explicitly states when to use ('when you do not yet know what Pipeworx can do') and how to call (no arguments for full spread, topic to focus). Mentions meta-tools (ask_pipeworx, entity_profile, etc.) as things to learn about, providing implicit alternatives.

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

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

The description adds significant behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted) and that historical events remain accessible via 'recent_alerts'. This aligns with annotations (non-destructive, idempotent) and provides extra detail.

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

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

Two concise sentences with front-loaded purpose. Every sentence adds value—no redundancy.

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

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

With only one parameter and no output schema, the description fully covers purpose, behavior, ownership constraint, and relation to sibling tools (recent_alerts). No gaps.

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

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

Schema coverage is 100% and the parameter description already notes it is returned by 'subscribe'. The description adds ownership context linking the id to the user, which enhances understanding beyond the schema.

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

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

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

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 ownership enforcement, guiding the agent on when this tool is applicable (only for own subscriptions). It does not mention alternatives or when not to use, but the constraint is clear and useful.

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, but the description adds substantial behavioral context: it explains the could_not_verify vs unsupported distinction, warns that could_not_verify is not evidence, and discloses the fall-through pipeline and return format with citations and reasoning. This goes well beyond the annotations.

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

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

The description is dense but well-organized: trigger phrases, usage context, two processing paths, return values, and a critical caller warning. Every sentence contributes essential information, and the structure (with bullet-like breaks) improves scannability.

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

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

Given the tool's complexity (two pipelines, six verdicts, error objects) and no output schema, the description covers all necessary semantics: verdict meanings, error handling, citation behavior, and the fact that it replaces multiple sequential calls. It is fully self-contained for correct invocation and 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?

The schema already describes both parameters well (100% coverage), and the description augments this with practical guidance: tolerance_pct overrides implied tolerance, suggests 1–2 for hallucination detection, and notes the 5% cap. Claim examples reinforce usage. This adds meaning beyond the schema without fully duplicating 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 identifies the tool as natural-language claim verification with an explicit verb ('validate') and resource ('claims'). It enumerates natural-language trigger phrases and describes two processing paths (structured vs grounded), distinguishing it from sibling research/analysis tools.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and gives clear context for when to use the structured vs grounded pipeline. However, it does not explicitly name alternatives or list when-not-to-use scenarios, stopping 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.