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 read-only/idempotent safety, so the description focuses on added value: routing to 5,462 tools, returning stable citation URIs, and being a fast single call. It doesn't mention potential latency or non-determinism, but given annotation coverage, this is acceptable. No contradiction.

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

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

The description is long but front-loaded and every sentence serves a purpose: preference guidance, mechanism, examples, escalation paths, and special-case note. It is well-structured and avoids fluff, justifying its length for a central default tool.

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

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

Given its position as the default entry point, the description covers what it does, when to use it, when to use alternatives, and what kind of output to expect (structured with citation URIs). No output schema exists, so the description adequately fills the gap.

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

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

The schema has 100% coverage; the main 'question' parameter is well-described and aliases are documented. The tool description adds no further parameter details beyond the schema, but the schema itself is sufficient for invoking correctly.

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 ('routes', 'returns') and resource (questions about real-world data with citations). It clearly distinguishes itself from siblings by name-checking ask_pipeworx_grounded and deep_research as alternatives, making its unique role explicit.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives and their use cases (hallucination-resistant single answer vs multi-part fan-out). Also gives examples of queries that fit.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds meaningful behavioral context: it is a live experimental edge, currently with no active candidate and matching ask_pipeworx exactly. It also discloses that results are compared against the stable router, which is valuable transparency about its evaluation 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 at three sentences, front-loaded with the key 'Beta version of ask_pipeworx' identity. Each sentence adds distinct value: identity, current state, and usage guidance, with no wasted words.

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

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

For a variant tool, the description fully covers its role, relationship to the stable router, current status, and usage. It notes 'same response shape' as ask_pipeworx, which addresses return value expectations without needing an output schema. It is complete for the decision-making and invocation needs.

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

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

The schema already covers all 6 parameters with descriptions, including aliases, so the baseline is 3. The description does not add parameter-specific details, but implies the same argument structure as ask_pipeworx, which is consistent with 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 it as a beta universal router identical to ask_pipeworx but with candidate routing improvements. It explicitly distinguishes from the sibling ask_pipeworx by naming it and describing the experimental edge, making the tool's purpose unmistakable.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing clear when-to-use guidance. It names the alternative (ask_pipeworx) and explains the comparison framework, giving sufficient context for choosing between them.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: the refusal mechanism, refusal_reason enum, evidence/verbatim quote, and the constraint that the answer must be extracted only from tool results. It also explains the extra LLM call cost. This goes well beyond what annotations provide.

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

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

The description is dense but well-structured: front-loaded with the core behavior, then return format, refusal cases, usage guidance, and cost trade-off. Every sentence carries unique information, with no filler or repetition of schema/annotations. It earns its length for a complex tool.

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

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

Despite having no output schema, the description thoroughly documents the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and failure shapes (refusal_reason enum with 5 values). The tool has 6 params but 5 are aliases, so the description covers the natural-language question context and the grounded extraction guarantee. Given the complexity and zero output schema, this is as complete as one could expect.

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

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

Schema coverage is 100%, so the schema fully documents the 6 parameters (question + 5 aliases). The description adds context that the question is in natural language and the tool will route/fill arguments, but it doesn't list specific parameter syntax. Baseline 3 is appropriate for 100% coverage; the description adds marginal value by explaining how the question is used ('fills arguments, fetches the data'), so 4 is justified.

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 ('EXTRACTS the answer using ONLY what the tool result contains') and resource ('hallucination-resistant answer mode'), clearly distinguishing it from its sibling ask_pipeworx. It identifies the tool as grounded/anti-hallucination for high-stakes reads, which differentiates it from the general ask_pipeworx tool.

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

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

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also names the sibling ask_pipeworx and provides a cost trade-off ('Costs one extra LLM call vs ask_pipeworx'), giving clear decision criteria.

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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses account requirements, paid depth level, latency ranges (15-90s), explicit gaps[] behavior with no invention, resolvable citation_uri guarantee, semantic excerpting, and contradictions[] for deeper depths. 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 lengthy but front-loaded with the most critical account requirement and packed with valuable details. There is minor redundancy (e.g., 'NOT open-web search' is repeated conceptually later), and it could be slightly tightened, but each sentence contributes meaning for a complex research tool.

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

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

For a tool with no output schema, the description thoroughly covers input expectations, behavioral nuances, return packet contents, failure modes (gaps[]), citations, latency, and account prerequisites. It is complete enough for an agent to select and invoke the tool correctly in almost any scenario.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains depth levels in concrete terms (quick=3 facets, standard=5 with gap recovery + contradictions, thorough=8 paid with iterative hop), and clarifies that the question parameter can be broad/multi-part. This goes well 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 tool performs multi-source structured research, decomposing questions into facets and routing them in parallel across 5,462 tools. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, making the purpose and differentiation unambiguous.

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

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

The description explicitly states when to use this tool (broad/multi-part questions over structured data), when to use alternatives (single lookup → ask_pipeworx; breaking/current-news topics → ask_pipeworx), and even notes account-tier prerequisites with a fallback if not signed in. This is model-excellent usage guidance.

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

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

Annotations already 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?

Beyond annotations (readOnly, idempotent, openWorld, non-destructive), the description reveals that patents may soft-fail due to API sunset, and that the call fans out across multiple sources in parallel. These are useful behavioral details not conveyed by annotations alone.

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

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

The description is front-loaded with examples and purpose, then lists outputs and limitations. It is somewhat long but every sentence adds value. Slight redundancy (e.g., repeating 'not supported') but overall 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?

With no output schema, the description fully explains return fields (CIK, filings with URIs, fundamentals sorted, patents, news, LEI) and limitations (patents soft-fail). It covers what the tool does and what to expect, making it complete for agent use.

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

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

Schema coverage is 100%, so schema already describes both parameters. The description adds example values and context (zero-padded CIK, that type is only 'company'), but this is marginal 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's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides diverse example queries and lists specific outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from siblings like resolve_entity, which handles name resolution.

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 prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use: 'Names not supported — use resolve_entity first if you only have a name.' Provides clear alternative.

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

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

Annotations 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?

Annotations are all false, so the description carries the burden. It adds concrete behavioral details: rate-limited to 5 per identifier per day, free (doesn't count against quota), and that the team reads digests daily. It doesn't mention any other side effects, but for a feedback submission tool this is sufficient and consistent with annotations.

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

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

The description is a single dense paragraph, but every sentence adds value: usage rules, exclusions, formatting guidance, rate limits, and impact. It could be slightly tightened (e.g., splitting into bullet points), but it remains focused and front-loaded with the core purpose.

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

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

For a feedback tool with no output schema, the description covers all necessary context: what qualifies as feedback, what to avoid, how to structure the content, rate limiting, and impact. It fully equips an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the meaning of feedback types (bug, feature/data_gap, praise) and instructing users to describe issues in terms of Pipeworx tools/packs, reinforcing the 'context' and 'message' fields. It also emphasizes not pasting end-user prompts, adding practical semantic guidance.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by focusing exclusively on feedback about Pipeworx tools, not data queries or research actions.

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 enumerates when to use (bug, feature/data_gap, praise) and provides a strong exclusion: tools from other MCP servers are not eligible. It also clarifies how to frame feedback (in terms of Pipeworx tools/packs, not end-user prompts) and notes rate limits, leaving no ambiguity about appropriate 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?

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond by detailing compatibility_warning conditions (non-equivalent bet shapes, semantic mismatch), temporal_alignment, and skipped_cross counters. It thoroughly discloses limitations (e.g., spreads meaningless when aligned:false). No contradiction with annotations.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses front-loaded key information. While longer than necessary, every sentence adds unique value. Minor verbosity in the safety fields section is acceptable given 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?

Despite no output schema, the description fully explains the response structure: leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and counters. It covers all necessary context for an agent to interpret results correctly. 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 covers 100% parameters with descriptions. The description adds value by explaining the two modes (topic vs explicit), listing valid topic values, and clarifying that kalshi_event_ticker and polymarket_event_slug override the topic mapping. This enriches the schema without redundancy.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It differentiates from siblings by focusing on cross-venue comparison rather than single-venue arbitrage (e.g., polymarket_arbitrage). The verb 'spread' combined with venue names makes purpose unambiguous.

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

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

The description explicitly explains two modes (topic shortcuts vs explicit tickers) and provides context for when each is appropriate. It warns that most pre-mapped topics currently return compatibility_warnings, guiding users to check before trading. However, it does not explicitly state when to choose alternatives like polymarket_arbitrage.

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?

Even though annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds significant behavioral context: the call cascades through multiple internal endpoints, replaces 2-3 manual lookups, auto-disambiguates input, and returns specific citation URIs. This goes well beyond structured annotations.

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

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

The description is reasonably concise and front-loaded with the purpose and example queries. It uses structured sections (SUPPORTED TYPES) to organize details. It is a bit long but each sentence contributes useful context, so it earns a 4 rather than 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?

Without an output schema, the description carries the burden of explaining return values, and it does so thoroughly for both entity types: company (ticker, CIK, company_name, citation URI) and drug (RxCUI, ingredient, brand, citation). It also covers input formats, disambiguation, and internal cascading, making it highly complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for 'value' per entity type (e.g., ticker 'AAPL', CIK '0000320193', drug names 'ozempic') and clarifies that input is auto-disambiguated. It also explains what each type returns, enriching parameter understanding beyond the schema.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier required by other tools. The verb 'resolve' is specific, and the resource is well-defined (entity names to IDs). It also distinguishes itself from siblings by noting it should be used 'FIRST whenever you have a name but need an ID' and by listing supported entity types.

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

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

The description provides explicit usage context: 'Use FIRST whenever you have a name but need an ID' and gives example user queries that trigger this tool. It does not explicitly mention when not to use it or name alternative tools, so it misses the 'when-not' and 'alternatives' aspect, which would elevate to a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description is consistent but adds no extra behavioral context (e.g., rate limits, authentication details).

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?

Single, front-loaded sentence. No wasted words.

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

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

Output schema exists and description lists return fields. Missing details on pagination or error handling, but overall adequate for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. However, description mentions searching by 'UEI' but no UEI parameter exists in schema, misleading the agent. This reduces score.

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 verb 'Search', resource 'registered federal contractors', and search criteria ('business name or UEI'), and lists return fields. Distinguishes from sibling tools like sam_search_exclusions.

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

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

No guidance on when to use this tool vs. alternatives like sam_search_exclusions or sam_search_opportunities. The sibling list is extensive but no differentiation cues.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by listing the specific data fields returned, which is useful behavioral context beyond the annotations.

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

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

Single sentence (15 words) that is front-loaded with purpose and free of filler. Every word earns its place.

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

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

The description lists return fields, and the output schema exists. It could mention error handling or prerequisites, but for a simple lookup tool, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description does not add additional meaning beyond what the schema provides.

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 gets full details for a federal contract opportunity by solicitation number, listing specific return fields. It distinguishes from sibling search tools like sam_search_opportunities and 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?

No explicit when-to-use or when-not-to-use guidance. The description implies use when you have a solicitation number, but does not clarify when to prefer this over search tools.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, indicating a safe, read-only, idempotent search. The description adds value by stating that the tool returns exclusion type, program, agency, and active/termination dates, which is useful behavioral context beyond the annotations.

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

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

The description is concise at 4 sentences, front-loaded with purpose, then use case, filter details, return info, and distinction. Every sentence adds value 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 5 parameters with 100% schema coverage, no output schema, and comprehensive annotations, the description covers behavioral details (return fields, distinction from OFAC) adequately. The tool is fully described for an 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 coverage is 100%, so the description's parameter information is supplementary. It adds context like 'matched against the exclusion name' for the 'name' parameter, but does not significantly enhance understanding 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 searches SAM.gov Exclusions for debarred parties, specifies the exact use case (KYB/vendor vetting/procurement due diligence), and distinguishes it from OFAC sanctions. The verb 'Search' combined with the resource 'SAM.gov Exclusions list' and the specific question it answers makes the purpose unambiguous.

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

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

The description provides explicit context for when to use the tool (KYB/vendor vetting/procurement due diligence) and explicitly distinguishes it from OFAC sanctions via 'see sanctions_screen'. However, it does not state when not to use it or provide alternatives beyond the one sibling mentioned.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context: default date range behavior, alias handling, and the set of returned fields (titles, solicitation numbers, deadlines, agencies). 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?

Four sentences with no wasted words. The first sentence states the core purpose. Later sentences add essential defaults and alias info. Every sentence earns its place.

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

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

The description covers the main search functionality, returns, and defaults. With output schema present and high schema coverage, it is fairly complete. Minor gaps: pagination (offset/limit defaults) are only in schema, not description. Still sufficient for most use cases.

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, the description adds significant value: explains aliases (query, q, keywords), default date range logic, and provides a concise purpose for each parameter. The examples further clarify usage, e.g., showing ptype codes.

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 searches active federal contract opportunities with multiple filter criteria (keyword, NAICS, set-aside, date range, procurement type). It distinguishes from siblings like sam_entity_search and sam_search_exclusions by focusing on opportunities.

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

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

The description provides important usage guidance: SAM.gov requires a posting date range and defaults to last 30 days if omitted. It also mentions alias parameters. However, it does not explicitly contrast with sibling tools like sam_set_aside_opportunities for set-aside-specific searches.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, while the description adds value by stating the return format (titles, deadlines, agencies). No contradictions, though pagination or rate limits are not mentioned.

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

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

Two sentences with no waste. The purpose is front-loaded, and every word serves a purpose. Excellent 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 that an output schema exists and annotations cover safety, the description is sufficiently complete. It explains inputs and outputs concisely, though it could mention the API key requirement explicitly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional parameter meaning beyond what the schema provides, meeting the baseline.

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

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

The description uses a specific verb ('Find') and clearly identifies the resource ('federal contracts reserved for small businesses') and the types of set-asides. It distinguishes from siblings like sam_search_opportunities by focusing on set-aside contracts.

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

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

The description implies usage for set-aside contracts but provides no explicit guidance on when to use this tool versus alternatives like sam_search_opportunities or sam_entity_search. No exclusions or conditions are mentioned.

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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining the dual pipeline behavior (structured SEC vs. grounded pipeline), the tolerance parameter mechanics, and the verdict types. It provides behavioral context 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 relatively long but well-structured and front-loaded with example usage phrases. Every sentence adds value, though it could be slightly more concise without losing 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 has 2 parameters, no output schema, and rich annotations, the description is complete. It explains the return values (verdict, actual value with citation, reasoning) and covers different claim scenarios, leaving no significant 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%, so baseline is 3. The description adds meaning beyond the schema by providing examples for the claim parameter and explaining the tolerance_pct's usage, default behavior, and override scenarios.

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 verifies factual claims, using phrases like 'Is it true that...', 'fact check', and 'verify the claim'. It specifies the verb-resource pair and distinguishes from siblings by noting it replaces multiple sequential calls and handles specific claim types.

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: 'whenever the agent needs to check whether something a user said is factually correct'. It differentiates between company-financial claims and other claims, providing clear context. It does not explicitly state when not to use, but the guidance is otherwise clear.

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