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 mark it read-only, open-world, and idempotent. The description goes well beyond those by revealing that it routes to 5,710 tools across 1,494 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. No contradiction with annotations exists.

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

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

The description is dense but well-structured and front-loads the most important guidance ('PREFER OVER WEB SEARCH'). Every sentence contributes either scope, examples, or sibling differentiation. It is longer than minimal, but the breadth of the tool justifies it; a slight trim could improve scannability.

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

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

For a broad routing tool with a simple schema and strong annotations, the description is remarkably complete. It covers what the tool does, when to use it, when not to, examples, behavioral details, and how it relates to key siblings. Nothing essential for correct selection and invocation is missing.

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

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

The input schema is fully documented (100% coverage) and the required parameter 'question' has a clear description plus examples in the schema. The tool description adds context about the kinds of questions to ask but does not need to repeat parameter details. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

The description states a very specific purpose: answer factual questions with authoritative structured data from thousands of verified sources, returning citations. It clearly differentiates from sibling tools by name (ask_pipeworx_grounded, deep_research) and by scope, so an agent knows exactly what this tool is for.

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

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

Usage guidance is explicit and comprehensive: it says to prefer this over web search, gives trigger phrases, provides concrete examples, declares it the default entry point, and names when to step up to alternatives. This is model guidance for when to use the tool versus siblings.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds behavior beyond that: it is an experimental edge with candidate routing improvements, currently identical to ask_pipeworx, and it is a full working router that does not fall back to anything. There is no contradiction with annotations.

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

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

Four sentences, front-loaded with the core definition and then adding current status, usage, and a caveat. Some detail (retirement date) is beyond the minimum but not distracting; no filler. Slight overlap between 'currently matches exactly' and 'use exactly like ask_pipeworx' keeps it from 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?

For a router tool, the description covers identity, current behavior, experimental status, usage criterion, and the fact that it is fully functional. It says response shape is the same as ask_pipeworx, which is enough given the sibling context, though a more explicit output note would fully close the gap with no output schema.

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

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

Schema description coverage is 100%, and each parameter is documented in the schema, mostly as aliases for question. The description only says 'same arguments,' which reinforces cross-tool consistency but doesn't need to restate 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 opens by identifying the tool as a beta version of ask_pipeworx and a universal router, with the same 5,710 tools, arguments, and response shape. This makes the verb/resource relationship explicit and distinguishes it from the stable ask_pipeworx sibling and from 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?

'Use it exactly like ask_pipeworx when you want the newest routing' gives an explicit condition for choosing this tool over the stable sibling. It also explains that outputs are compared against the stable router to decide merges. It could add an explicit 'use stable ask_pipeworx in production' exclusion, so 4 rather than 5.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the full return contract, refusal reasons, the extra LLM call cost, and the constraint that answers are extracted solely from the tool result. This adds meaningful runtime behavior not available in structured fields.

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

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

The description is front-loaded with the core behavior, then return contract, use cases, and cost tradeoff. Each sentence contributes distinct information; no filler or repetition.

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

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

With no output schema, the description supplies a complete return envelope (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerates all refusal modes. Combined with 100% parameter schema coverage and safety annotations, an agent has enough to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters; the description does not need to add parameter-level meaning. It adds behavior context but not new parameter semantics, so the 100% coverage baseline of 3 applies.

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

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

The description names a specific behavior: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from the tool result, with explicit refusal outcomes. This clearly distinguishes it from the sibling ask_pipeworx and conveys the resource/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?

It explicitly states when to use it — when an answer will be quoted, cited, or acted on and facts must not be invented — and when not to, preferring ask_pipeworx for casual lookups because of the extra LLM call. This is direct alternative 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 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?

Annotations already carry readOnly/openWorld/idempotent/non-destructive hints, and the description still adds extensive operational context: internal facet decomposition routed across 5,710 tools in parallel, the exact findings-packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), never-invented gaps[] handling, per-depth hop mechanics, contradictions[] behavior, citation_uri resolvability guarantees, semantic excerpting versus head-truncation, and latency expectations (15-60s, thorough up to ~90s). Nothing contradicts 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?

Front-loaded with the critical gate (account requirement and the ask_pipeworx fallback) before purpose, usage, and behavioral detail. At roughly 300 words it is long, but every sentence carries operational value; the main blemish is a syntactically tangled middle section on hop mechanics ('First hop is always standard/hop-level routing with 3 facets') that the schema expresses more cleanly.

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

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

For a complex research tool with no output schema, the description fully covers return structure, gap/error handling, citation semantics, prerequisites, latency, and alternatives. Nothing an agent needs to decide whether to call it, with which depth, and what to expect is missing.

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

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

Schema description coverage is 100%; the schema already documents both params fully, including the depth enum's facet counts, hop behavior, and default. The description adds only marginal semantics — latency expectations per depth and the paid-plan gate on 'thorough' — while mostly restating what the schema already says, so the 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources ... in ONE call,' and clarifies the mechanism (decomposes into facets, routes in parallel). Explicitly distinguishes itself from siblings and open-web search ('this is NOT open-web search'), so an agent can tell it apart without opening any other schema.

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 it ('Best for broad/multi-part questions over structured data') with concrete example phrasings, and gives explicit exclusions with the named alternative: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' Selection criteria are fully specified.

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?

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

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

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

The description is long but every sentence earns its place: all major aspects (purpose, usage, scope, claim token behavior, rate limits) are necessary for correct use. It is front-loaded with the primary purpose and then logically organized, making it easy to parse despite the length.

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

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

For a tool with no output schema, the description fully covers the return behavior (claim_token), the two-phase feedback follow-up workflow, constraints (daily limit, quota), and appropriate content guidelines. It gives the agent all necessary context to decide when and how to invoke the tool correctly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is concise (~100 words), front-loaded with the main function, and uses bulleted use cases for clarity. Every sentence is purposeful and well-structured.

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

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

Given the tool's simplicity (one param, no output schema, rich annotations), the description covers return values, parameter effect, caching, data source, and use cases completely. No gaps remain.

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

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

Schema coverage is 100% with one parameter (window). The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the enum values.

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

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

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

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

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

The description provides three explicit use scenarios: discovering hot data sources, confirming canonical tools, and checking use case alignment. While it does not mention when not to use or alternatives, the use cases serve as effective guidelines.

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

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

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

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

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

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

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities array, partition_check results, fill check details). It covers edge cases like skipped_low_similarity, placeholders, and provides trade advice. The description is complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: for `event` it explains single-event mode, gives examples of slugs, and describes the partition check and monotonicity checks. For `topic`, it explains cross-event scanning and the union of markets. This adds substantial value beyond the schema.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and explains what each does, making the purpose specific and differentiating from sibling tools.

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

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

The description explicitly recommends when to use each mode: `event` for a specific market, `topic` for cross-event scanning. It also advises against trading when realizable edge is ≤0 and directs to `polymarket_fill_risk` for custom sizing, providing clear usage guidance and alternatives.

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

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

The description extensively discloses behavioral details beyond annotations, including caching (KV level keyed on knobs), response structure (by_segment, diagnostics), and filter effects (tradeable-edge knobs drop opportunities). It aligns with readOnlyHint and idempotentHint, with no contradictions. The disclosure of why segments might be empty is particularly valuable.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs with detailed model explanations and response fields. While front-loaded with purpose, the density of information may overwhelm agents scanning briefly. It could be more concise by moving some model details to a separate reference.

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

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

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

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

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

Schema coverage is 100% with descriptive parameter descriptions. The tool description adds context by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining their interplay (e.g., min_liquidity and max_spread_pp drop opportunities where edge isn't realizable). This provides meaningful semantic value beyond individual parameter descriptions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against using it for small trades and explains the risk of partial basket fills converting an arb into an unhedged directional position, providing clear context for when not to use it.

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

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

The description richly discloses behavior beyond the read-only/idempotent hints: it details safety fields, compatibility codes, skipped-leg counters, temporal alignment, and the rule that unknown metric_type/match_subtype legs are never paired. It also warns that BOTH compatibility fields can be non-empty even when matched_pairs>0. This gives an agent a precise model of the tool's edge cases.

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

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

The description is long but every section earns its place: modes, response shape, safety fields, compatibility codes, and practical caveats are all operationally relevant. The use of labels like TWO MODES, RESPONSE, and SAFETY FIELDS makes it navigable. It is dense rather than wasteful, though it could be tightened slightly.

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly: per-venue prices, top_spreads_pp, compatibility_warning, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and the skipped cross-type/cross-subtype counters. It also covers the practical caveat that most pre-mapped topics are not currently tradeable spreads.

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

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

The schema already documents all three parameters, and the description adds meaningful mode-level semantics: topic auto-fetches matching events, while kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. The explicit list of shortcut values and override examples make parameter behavior easy to invoke 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 opening sentence clearly identifies the resource and operation: computing the spread between Kalshi and Polymarket for the same resolving question. The two modes and response description further clarify what the tool does. It does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so it stops short of a 5.

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

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

The description gives clear guidance on the two modes: use topic shortcuts for pre-mapped events, or explicit kalshi_event_ticker plus polymarket_event_slug for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped does not mean tradeable. It lacks explicit 'when not to use this tool' or alternative tool names.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds behavioral context: scoping to identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. No contradictions.

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

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

The description is concise: three sentences that front-load the core purpose, then add context and scope. Every sentence earns its place—no fluff, no repetition.

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

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

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

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

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

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

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list), the resource (saved values/keys), and gives concrete use cases (ticker, address, notes). It effectively distinguishes itself from siblings remember and forget.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states the verb 'pull' and resource 'fired events from your subscription feed,' distinguishing it from sibling tools like 'list_subscriptions' or 'subscribe' by focusing on consuming fired events rather than managing subscriptions.

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

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

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

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

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

The description adds significant context beyond annotations: explains fallback logic (GDELT preferred, GNews when rate-limited/5xx), USPTO API sunset soft-failure, accepted date formats and recommendations, and return structure with grouped changes, total count, and citation URIs.

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

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

The description is comprehensive but slightly lengthy. It front-loads the core purpose and examples efficiently, but every sentence earns its place. A minor reduction for verbosity; still very well-structured.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond annotations (idempotentHint=true, non-destructive), the description adds valuable context: memory is scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. No contradictions.

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

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

The description is concise (3 sentences), front-loaded with the core purpose, and every sentence adds unique value. No redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: identifiers are labelled with the source that established them, unresolved identifiers are explicitly stated under `unresolved` rather than omitted, and LEI/FIGI enrichment 'degrades gracefully' if upstream services are unavailable. It also discloses that each call cascades through several internal lookup endpoints, giving performance expectations. This is rich, non-obvious behavior that agents benefit from knowing.

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

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

The description is long but well-structured: it opens with commonly used query phrases, then provides a one-sentence core purpose, followed by a detailed but logically organized breakdown of supported types. It uses capitalization, quotes, and enum-like references to improve scannability. While it is wordier than average, the tool's complexity (multiple entity types, identifiers, source attribution, fallback behavior) justifies the length. Minor trimming could make it tighter, but it is not redundant.

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 present, the description carries the full burden of explaining return values and behavior, and it delivers. It specifies exactly what is returned for company resolution (CIK, ticker, company_name, LEI, parent/ultimate-parent/children ownership, FIGI) and for drug resolution (RxCUI, ingredient, brand, citation). It also covers edge behavior like unresolved identifiers and graceful degradation. This makes the description self-contained for an agent to decide when to call the tool and what to expect.

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

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

The input schema already provides 100% coverage for both parameters, including enums and example values. The description enhances this by specifying acceptable input formats for company lookup (ticker, CIK, ISIN, or company name) and explaining the ISIN-to-LEI legal-entity mapping, which adds meaning beyond the schema's simple 'ticker (AAPL), CIK...' examples. However, it does not enumerate all formatting edge cases (e.g., case sensitivity or leading zeros), so it doesn't fully compensate for all potential ambiguity.

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 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and opens with concrete example queries like "What's the ticker for…" and "find the CIK for…". It differentiates from sibling tools by focusing specifically on name-to-ID resolution, while other tools like entity_profile likely serve broader entity-information needs.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also breaks down supported types ('company' and 'drug') with details on what each resolves, implying appropriate selection. However, it does not explicitly mention when not to use this tool or name alternative tools for different scenarios, so it stops short of a full when/when-not/alternatives specification.

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=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable behavioral context: it explains the one-year search cap, automatic posting-date resolution, and when to supply optional date parameters. It misses any details about rate limits or maximum result size, but given the annotations already cover safety, the description adds meaningful behavioral nuance.

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

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

The description is two sentences and front-loads the main purpose and value proposition. Every clause earns its place: the first sentence states what it does and its unique value, the second sentence provides critical usage guidance for the date parameters. 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?

Given the output schema exists, the description needn't explain return values. The description covers purpose, distinct value, and usage guidance for its parameters. It could be improved by mentioning whether there are any edge cases (e.g., what happens if an older solicitation isn't found with auto-resolution), but for a read-only tool with an output schema, this is largely 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 baseline is 3. The description adds extra semantic value by explaining the logic behind the posted_from/posted_to parameters: they are only needed for older solicitations, and the tool attempts to auto-resolve the posting date. This provides usage context beyond what the schema's descriptions offer. However, it doesn't add meaning for the _apiKey or solicitation_number parameters beyond what's in the schema.

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

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

The description uses a specific verb ('Get full details for a federal contract opportunity') and identifies the resource (solicitation number) and the key differentiator from sam_search_opportunities: returning fields the other tool does not carry. This clearly distinguishes it from 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 states when to use this tool ('if you need full details not carried by sam_search_opportunities') and when not to (implies you should use sam_search_opportunities for lightweight searches). It also provides explicit guidance on the posted_from/posted_to parameters, saying to pass them only for older solicitations because the tool automatically resolves the posting date for recent ones.

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

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

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

Even with strong annotations (readOnly, idempotent), the description adds significant extra behavior: relevance ranking with title weighting, the daily snapshot freshness indicator, default date range behavior, alias support, and the note about not requiring an API key. This far exceeds the annotation baseline and provides valuable invocation context.

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

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

Four sentences deliver a dense but coherent summary: the core search action and filters, data source and freshness, ranking behavior, return fields, date defaults, and aliases. No filler words; every sentence contributes useful information for tool selection and invocation.

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

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

Given the 12-parameter complexity and existing output schema, the description covers all critical operational aspects: source, refresh cycle, ranking specifics, default behaviors, and alias handling. It does not need to repeat return structures (schema exists) and provides enough context to predict how the tool behaves in edge cases like missing dates.

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

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

Schema coverage is 100% with detailed descriptions for every parameter. The description mostly restates alias and date-default details that already exist in the schema, but it adds the rationale for default date range ('SAM.gov requires a posting date range'). No significant new semantic meaning beyond the schema is provided, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Search active federal contract opportunities' by multiple concrete filters. It clearly distinguishes from sibling tools like sam_get_opportunity (single opportunity) or sam_search_exclusions (exclusions), and includes unique features like the relevance ranking and daily-refreshed extract.

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

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

The description makes the use case clear: general purpose search across contract opportunities with keyword and various filters. It does not explicitly name alternative tools or exclusion criteria, but the specificity of filters and mention of SAM.gov's default date range make it obvious when this tool is appropriate.

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

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

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

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

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

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

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

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

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

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

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

The schema already describes both parameters well (100% coverage), and the description augments this with practical guidance: tolerance_pct overrides implied tolerance, suggests 1–2 for hallucination detection, and notes the 5% cap. Claim examples reinforce usage. This adds meaning beyond the schema without fully duplicating it.

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

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

The description clearly identifies the tool as natural-language claim verification with an explicit verb ('validate') and resource ('claims'). It enumerates natural-language trigger phrases and describes two processing paths (structured vs grounded), distinguishing it from sibling research/analysis tools.

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

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

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

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