Mockdata

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds cost implications ('you pay Anthropic directly for those calls'), the default model, and the structure of the response. This goes beyond schema but doesn't fully detail edge cases like failure modes, so a 4 is appropriate.

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: the first states the core function, the second covers model and cost, the third covers return format and use cases. Every sentence earns its place with zero 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?

The tool has no output schema, but the description mitigates this by specifying the per-model shape ({score, confidence, signals, raw_response}) and a combined view. Use cases are provided. It could mention pagination or limits, but for the tool's scope it's adequately 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?

The input schema covers 100% of parameters, which sets a baseline of 3. The description adds extra context beyond the schema, including the default model, the callback for quoting that the user pays Anthropic directly, and the 'context' parameter's role in disambiguation. This earns 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 uses a specific verb ('Probe') and identifies the resource (LLMs) and output (visibility score 0-100 per model). It also notes the return format and default model, making the tool's function clear. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it falls 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 provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when the optional Anthropic probe is relevant. It does not mention when not to use the tool or name alternatives, so it's a 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?

Annotations already declare readOnly/openWorld/idempotent safety. The description adds behavioral context: routes to many tools, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradictions, but a few potential caveats (e.g., failure modes) 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?

The description is longer than average but well-structured: it front-loads the key directive ('PREFER OVER WEB SEARCH'), provides concrete examples, and concludes with usage guidance. Some phrases could be trimmed, but the length is justified by the tool's breadth.

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

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

For a complex tool with no output schema, the description covers what it does, when to use it, how it differs from alternatives, and what the answer looks like (structured with citations). This is sufficient for an agent to invoke 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?

Schema coverage is 100% – the question parameter and aliases are fully described in the input schema. The description reinforces that a natural-language question is required but adds no new parameter-level semantics beyond what the schema provides.

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

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

The description clearly identifies the tool as a general question-answering router that queries 5,529 tools across 1,455 sources and returns citable structured answers. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'USE WHENEVER the user asks...', and 'START HERE for most questions'. It also states when to step up to ask_pipeworx_grounded or deep_research, and covers breaking-news 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?

The description adds rich context beyond annotations: it discloses that no candidate is currently active, that it falls back to nothing (fully functional), and that it exists for comparative testing. This complements the readOnly and idempotent hints without contradicting them.

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

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

Every sentence conveys essential information: identity, relationship to stable, current state, usage, and purpose. It's front-loaded with the key fact ('Beta version of ask_pipeworx') and is information-dense without 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?

Despite no output schema, the description covers the tool's behavior, experimental status, current active state, fallback semantics, and relationship to the sibling. This fully prepares an agent to use it correctly in most scenarios.

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

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

Schema coverage is 100%, so the schema fully documents all six parameters (aliases for question). The description only says 'same arguments' and doesn't add parameter-specific semantics, but the schema is sufficient, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router identical to the stable tool but with candidate routing improvements. It explicitly names the resource and scope, and distinguishes it from its sibling by labeling it as the experimental edge.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This gives clear when-to-use guidance and implies ask_pipeworx is the stable 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 already mark the tool as read-only, idempotent, and open-world, but the description goes far beyond by disclosing the exact success and failure return shapes, including enums for refusal_reason. It also mentions the extra LLM call cost and the constraint that answers come only from tool results, which is critical behavioral context.

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

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

Every sentence adds value: purpose, mechanism, return format, failure modes, usage guidance, and trade-off. It is dense but not bloated, and the first sentence immediately communicates the core value proposition.

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 lacking an output schema, the description fully documents the return structure and refusal reasons, making the tool's behavior predictable. It covers routing, extraction, when to use, when not to use, and the cost trade-off, which is comprehensive 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% and clearly documents the question parameter and its aliases. The description adds no additional parameter-specific details, but it doesn't need to because the schema already handles semantics. Baseline 3 is appropriate.

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

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

The description opens with "Hallucination-resistant answer mode for high-stakes reads," immediately establishing a specific purpose. It clearly differentiates from the sibling ask_pipeworx by explaining the grounded extraction and explicit refusal behavior, so the agent knows this is the safer, evidence-based variant.

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: "Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts." It also names the alternative (ask_pipeworx) and gives a clear trade-off: "Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups." This is ideal usage guidance.

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

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

The description goes far beyond annotations by detailing fan-out behavior, response shapes, resolver contract (market_match_confidence, suggestions), parent_event extractor, news fallback fields, safety short-circuits (low_confidence_match, market_closed_or_inactive), and cancellation rule risk. It candidly explains that resolved markets usually surface via the low_confidence_match path and that analysis fields may be suppressed.

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 very long but front-loaded with purpose and clear usage, followed by labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section adds critical operational detail for a complex tool, so the length is largely justified, though a bit more brevity would 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?

With no output schema, the description fully compensates by detailing all major response shapes, resolver behaviors, parent_event data, news fallback semantics, and cancellation-rule risk. It covers edge cases like wide spreads, closed markets, and low-confidence matches, making the tool's behavior predictable and 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?

The input schema already provides 100% coverage of all three parameters (market, depth, include_raw), including descriptions. The tool description repeats the market input formats already in the schema and does not add deeper parameter semantics for depth or include_raw. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by stating it resolves, classifies, fans out to data packs, and returns an evidence packet plus market-vs-model comparison, with explicit use cases like 'should I bet on X'.

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 for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also provides rich fan-out examples and safety caveats. However, it does not explicitly mention alternatives or when not to use it, leaving some room for ambiguity relative to sibling tools like polymarket_edges.

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, non-destructive, and idempotent. The description adds substantial behavioral detail: single parallel call, data provenance (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and citation URI return values.

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 with user-phrase examples, type-specific details, and a clear why-to-use rationale. It is longer than ideal, but every sentence adds functional value, making it appropriately concise for the tool's complexity.

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

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

For a tool with no output schema, the description covers the essential return behavior (paired data + citation URIs), input constraints, type-specific data dimensions, and edge-case handling (off-calendar fiscals). It is fully complete 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 description coverage is 100%, providing a solid baseline. The description adds useful data-source context (e.g., 10-K metrics, FAERS counts) and examples, but does not significantly alter parameter understanding beyond what the schema already states.

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

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

Clear, specific purpose: side-by-side comparison of 2–5 companies or drugs. The description names user phrasings, data sources, and explicitly contrasts with sequential single-pack lookups, distinguishing it from sibling tools like 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?

Provides explicit preference rule: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also covers type-specific usage and limits, though it doesn't name specific alternative tools or state when to avoid using it beyond the entity-count constraint.

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

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

Discloses far beyond annotations: account requirement, paid plan for 'thorough', depth-specific behavior (gap recovery, contradictions[]), citation_uri fetchability, semantic excerpting, parallel execution, and latency expectations. No contradiction with readOnly/openWorld/idempotent hints.

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

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

The description is long but well-structured and front-loaded with the most critical constraints (account requirement, alternatives). While some depth-tier details repeat the schema, each sentence provides operational value for a complex tool.

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

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

Covers all necessary context: purpose, prerequisites, alternatives, depth semantics, output packet contents, gaps[], contradictions[], citations, and latency. Given the tool's complexity and lack of an output schema, the description is complete and self-sufficient.

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

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

Schema already covers both parameters with detailed descriptions; the tool description adds example questions, payment nuances for 'thorough', and a clear statement that broad/multi-part questions are fine. This extra context raises it above the baseline of 3.

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 performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and decomposes questions into facets routed to 5,529 tools in parallel. It distinguishes itself from ask_pipeworx and identifies the exact resource and action.

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: 'Best for broad/multi-part questions over structured data' and directs single lookups or breaking news to ask_pipeworx. Also states to use ask_pipeworx if not signed in. Example questions clarify ideal usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by detailing the response format (names, descriptions, full input schemas with curated examples) and the fact that results are directly callable without a second lookup. It also notes 'Call this FIRST' as a behavioral recommendation. This goes beyond the annotations and clarifies what the agent can expect from the tool.

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

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

The description is slightly long but every part serves a purpose: the domain enumeration helps the agent match its need, the return-value detail avoids a second lookup, and the 'Call this FIRST' guidance is actionable. It front-loads the core purpose and flows logically. The only minor issue is the lengthy domain list, which is acceptable for a discovery tool but could be seen as slightly over-specified.

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 this is a read-only discovery tool with no output schema, the description covers what the agent needs: what it does, when to use it, what it returns (schemas included), and a direct-call guarantee. It doesn't need to explain error handling or pagination because the tool is straightforward and the schema covers limit/default. This is fully complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not elaborate on individual parameters (query, limit, aliases), but it does align with the 'query' parameter by saying 'describing the data or task' and 'top-N' which maps to 'limit'. The schema already documents aliases, default, and max, so the description adds little beyond what the schema provides. No deduction or bonus warranted.

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

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

The description opens with a specific verb+resource pair ('Find tools') and immediately clarifies scope ('by describing the data or task'). It then enumerates the exact domains covered (SEC filings, financials, FDA drugs, etc.), making it unmistakably distinct from sibling tools like ask_pipeworx or validate_claim. The return behavior ('top-N most relevant tools... ready to call directly') further pins down its purpose.

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

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

Explicit usage guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to invoke this tool and implies that if you already know the specific tool, you might skip discovery. No alternative tool is named, but the context is clear.

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

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

Even with annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds operational details: it fans out across multiple sources, returns specific fields, uses a GDELT→GNews fallback, and notes that patent lookup 'soft-fails' due to API sunset. This goes well beyond the baseline annotations and provides important context about robustness and failure modes.

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

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

The description is longer than average but is tightly packed with distinct pieces of information: intents, output fields, source list, and input constraints. It is front-loaded with example user phrasings and ends with a clear input directive. Each sentence serves a purpose; while concise, it is dense enough that a 5 would be arguable but 4 seems appropriate given 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?

Without an output schema, the description fully documents the return values: cik, company_name, recent_filings (with URI format), fundamentals (specific metrics and sort), patents (with sunset warning), news fallback, and LEI. It also covers the input constraints and behavior. For a complex multi-source tool, this is a complete and self-sufficient specification.

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 parameter descriptions. The tool description adds concrete examples ('AAPL', '0000320193') and reinforces the zero-padded CIK requirement and the exclusion of name-based lookup. While not adding entirely new info, it makes the parameter usage more concrete and actionable through examples and the resolve_entity redirect.

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 diverse example phrasings and immediately states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates specific output components (cik, recent_filings, fundamentals, patents, news, LEI), making the tool's function unmistakable. This clearly distinguishes it from siblings like compare_entities or resolve_entity.

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

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

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides an alternative for name-only input: 'use resolve_entity first if you only have a name.' This is clear when-to-use and when-not-to-use guidance, with a specific alternative tool named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds only the context of clearing sensitive data. It doesn't disclose additional behavioral traits such as permanence, error handling, or whether deletion is reversible, so transparency is adequate but not enhanced 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 two sentences, front-loaded with the primary action followed by usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a simple one-parameter tool with annotations covering safety and behavior, the description covers purpose, usage, and sibling relationship. It doesn't mention return values or error behavior, but these are not critical for a delete operation, and the absence of an output schema makes this acceptable.

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

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

The schema fully describes the 'key' parameter with a description and example, achieving 100% schema coverage. The description only adds 'by key', which adds no new semantic value beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Delete') and a clear resource ('a previously stored memory by key'), making the tool's function unambiguous. It also distinguishes itself from sibling tools by pairing with 'remember' and 'recall', clearly marking itself as the deletion counterpart.

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

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

The description provides explicit when-to-use scenarios ('context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember and recall. However, it doesn't include an explicit when-not-to-use statement or name any alternative deletion tools, so it falls short of a 5.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by explaining the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the purpose, then process, then use cases. Every sentence adds value and there is no fluff or repetition of schema/annotation details.

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 tool with no output schema, the description clearly explains what the output is ('single text blob ready to drop at site-root/llms.txt') and the general process. It doesn't include an example or error handling, but given the low complexity, it is adequately 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?

The input schema provides 100% coverage with clear descriptions for both 'url' and 'max_links'. The description does not add extra parameter details beyond what is already in the schema, so the baseline of 3 is appropriate.

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

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

The description has a specific verb ('Generate') and resource ('llms.txt file for any URL'), and clearly states the output format. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing specifically on producing a ready-to-deploy llms.txt file.

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

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

The description provides clear context for when to use the tool via the 'Useful for:' list (indexing a client's site, drafting for own project, auditing competitors). It does not explicitly mention when not to use it or alternatives, but the use cases are sufficient for most agents.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral context: data is fake, keyless, and offline, which goes beyond annotations. No contradiction noted.

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?

One concise sentence that front-loads the action and includes a comprehensive field list and key constraints. No redundant information.

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

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

With a single parameter and no output schema, the description compensates by listing output fields and clarifying the offline/fake nature. Fully sufficient for an agent to 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?

Input schema covers the single 'count' parameter with description and range (1-100, default 1), so description adds no additional parameter semantics. Baseline 3 is appropriate when schema coverage is 100%.

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

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

The description uses the verb 'Generate' with a specific resource 'fictional person record(s)' and enumerates fields (name, email, phone, address, company, job title, birthdate, uuid), clearly distinguishing it from sibling 'lorem' which generates generic placeholder text.

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 'for testing/seeding (keyless, offline)' and 'All data is FAKE,' indicating it's not for real-world use. It doesn't mention alternatives, but the context is clear and excludes production usage.

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 safety is covered. The description adds value by disclosing the return shape (id, type, params, created_at, last_fired_at, fire_count) and the 'caller's active subscriptions' scope, 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 two sentences: first states the primary action and return fields, second gives usage guidance. Every sentence earns its place with no fluff. It is front-loaded with the core purpose and reads clearly.

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 one optional parameter, rich annotations, and no output schema, the description is complete. It covers scope, return fields, and practical usage. The include_inactive parameter is already documented in the schema, so nothing important is missing.

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

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

The single parameter include_inactive has a full description in the schema (100% coverage), so the schema carries the semantic weight. The tool description does not mention the parameter, but given the high schema coverage, this is acceptable per 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 and resource: 'List the caller's active subscriptions.' It clearly distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing. The return fields are also specified, making the purpose unmistakable.

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

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

The description provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use the tool relative to subscribing/unsubscribing, though it doesn't name sibling tools explicitly. It gives actionable guidance without being verbose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond these by noting 'keyless, offline' and specifying that 'unit' defaults to 'sentences,' which enriches the agent's understanding of the tool's operation without contradicting the annotations.

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

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

The description is a single, well-structured sentence that front-loads the core purpose ('Generate lorem-ipsum placeholder text') and then pragmatically lists the key parameters and defaults. Every word earns its place, and it is appropriately concise for such a simple tool.

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

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

For a simple, low-risk tool with full schema coverage and clear annotations, the description covers all necessary aspects: purpose, keyless/offline nature, parameter meanings, and defaults. No output schema is present, but the return value (generated text) is self-evident from the tool's name and description, making this description complete for its 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?

The input schema already provides full descriptions for both parameters ('unit' and 'count') with examples and defaults, achieving 100% schema coverage. The description merely repeats the options and default for 'unit' but adds no additional semantic value beyond what the schema already offers, 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 clearly states the tool's function with a specific verb+resource: 'Generate lorem-ipsum placeholder text.' It also distinguishes itself from all sibling tools (which are focused on research, entities, or subscriptions) by being a simple utility for placeholder content.

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 by stating it's a placeholder text generator that is 'keyless, offline,' but it does not explicitly state when to use it or mention any alternatives. Since no similar sibling tool exists, the lack of explicit 'when not to use' is not critical, but the guidance is minimal.

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 important behavioral details beyond the sparse annotations: filing without an account returns a claim_token that can be reused to check status, rate limiting to 5 per identifier per day, and that it is free and does not count against tool-call quota. It also explains how the team processes feedback, which adds meaningful operational context.

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

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

The description is long but well-structured with a clear logical flow: purpose, use cases, exclusions, claim_token workflow, and constraints. Every sentence adds necessary information; however, it is slightly verbose, and a more compact structure could improve skimmability while retaining the same content.

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

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

For a tool with 4 params, nested context object, and no output schema, the description covers all necessary aspects: it explains each parameter's spirit, the claim_token workflow, rate limits, and the distinction from other MCP servers. The return behavior (claim_token, status updates) is explained even without an output schema, making the tool fully self-contained.

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 defines all parameters. The description adds valuable operational semantics for the claim_token parameter (how to pass it back and what it returns), plus context on rate limits and usage expectations, going beyond the schema's field-by-field descriptions.

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

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

The description opens with a clear verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly covers bug, feature, data_gap, and praise use cases, and distinguishes itself by stating it ONLY applies to tools served by this Pipeworx connection, differentiating it from siblings like ask_pipeworx or discover_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 scenarios for each feedback type, and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also gives a rule of thumb for identifying Pipeworx tools, making the usage guidance highly actionable.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds meaningful context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on window. These details enhance understanding of the tool's behavior without contradicting 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 three sentences with a clear, front-loaded statement of functionality, followed by a structured 'Useful for' list and a succinct note on data source and caching. Every sentence contributes value, with no filler or redundancy.

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

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

Although there is no output schema, the description explicitly states the return contents (top tools, top packs, total call volume, and the format '(pack, tool, count)'), addresses privacy ('no PII'), and notes caching behavior. For a simple, single-parameter tool with comprehensive annotations, this is complete enough for an agent to invoke 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?

The schema description already covers the 'window' parameter fully (100% coverage), including the default and the interpretation of shorter vs longer windows. The description itself merely repeats the window options and does not add new semantic meaning, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'returns' and specific resources make it distinct from sibling tools like discover_tools or recent_alerts, fulfilling the specific verb+resource criterion.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical choices, and aligning use cases with agent demand. This gives clear context for when to use the tool, but it does not explicitly mention when not to use it or name alternative tools as a direct contrast.

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 deep behavioral context: internal checks like partition_check sum >3pp deviation, Jaccard similarity ≥0.30, placeholder fraction >20% filter, and fill_check pricing against live CLOB depth. It even interprets outputs: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.'

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?

Although lengthy, every sentence earns its place. It starts with the core purpose and mode selection, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex logic. No redundant material; each threshold and example directly aids correct 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?

With no output schema, the description supplies the full response contract: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also explains edge-case signals like skipped_low_similarity and placeholders_filtered, making the tool's behavior fully self-contained.

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 both params, yet the description significantly enriches them. For 'event', it specifies 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check'. For 'topic', it explains 'searches related events across the platform, flattens markets, runs the comparator on the union'. This transforms the params from simple strings into behaviorally distinct modes.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by focusing on cross-market arbitrage rather than single-market edges or fill risk. Examples like 'fed-decision-may-2026' provide concrete illustration.

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 covers all three modes: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also points to an alternative tool for sizing: 'For custom sizing use polymarket_fill_risk', making the when-to-use boundaries clear.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the model families, per-leg Kelly calculation, slippage handling, filters, response structure including diagnostics, and the 1h KV-level caching keyed on all knobs. This gives the agent deep insight into what the tool does and its edge cases, such as placeholder-slug filters and partition-level Kelly 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 extremely long and dense, resembling a specification rather than a concise tool guide. While every sentence carries technical value, the lack of formatting (e.g., bullet points or section breaks) makes it harder to parse quickly. It is front-loaded with the core purpose, but the volume of detail makes it less concise than ideal.

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 thoroughly explains the return structure: by_segment with three segment names, fed_candidates/fed_note with reliability caveat, and _diagnostics containing funnel counters, category_counts, and filter_skips. It also covers per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume) and the 24h-move warning, making the tool's behavior fully comprehensible for an agent.

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

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

Although the input schema already has 100% description coverage for all 9 parameters, the description adds high-level context by grouping knobs into 'TRADEABLE-EDGE KNOBS' and explaining their interplay with the filtering pipeline (e.g., min_partition_leg_kelly compensates for zero parent-level Kelly in partition arbs). This enriches the schema's per-parameter descriptions with system-level 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 immediately states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself by the use case 'what should I bet on today' and explicitly enumerates the three response segments (model_driven, structural_arbitrage, concentrated_longshot), separating it from sibling tools 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 a clear use case: 'agents discover opportunities without paging hundreds of markets.' It also includes a caveat about Fed bets being excluded from ranking due to unreliable signals, which helps an agent decide whether to rely on those candidates. However, it does not explicitly contrast with alternatives or state when not to use the tool, only implying its suitability for opportunity discovery.

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 reveals important behavioral traits beyond the readOnly/idempotent annotations: snapshots are written on cache-miss (causing gaps), history is limited by a 60-day TTL, decay is computed from daily closes not intraday, and edge_pp_net is signed by trade direction. These details are not captured in the annotations and are highly valuable for avoiding misinterpretation.

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

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

The description is well-organized with labeled sections (Answers, Args, RESPONSE, LIMITS) and every sentence earns its place. It is long but justified by the output complexity, and the opening analogy effectively conveys the core value. No fluff or redundancy.

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

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

This tool has no output schema, so the description must explain return values. It thoroughly describes tracked[], expired[], and snapshot_dates[], including field-level semantics like trend values, decay_pp_per_day, lifespan_days, and the meaning of gaps. It also covers edge cases like TTL boundaries and cache-miss behavior, making it highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats parameter info ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding significant new meaning beyond the schema. The schema already provides defaults, clamps, and allowed 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 the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges, with a concrete example of fresh vs. old wide edges being different trades. The verb+resource+scope is specific and 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?

It provides a clear use case—evaluating whether an edge is fresh or decaying—and explains why that matters ('different trades'). However, it does not explicitly name alternative tools or state when not to use it, though the context strongly implies it complements rather than replaces current-edge 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?

Beyond the readOnlyHint/openWorldHint annotations, the description details exactly how the tool behaves: it 'walks the ladder', provides a verdict (clean|degraded|cannot_fill), identifies 'thin_legs[]' and 'forced_directional_risk', and warns about partial-fill conversions into unhedged positions. This is rich behavioral disclosure that goes far beyond annotation hints.

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

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

The description is long but densely informative. It is front-loaded with the core purpose, then structured into SINGLE-MARKET and BASKET sections with clear parameter semantics, return values, and usage guidance. Every sentence contributes value, and the structure aids scannability 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?

The tool has no output schema, so the description must explain return values; it does so in detail for both modes, including theoretical vs realizable sums, capture_ratio, profit_usd, per-leg fill details, and risk warnings. It also covers parameter defaults, modes, and explicit usage context, making the description fully adequate for the tool's complexity.

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

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

Even though the schema already describes all four parameters with 100% coverage, the description adds crucial semantics: it distinguishes single-market vs basket modes, explains side defaults and their different meanings (sell_yes = capture overround, buy_yes = capture underround), and clarifies size_usd as 'max spend on buys, target proceeds on sells' versus 'settlement notional S' in basket mode. This is substantially more than the schema provides.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This specific verb–resource combination distinguishes it from siblings like polymarket_arbitrage and polymarket_edges, which focus on finding edges rather than verifying fill risk.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing thin-book overround and partial-fill risk, making the when-to-use cotext clear and actionable.

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

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

The description goes far beyond annotations by explaining the meaning of safety fields, compatibility warnings, temporal alignment, and skipped cross-type/subtype counters. It details conditions for false signals and when spreads are meaningful, offering deep behavioral 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 long but well-structured and front-loaded with the core purpose. It contains necessary detail for a complex tool, though some sections (e.g., explaining skipped_cross_type/subtype) could be more concise. Overall, every sentence adds 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?

Given no output schema, the description fully explains the response structure (leg-by-leg prices, spread, compatibility warnings). It covers modes, safety fields, temporal alignment, and edge cases. The tool's complexity is high, and the description addresses all major aspects, leaving little ambiguity.

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

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

While the schema already covers all parameters, the description adds crucial context: it explains the two modes, how explicit parameters override topic mappings, and what the response will contain. This enriches the meaning of each parameter significantly beyond the schema.

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

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

The description clearly states the tool's function: calculating cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by explicitly focusing on cross-venue comparisons and differentiates between equivalent and non-equivalent bet shapes.

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

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

Provides explicit guidance on when to use the tool with two modes (topic shortcuts vs explicit tickers), and warns that most pre-mapped topics return compatibility_warning, meaning they may not be tradeable. This tells the agent exactly when the tool is appropriate and sets expectations.

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, and non-destructive behavior. The description adds valuable context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the detail that omitting the key lists all saved keys. It does not cover error cases or return value specifics, but the annotation coverage lowers the bar.

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 with no filler. The primary action and the secondary list mode are front-loaded in the first sentence, followed by use cases and scoping in the second. Every clause earns its place, making it both concise and informative.

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 tool with one optional parameter and no output schema, the description provides sufficient context: purpose, usage examples, scoping, and relationship to complementary tools. It does not explain return values, but the tool's functionality is straightforward and the description covers the key decision-making needs of an agent.

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

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

Schema coverage is 100% (the 'key' property is described). The description adds meaning by explaining that omitting the key lists all keys, which is critical for using the optional parameter. The examples of potential key values (target ticker, address) help illustrate semantics without being redundant.

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

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

The description clearly states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes itself from sibling tools by explicitly naming the paired remember and forget tools, making its role in the memory system immediately apparent.

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 guidance on when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains the alternative by mentioning 'Pair with remember to save, forget to delete,' which sets clear usage boundaries.

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 mark_read side effects and the persisted feed behavior, but these contradict idempotentHint and readOnlyHint annotations. If events are flagged read, repeated calls are not idempotent, and the operation is not purely read-only.

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 adding value: what it returns, how to filter, mark_read side effect, and alternative access. No filler.

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

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

Covers return format, filtering, side effects, and alternative access. No output schema exists, so explaining the payload is useful. Lacks error conditions or pagination, but for a simple feed reader it's 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 covers 100% of parameters. The description adds semantics for 'type' (example sec_8k), 'since' (ISO timestamp), mark_read (flag read), and unread_only (read_at null), enriching the schema definitions. Limit is not mentioned but schema covers 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 names a specific resource ('fired events from your subscription feed') and a clear action ('Pull'), with return details (source, citation_uri, payload). This distinguishes it from siblings like list_subscriptions or recent_changes.

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

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

Gives concrete usage context: filters by type/since, mark_read behavior, and polling suitability. Also points to an HTTP endpoint for scripts/dashboards. No explicit exclusions or mention of sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavioral context: concurrent fan-out to multiple sources, GDELT-to-GNews fallback on rate limits or 5xx, and USPTO's soft-fail due to API sunset. However, it doesn't disclose authentication requirements or error handling beyond the fallback, so a 4 is appropriate.

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

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

The description is a single dense paragraph but is well-structured with examples, source details, parameter syntax, and output summary. It earns its length given the tool's complexity, but could be broken into bullet points for readability. No filler sentences.

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

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

Given no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all parameters, sources, fallback behavior, and alternative tools. For a tool with this complexity, the description is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for 'since' by specifying allowed formats ('ISO date or relative shorthand') and recommending '30d' or '1m' for typical monitoring. It also reinforces 'value' accepting ticker or CIK. This goes slightly beyond the schema, justifying 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's purpose: a change feed for a company over the last N days/weeks/months, with example queries like 'What's new with X' and 'latest on Y'. It also distinguishes itself from entity_profile, which is for static profiles, making the purpose unambiguous and distinct 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?

It provides explicit when-to-use guidance with example natural language queries, and explicitly says 'Use entity_profile instead when you want the static profile', giving a clear alternative. It also explains the internal fan-out to SEC EDGAR, GDELT/GNews, and USPTO, which helps the agent decide based on data needs.

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, destructiveHint=false), the description adds key behavioral details: scoping by identifier, persistence duration (authenticated vs anonymous), and key-value storage model. While it doesn't mention overwrite behavior, the annotations already imply safe repetition, and the added context is valuable.

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

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

The description is only three sentences, front-loaded with the main action, and uses no fluff. Every sentence adds unique value: what it does, when to use, persistence details, and companion tools.

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 tool with two well-documented parameters and no output schema, the description fully covers the essential context: purpose, usage, persistence, and related tools. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces key-value semantics and adds scoping context ('scoped by your identifier') that clarifies how keys work. Examples in the schema provide concrete format guidance, and the description complements rather than repeats.

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 saves data for later reuse, specifying the verb 'Save' and the resource (memory key-value store). It distinguishes itself from siblings by naming recall and forget, and provides concrete use cases (resolved ticker, target address, user preference).

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: 'Use when you discover something worth carrying forward'. Also mentions pairing with recall to retrieve and forget to delete, giving alternatives and complementing 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?

Although annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes beyond them with important behavioral details: 'every identifier is labelled with the source that established it, and an identifier that could NOT be resolved is stated explicitly under unresolved rather than omitted,' 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return,' and 'Each call cascades through several lookup endpoints internally.' These disclosures are valuable and not present in annotations.

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

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

The description is relatively long but well-structured: it front-loads example user queries, then gives the core instruction ('Use FIRST whenever you have a name but need an ID'), followed by a clear SUPPORTED TYPES breakdown. Every sentence contributes useful information. It could be tightened by removing some redundancy, but it remains highly scannable.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, output schema absent), the description thoroughly covers what is returned (CIK, ticker, company_name, LEI, FIGI for company; RxCUI, ingredient, brand for drug), how unresolved identifiers are handled, and graceful degradation behavior. It also explains the internal cascading, giving the agent enough context to set expectations.

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

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

Schema description coverage is 100% and the schema already provides meaningful descriptions for both parameters (e.g., 'For company: ticker (AAPL), CIK (0000320193), or name'). The description adds contextual color about output fields and sources, but it does not materially change how the parameters should be interpreted. Baseline 3 is appropriate.

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

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

The description opens with explicit example queries ('What's the ticker for…' / 'find the CIK for…') and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It further distinguishes itself from siblings by instructing 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource combination with clear scope.

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

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

The description provides explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types and input formats, making it clear when to invoke this tool. However, it does not explicitly mention when not to use it or name alternative tools, so it misses the full 'when-not/alternatives' criterion.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat safety. It adds valuable context on orchestration (probes each entity with ai_visibility_check, ranks results) and return format (ranked list with score, confidence, signal density), which are not present in annotations.

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

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

The description is three sentences: the first states the core purpose, the second explains the probing and ranking mechanism, and the third gives an example use case. Every sentence earns its place, and the illustrative quote adds clarity without bloat.

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 and four parameters, the description covers the main inputs, the multi-probe orchestration, the ranking output, and a concrete use case. It lacks details on score interpretation or error handling, but these are not essential for an agent to invoke it correctly, especially with annotations covering safety and idempotency.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add meaningful extra semantics beyond the schema; the "first entry as subject" detail is already in the entities parameter description. No additional defaults, edge cases, or formatting details are provided.

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

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

The description uses the specific verb "Compare" and identifies the resource as "AI visibility across multiple entities side-by-side." It clearly states the outcome (ranks by score, surfaces most/least recognized) and explicitly names ai_visibility_check as the underlying probe, differentiating it from the single-entity sibling tool.

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

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

The description says "Useful for competitive AI-marketing audits" and gives an example, establishing clear when-to-use context. It implies the alternative (ai_visibility_check for single entities) by mentioning it probes each entity with that tool, but it does not explicitly state exclusions or name other comparison alternatives like compare_entities.

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 the read-only/idempotent annotations: composite fan-out execution, partial failure degradation, and a 5-30s latency for first-time bundlephobia measurements. No contradiction with annotations.

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

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

The description is dense but efficiently structured: purpose, usage, output, ecosystem scope, and failure behavior are clearly delineated. The parenthetical list of output fields is somewhat verbose but earns its place given there is no output schema.

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

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

Without an output schema, the description fully enumerates the return contents (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases like timeouts and ecosystem limitations. This is complete for a complex composite 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% and both parameters are well-documented. The description adds no additional parameter-specific semantics, but it does explain the output structure which indirectly clarifies the version parameter's role. Baseline 3 is appropriate.

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

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

The description states a specific composite purpose: a 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It clearly distinguishes this tool from siblings by naming its unique data sources and use case.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', and specifies that non-NPM ecosystems fall under deps.dev:version directly, effectively providing when-not-to-use guidance.

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

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

Beyond annotations (readOnly, idempotent), the description reveals implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap, and truncation with a flag. It also explains the practical value of char offsets for verifying verbatim quotes. This adds substantial behavioral context not present in annotations.

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

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

Four sentences, each earning its place: purpose, use case, pairing, and technical constraints. No repetition of schema fields, no fluff. It is dense but highly readable and front-loaded with the core action.

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

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

Even without an output schema, the description conveys return format (passages with offsets and similarity scores), boundaries (truncation cap), and integration with a sibling tool. For a 3-parameter tool with no output schema, this provides complete operational 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 enhances meaning by framing the 'text' parameter as 'already pulled' content (e.g., SEC 10-K body) and providing realistic query examples. It does not introduce new parameter details but clarifies the intended context, earning 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 opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by explaining it operates on already-fetched text rather than external data, and explicitly names ask_pipeworx_grounded as a complementary tool. The scope is precise: input text + query, output passages with offsets and scores.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also explains the benefit (saves context, returns only relevant passages) and pairs it with ask_pipeworx_grounded to define a workflow. This is clear guidance for both use 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 goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) by detailing authentication requirements, delivery channel mechanics, per-event email/SMS semantics, webhook HMAC signing and the 10-day auto-disable after 10 consecutive failing runs. This is rich behavioral disclosure.

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 organized paragraph that front-loads the core purpose, then covers requirements, types, and delivery options in logical order. Every sentence carries useful operational detail; no fluff or redundancy.

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

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

Given the tool has 3 parameters, nested objects, and no output schema, the description covers all essential facts: return value (subscription id), authentication requirements, per-type param syntax, delivery options, SMS cap, and webhook behavior. It is complete enough for an agent to correctly invoke the 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?

Although the input schema already covers parameters 100%, the description adds significant context beyond the schema: concrete examples for each subscription type (e.g., sec_8k items:['5.02'], fred_series series_id:'UNRATE'), explicit channel constraints (e.g., SMS E.164 and verification, webhook signing secret), and the always-on feed behavior. This greatly aids correct usage.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies a concrete create action on a specific resource (subscription) and is easily distinguishable from sibling tools like unsubscribe and list_subscriptions.

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

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

The description provides context on prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and explains supported subscription types with examples. While it doesn't explicitly say 'use this instead of X', the use cases are well-defined and the prerequisites are 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 and idempotentHint, so the bar for additional context is lower. The description adds that it returns category-bucketed example questions with exact tool + argument shape, and that it draws from a live catalog, which gives the agent insight into the output format and dynamic nature. However, it does not discuss any potential side effects or rate limits, but these are not expected for a read-only suggestion tool.

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

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

The description is quite long, listing many example trigger phrases and repeating the same idea in multiple ways. While it contains useful guidance, it is not as concise as it could be; the core purpose statement appears after a list of example queries. It earns a 3 for being informative but not tightly edited.

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

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

The tool is simple (one optional parameter, no output schema). The description fully covers what it does, when to use it, how to use the parameter, and what the response looks like. There are no gaps that would leave an agent confused.

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 fully describes the optional `topic` parameter with allowed values. The description adds value by explaining the effect of omitting vs providing `topic` (full spread vs focused) and gives specific examples like 'finance', 'pharma', 'betting'. This enriches the schema's static list with usage 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 clearly identifies the tool as an onboarding entry point that suggests example questions about what Pipeworx can do, with specific verb 'returns category-bucketed example questions'. It distinguishes itself from siblings by naming itself the FIRST tool to use when unaware of Pipeworx capabilities, and mentions meta-tools like ask_pipeworx, entity_profile, compare_entities.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' providing clear when-to-use guidance. It also gives call variations (no args vs topic) and mentions that it draws from the live catalog, implying it's for initial exploration rather than specific 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 non-readonly, idempotent, and non-destructive behavior. The description adds valuable context beyond these: ownership is enforced, rows are deactivated not deleted, and historical events remain available. This clarifies the operational semantics without contradicting 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 three short sentences, with the action front-loaded and no redundant information. Every sentence contributes a distinct detail: what it does, who can do it, and what happens to the data.

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 mutation tool, the description covers the essential behavioral aspects: ownership, deactivation instead of deletion, and linkage to recent_alerts. It does not mention the return format, but there is no output schema and the mutation's effects are sufficiently described.

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 provides 100% coverage for the single id parameter, describing it as a uuid returned by subscribe. The description reinforces that the cancellation is by id and references subscribe, but it does not add significant meaning 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 starts with 'Cancel a subscription by id', a specific verb and resource that clearly states the tool's function. It distinguishes from siblings like subscribe and list_subscriptions by focusing on the cancellation action and explicitly mentioning ownership enforcement.

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

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

The description provides clear usage context: it is for canceling own subscriptions, and it notes that the row is deactivated rather than deleted. While it does not explicitly list alternative tools or when not to use, the mention of recent_alerts for historical events implies the intended scope.

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 provides deep behavioral transparency beyond the annotations: it explains the two processing paths, the list of possible verdicts, and crucially distinguishes 'could_not_verify' (check failed, not evidence) from 'unsupported' (no source). It also reveals the presence of verification_error{stage,detail}. The readOnlyHint, openWorldHint, and idempotentHint annotations are consistent with this non-destructive, open-world verification tool.

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

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

The description is long but well-structured, with each section adding value: examples, purpose, usage, return values, and error handling. The opening list of query phrases is somewhat redundant and could be trimmed, but overall the structure is logical and every sentence earns its place.

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

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

There is no output schema, so the description reasonably explains return values: verdicts, actual value with citation, reasoning, and specific error semantics. It also covers the behavior for both claim types and the meaning of each verdict, making the tool's expected behavior fully understandable to an agent.

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

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

The input schema already fully covers both parameters (claim and tolerance_pct) with descriptions, so the description adds no new parameter-level semantics. The description references 'exact percent-delta math' which indirectly relates to tolerance, but it does not supplement the schema's explanation. Schema coverage is 100%, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example queries ('is it true that…', 'fact check') and describes the exact role of checking whether a user's statement is factually correct, distinguishing it clearly from general Q&A tools like ask_pipeworx.

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

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

Explicit usage guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR fast path) and any other claims (grounded pipeline), and notes it replaces 4–6 sequential calls, giving a clear reason to prefer it.

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