Htmlentities

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

Annotations already establish read-only, idempotent behavior; the description adds important context about external API calls and billing ('you pay Anthropic directly'), the free default model, and the exact return payload. It stops short of disclosing rate limits or failure modes, but with annotations covering safety, this is substantial additional 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?

Three dense sentences front-load the core function, then default behavior, then output format and use cases. No redundant phrasing, every sentence contributes new 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?

Despite the lack of an output schema, the description specifies the per-model result shape and combined view, making the return contract explicit. It also covers default model, optional key material, and applicable scenarios, making the tool fully usable without additional documentation.

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 practical meaning: it identifies the free default model, clarifies that _apiKey enables Anthropic and direct billing, and gives representative entity examples. This goes beyond the schema to explain cost and default behavior.

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

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

The description opens with a specific verb ('Probe'), names the resource (LLMs), and defines the output (visibility score 0-100 per model). It clarifies the default model and optional Anthropic probe, distinguishing it from sibling data-retrieval tools like ask_pipeworx or recall.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and specifies when to include _apiKey for Anthropic. However, it does not explicitly define when not to use this tool or name alternatives like scan_competitor_ai_presence.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: routing across thousands of tools, filling arguments, returning structured answers with citation URIs, being a fast single call, and working across tiers. It also implies a lower hallucination-resistance than the grounded variant, without contradicting annotations.

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

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

The description is fairly long but front-loaded with a strong directive and organized into clear sections: scope, trigger phrases, examples, and escalation paths. Every section earns its place, though the trigger-phrase list and example list are slightly redundant with each other.

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

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

For a broad catch-all tool, the description covers what it does, how it returns data (structured with citation URIs), when to use alternatives, and even the breaking-news corner case. Despite lacking an output schema, the described return format is sufficient for an agent to know what to expect.

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

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

Schema description coverage is 100% and includes all six aliases with descriptions. The description goes beyond schema by offering concrete example questions that illustrate the expected natural-language input, though it does not add new parameter-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 states a clear verb-resource pair: routes a natural-language question to one of 5,743 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It differentiates itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research and contrasting with web search.

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

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

Provides explicit when-to-use conditions, including trigger phrases like 'what is', 'look up', and 'get the latest'. It declares this the default entry point, gives concrete examples, and specifies exactly when to step up to ask_pipeworx_grounded or deep_research, plus addresses breaking-news coverage.

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 by disclosing the experimental status, the fact that candidate routing improvements are enabled live when under test, the current absence of an active candidate, and that results are compared against the stable router. It also clarifies that this is a full working router with no fallback, which is valuable behavioral context. No contradiction with the readOnly/idempotent annotations.

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

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

The description is front-loaded with the core identity ('Beta version of ask_pipeworx: identical universal router') and every sentence contributes meaningful context about state, usage, or behavior. It is slightly longer than strictly necessary due to specific details like the retirement date, but there is no fluff.

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

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

Given the tool's simplicity (one question parameter) and the annotations covering safety and idempotency, the description provides sufficient context: current state, usage condition, and relationship to the stable router. The only gap is that the response shape is referenced as 'same response shape' rather than described, but this is acceptable given the explicit sibling reference.

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

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

Schema description coverage is 100%, so the schema already fully documents the single required 'question' parameter and its aliases. The description only says 'same arguments' in reference to ask_pipeworx, adding no new parameter-level semantics, which aligns with the baseline of 3 for high schema coverage.

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

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

The description states this is a beta version of ask_pipeworx, an identical universal router with the same 5,743 tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the experimental edge with candidate routing improvements. This clearly explains what the tool does and how it relates to a specific sibling.

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,' naming the alternative and the specific condition for choosing this tool. It does not explicitly state when not to use it, but the beta/experimental framing implies caution and the current no-active-candidate note provides clear context.

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

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

The description adds significant behavioral context beyond the annotations: it explains the extraction-only behavior, the exact success and failure response shapes, and the refusal reason enum. It also discloses the cost implication of one extra LLM call. This goes well beyond readOnlyHint and idempotentHint.

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

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

The description is dense but every sentence contributes: purpose, mechanism, output contract, use cases, and cost trade-off. It is front-loaded with the most important behavior and avoids fluff. The format is easily scannable for an agent.

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

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

Given there is no output schema, the description compensates by fully specifying both success and refusal response contracts. It also covers when to use, when not to use, cost implications, and failure modes. An agent has everything needed to decide and call this tool correctly.

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

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

Schema coverage is 100% and the schema already documents 'question' plus five aliases. The description does not add further parameter-level meaning, but that is acceptable because the schema carries the full burden. A baseline 3 is appropriate because the description adds no extra parameter guidance.

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

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

The description clearly identifies this as a 'Hallucination-resistant answer mode' that extracts answers only from tool results, with a specific return and refusal shape. It also distinguishes itself from ask_pipeworx by describing the extra extraction step. This is a specific verb+resource definition that an agent can act on.

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

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

Explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also gives the alternative and trade-off: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call. This is clear routing guidance.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond these by revealing resolver contracts (market_match_score, alternatives, suggestions), safety blockers (low_confidence_match, market_closed_or_inactive), wide-spread market warnings, cancellation-rule risk, and news fallback mechanics. This level of disclosure is exceptional and gives the agent deep insight into edge cases 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 long and dense, but it is meticulously structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that make it scannable. Each sentence adds concrete information, and there is no filler. However, the length might overwhelm an agent, and a slightly tighter summary of the resolver contract could improve readability. Still, for the tool's complexity, it earns a high score.

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

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

Even though there is no output schema, the description meticulously documents the response structure: result.market fields, analysis fields, evidence keyed by source, parent_event details, and status codes. It covers safety, cancellation rules, and edge cases like fallback attempts. Given the tool's complexity, the description is remarkably complete and self-contained, allowing the agent to invoke and interpret results correctly without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by explaining how the 'market' parameter accepts slug/URL/question text (already in schema) and elaborates on 'depth' with quick vs thorough fan-out behavior. For 'include_raw', it specifies when to use true (recompute deltas, cite observations) and the size implications. This added context pushes it above the schema-only baseline, though not to a 5 since the schema already does a good job.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the tool's scope and differentiates from siblings by describing the bet classification and fan-out behavior. It also includes explicit use cases ('should I bet on X', 'what does the data say about Y'), leaving no ambiguity about the tool's 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?

The description explicitly states when to use the tool with concrete query examples and provides a classifier list plus fan-out examples for various bet types (BTC, Fed, Hormuz, Yankees, etc.). It also gives negative guidance through safety notes (e.g., low-confidence matches block usage, closed markets return a specific status), helping the agent avoid misuse. It does not name alternative tools but clearly establishes the intended context.

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

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

Annotations already declare readOnly/openWorld/idempotent hints. The description adds substantial context: specific data pulled for company (10-K revenue, net income, cash, long-term debt) and drug (FAERS counts, FDA approvals, trial counts), off-calendar fiscal year handling, sorting by primary metric, and citation URI returns. 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 every sentence earns its place: usage triggers, preference instruction, data source details, fiscal year handling, sorting behavior, and return format. It is front-loaded with query examples and avoids filler.

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

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

Given two distinct modes (company/drug) and no output schema, the description covers key aspects: what data is pulled per mode, how results are ordered, and the return structure (paired data + citation URIs). This is sufficient for an agent to select and invoke the tool correctly, especially with sibling 'entity_profile' available for single lookups.

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?

Though schema coverage is 100%, the description enriches parameter semantics: it explains what each enum value ('company' vs 'drug') produces, gives example value formats (tickers/CIKs vs drug names), and clarifies the array count constraints (2–5). This goes far beyond the schema's basic type descriptions.

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

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

The description clearly identifies the tool as a side-by-side comparison engine for 2–5 companies or drugs, using explicit query patterns like "X vs Y" and "which is larger." It distinguishes itself from single-entity lookups (sibling tool 'entity_profile') by emphasizing parallel comparison and replacing sequential lookups.

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 states explicitly when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete example queries and contrasts with the alternative (sequential lookups), making the choice unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, which covers the safety profile. The description adds the behavioral attributes 'Keyless, offline' and clarifies the output is plain text, providing context beyond the annotations. It does not describe potential errors or edge cases, but for a simple transformation this is adequate.

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 one sentence, front-loaded with the action 'Decode', and contains no unnecessary words. Every piece of information (named versus numeric entities, keyless, offline) is meaningful and contributes to understanding.

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 required parameter, no output schema, and good annotation coverage, the description fully covers what the tool does, what input it expects, and its key behavioral characteristics. No additional return value explanation is needed since the transformation 'back to plain text' is self-explanatory.

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

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

The schema has 100% coverage for the single parameter 'text', with a description 'Text containing HTML entities.' The tool description adds value by giving concrete examples of entity formats (named like & and numeric like © / ©), which helps the agent understand the expected input beyond the schema's generic description.

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: decoding HTML entities (both named and numeric) back to plain text. It uses a specific verb 'decode' and identifies the resource (HTML entities). It is also distinct from the sibling tool encode_html, which performs the inverse operation.

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

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

The description provides clear usage context by noting 'Keyless, offline', indicating no authentication is required and the operation works offline. While it does not explicitly mention alternatives or exclusions, the context is sufficient for a simple utility tool. It lacks an explicit 'when not to use' statement, but it is implied that this is for decoding, not encoding.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses account requirements, parallel decomposition, the exact findings-packet shape, the never-invented gaps[] behavior, hop fields, resolvable citation_uri, contradictions scanning, semantic excerpting, and expected latency. This is far richer behavioral detail than the annotations provide.

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

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

The description is dense and front-loaded with the critical account caveat, and every clause earns its place given the tool's complexity. It could be slightly tightened or broken into structured sentences, but there is no genuine filler.

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

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

Even though there is no output schema, the description fully specifies what the findings packet contains—verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], hop, contradictions[]—plus runtime expectations and auth requirements. Nothing needed to invoke this tool correctly 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 schema already covers 100% of the parameters, including detailed enum meanings for depth and question format. The description reinforces that broad questions are acceptable and echoes the depth behavior, 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 states a specific verb ('research') and resource ('Pipeworx's 1500 STRUCTURED data sources'), and clearly distinguishes itself from open-web search and from the ask_pipeworx sibling. This lets an agent select it confidently without guessing.

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 names when NOT to use the tool: if not signed in, use ask_pipeworx; for a single lookup use ask_pipeworx; for breaking/current news prefer ask_pipeworx. It also names the ideal use case ('broad/multi-part questions over structured data'), leaving no ambiguity.

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 it read-only and idempotent. The description adds that results include full schemas and are directly callable, but doesn't disclose ranking, pagination, or rate limits—acceptable but not rich.

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

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

Three focused sentences; the domain list is useful but slightly dense. No wasted words, but could be tightened.

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 discovery tool, it explains the response contents and usage timing, but lacks explicit notes on response format. Overall adequate.

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

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

Schema covers 100% of parameters with descriptions and aliases; the description only restates the limit behavior ('top-N') without adding new semantic detail.

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

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

The description opens with a specific verb-resource pair ('Find tools') and enumerates supported domains, clearly distinguishing it from sibling tools that answer questions or search within specific datasets.

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

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

It explicitly states when to use ('Use when you need to browse, search...') and gives a priority directive ('Call this FIRST...'), though it doesn't name alternatives or exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral specifics beyond annotations: the exact characters escaped in each mode and the operational trait 'Keyless, offline'. This gives the agent a clear and complete picture of what the tool does.

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 wasted words. The first sentence immediately states the action, and the second sentence efficiently covers the modes. It is front-loaded and easy to parse.

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, side-effect-free utility with a complete schema, strong annotations, and no output schema, the description covers the core functionality, mode differences, and operational constraints (keyless, offline). It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already describes both parameters with 100% coverage, but the description enriches them further by explaining the 'basic' vs 'extended' modes and listing the exact characters each handles. This adds meaning that the schema alone does not convey.

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 and resource: 'Encode text to HTML entities'. It distinguishes itself from the sibling decode_html by focusing on encoding, and further distinguishes its two modes by explicating what each does.

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

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

The description provides usage context by noting 'Keyless, offline' and explains the choice between basic and extended modes, which helps decide how to invoke the tool. However, it does not explicitly compare with alternatives like decode_html or mention when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds significant behavioral context beyond these: patents API sunset with soft-fail behavior, sources_used/sources_failed indicating real data availability, fda_products absence for small-molecule/generic-only companies explained as expected, and private company handling with explicit notes. No contradiction with annotations; the description enhances transparency significantly.

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?

While long, the description is densely packed with high-value information and each sentence earns its place. It front-loads purpose with examples, then systematically enumerates sources and return fields with clear separators (semicolons, parentheticals), and ends with parameter details. It is well-structured and not wasteful; the complexity of the tool justifies the length.

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

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

Given the tool's high complexity (multiple sources, many return sections, no output schema), the description is remarkably complete. It details every return field (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed), explains edge cases (resolved:false, empty sections, patent soft-fail), and provides parameter handling guidance. There is nothing an agent needs to know that is missing.

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

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

Schema coverage is 100% for both parameters, providing baseline 3, but the description enriches meaning considerably: it gives concrete examples ('AAPL', '0000320193', 'Moderna'), explains name resolution via SEC EDGAR, clarifies that type accepts both values interchangeably, and details edge cases (private companies returning resolved:false). This goes well beyond the schema's enum and value descriptions, fully compensating for any ambiguity.

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

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

The description opens with concrete example queries and states exactly what the tool does: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the specific data sources (SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, GDELT/GNews, GLEIF) and return sections, making it unmistakable and distinct from sibling tools like deep_research or compare_entities. The explicit directive 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' distinguishes it from alternative approaches.

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 guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies usage edge cases: passing a ticker, CIK, or name; private companies returning resolved:false; patents soft-failing after sunset; and empty sections being 'real no-data, not a bug.' It implicitly signals when not to use it (for specific single-source queries) by contrasting with chained lookups.

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

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

The annotations already provide destructiveHint=true and idempotentHint=true, so the description's 'delete' action is consistent. It adds value by specifying use cases (stale context, done tasks, sensitive data) and the relationship with remember/recall, which goes 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, front-loaded with the core action followed by usage context. Every sentence earns its place with no redundancy or irrelevant information.

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

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

For a simple one-parameter delete tool with strong annotations and a clear schema, the description is fully complete. It covers the operation, when to use it, and how it relates to sibling tools, leaving no significant gaps.

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

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

The schema provides full coverage of the single 'key' parameter with a clear description ('Memory key to delete'). The tool description does not add additional parameter details, so a baseline score of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the specific verb 'Delete' and resource 'memory'. It distinguishes itself from siblings like remember and recall by focusing on the deletion operation.

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

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

The description explicitly lists scenarios for use: when context is stale, task is done, or clearing sensitive data. It also mentions pairing with remember and recall, providing context. However, it lacks explicit when-not-to-use guidance, so it doesn't fully meet the 5-point 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: "Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format," which explains the process and output beyond structured hints. It does not describe error handling or edge cases, but that is not critical for this simple 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 three sentences, front-loaded with the core purpose, and each sentence adds unique value (purpose, process, and use cases). No wasted words 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?

For a 2-parameter tool with no output schema and rich annotations, the description is complete: it specifies inputs (URL via fetching), outputs ("single text blob ready to drop at site-root/llms.txt"), and concrete use cases. It would be difficult to misuse this tool given the clarity provided.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds no new parameter semantics beyond what the schema already provides (URL and max_links). It mentions fetching the page, which implicitly relates to the URL, but does not elaborate on max_links behavior.

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

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

Purpose is crystal clear: "Generate a production-ready llms.txt file for any URL" with a specific verb, resource, and scope. It also distinguishes from siblings by focusing on llms.txt generation and mentions the standard format, making it unique among the listed tools.

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

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

The description explicitly lists use cases: "getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor." It does not mention when not to use or alternatives, so it misses the 'when-not' and 'alternatives' portion of a perfect score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by listing the exact returned fields (id, type, params, created_at, last_fired_at, fire_count), which is especially helpful since no output schema is provided. It also clarifies scope ('active subscriptions'), which aligns with the include_inactive parameter.

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 action and resource, and every sentence earns its place. It states the purpose, the return fields, and a practical usage hint without repetition or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete enough. It covers purpose, return fields, and usage context. Since no output schema exists, explaining the returned fields in the description is essential and well handled.

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

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

The schema has full coverage for the single optional parameter include_inactive, with a clear description in the schema itself. The tool description adds no explicit parameter semantics beyond mentioning 'active subscriptions', which indirectly relates to the parameter. With 100% schema coverage, 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 uses a specific verb, 'List', and names the resource, 'the caller's active subscriptions'. It clearly identifies what the tool does and distinguishes it from sibling tools like subscribe and unsubscribe, which perform different actions.

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

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

The description provides clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies alternatives (subscribe, unsubscribe) but does not explicitly name them or state when not to use. It gives practical usage guidance without explicit exclusion, so a 4 is appropriate.

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

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

Beyond annotations, it discloses rate limiting (5 per day), cost (free, no quota), and token mechanics (filing returns a claim_token, passing it back reads status). These are important behavioral traits not conveyed by the schema or annotations, and they don't contradict any 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?

Although the description is long, every sentence adds distinct, necessary information: purpose, use cases, exclusions, token mechanics, rate limits, and cost. It is structured logically from general to specific, with no filler.

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

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

Even without an output schema, the description explains that filing returns a claim_token and how to use it to read the outcome. It covers all parameters (including nested context), acknowledges no required parameters, and provides operational details like rate limits, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning about claim_token (how it is obtained and used) and instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts, which enriches parameter understanding beyond the schema.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx feedback). It also distinguishes itself from sibling tools by specifying that it only applies to tools served by this connection, not other MCP servers.

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

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

Explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies scope with 'ONLY for tools served by this Pipeworx connection'.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds significant non-obvious context: no PII, derived from CF analytics-engine, cached 5min-1h depending on window, and raw output shape (pack, tool, count). This goes well beyond the structured annotations.

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

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

Every sentence earns its place: definition, outputs, three distinct use cases, and data provenance/cache policy. The purpose is front-loaded, and the structure is tight with no filler.

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

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

Despite lacking an output schema, the description fully communicates return content (top tools, top packs, volume), data format (pack, tool, count), window options, and caching behavior. For a read-only, simple tool, this is 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 single parameter `window` is fully documented in the schema with enum values and semantic explanations. The description only repeats the window options without adding new syntax or format details, 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 opens with a concrete framing ('What other AI agents are calling...') and clearly lists outputs: top tools, top packs, and total call volume. This distinguishes it from siblings like discover_tools by focusing on aggregate usage signals rather than a catalog.

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?

Three explicit use cases are provided (hot data sources, canonical tool confirmation, alignment check), giving clear when-to-use context. However, it does not name alternative tools or state when not to use it, 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 readOnlyHint=true and idempotentHint=true, but the description goes far beyond by detailing the internal algorithms (partition_check, semantic anchor, Jaccard similarity), the fill check against live CLOB depth, and explicit warnings like 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' No contradictions.

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

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

The description is long but information-dense, with clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes unique value, and the structure makes complex behavior easy to navigate. 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?

Despite having no output schema, the description explicitly defines the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, etc.) and covers all modes, edge cases, and limitations. It is comprehensive enough for an agent to correctly invoke the tool and interpret results.

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

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

Schema coverage is 100%, but the description adds significant semantic value beyond the schema. It provides concrete examples for `event` ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), explains that full URLs are accepted, and clarifies what `topic` does (searches related events). The mode-specific behavior is richly described, making the parameters far more meaningful.

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.' This clearly states what the tool does and distinguishes it from siblings like polymarket_edges and polymarket_fill_risk, which focus on other aspects of Polymarket analysis.

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 each mode: no args for trending_scan, `event` for a specific market (recommended), and `topic` for cross-event scanning. It also names an alternative tool, polymarket_fill_risk, for custom sizing, and explains why cross-event mode catches patterns single-event misses.

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 readOnlyHint/idempotent annotations already signaling safe read-only behavior, the description adds extensive behavioral context: 1-hour KV-level caching, response segmentation, Kelly caps at 0.25, slippage handling, 24h-move warnings, and funnel diagnostics. This far exceeds what annotations alone provide.

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

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

The description is a single dense paragraph containing a high information density, but the lack of visual structure (no line breaks, heavy parentheticals) makes it harder to parse. Every sentence is informative, but the wording is verbose and includes internal references like 'Run 8' that could confuse an agent.

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 defines the response topology (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, 24h-move warning). It even explains why segments might be empty and how caching works, making it highly 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?

Although schema coverage is 100%, the description adds significant meaning beyond field names: it defines which parameters are 'tradeable-edge' filters, explains the surprising min_partition_leg_kelly behavior (parent-level Kelly is 0 for partition arbs), and gives rationale for slippage defaults. This deepens parameter understanding beyond the schema.

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

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

The first sentence precisely states what the tool does: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by tying the opportunity to Pipeworx data disagreement.

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 positions the tool as the daily discovery entry point ('what should I bet on today') and gives practical filter usage (tradeable-edge knobs). It does not explicitly name alternative sibling tools to use instead, but provides clear caveats such as the Fed signal unreliability note.

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. The description adds substantial behavioral context: snapshot writing on cache-miss, TTL limits, decay computed from daily closes, and semantics of expired opportunities and snapshot gaps. No contradiction.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS) and uses concise language. Every sentence conveys essential information; no filler.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), their semantics, and limitations (TTL, gaps). It also explains how to interpret decay numbers and the 'competition clock'.

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?

Both parameters are fully described in the schema with defaults and allowed values (100% coverage). The description only restates the defaults and adds no meaningful new semantics beyond the schema, 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 explicitly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and trend. It clearly distinguishes itself from sibling polymarket_edges by focusing on tracking edges over time rather than providing current edges.

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

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

It explains the use case as answering 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. However, it does not explicitly name alternatives or state when not to use this tool, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context. It explains that the tool walks the order-book ladder, computes top_of_book vs VWAP, returns a verdict (clean|degraded|cannot_fill), and details basket-mode outputs. It also discloses the risk of partial fills converting an arb into a directional position. No contradiction with annotations.

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

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

The description is long but densely packed with necessary information for a two-mode tool. It uses CAPS for mode labels, front-loads the core purpose, and every sentence contributes unique details about parameters, outputs, or usage timing. While not minimal, it is appropriately structured and free of 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?

With no output schema, the description carries full responsibility for explaining return values, and it does so comprehensively. It enumerates single-market fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) and basket-mode outputs (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It also covers prerequisites, parameter interpretation, and risk caveats, making it complete 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?

Although schema description coverage is 100%, the description enriches parameter understanding significantly. For example, it clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. It also explains the market/event requirement and the default auto behavior for side in basket mode, going beyond the schema's concise descriptions.

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

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

The description opens with a specific, action-oriented summary: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then distinguishes two modes (single-market and basket), lists concrete output fields, and clearly differentiates the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on 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?

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides a rationale citing theoretical overround not being capturable on thin books and partial basket fills creating unhedged directional risk, directly addressing when to use it vs alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description goes far beyond them: it discloses matching methodology, compatibility codes, fee treatment, skipped-leg counters, and null semantics for temporal_alignment. It also warns that spreads are gross and not necessarily tradeable, which is essential 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?

The description is long, but it is well-structured with visible labels like TWO MODES, RESPONSE, SAFETY FIELDS, Codes, and fees_note. Nearly every sentence carries non-obvious operational information; the length is justified by the tool's complexity, though it could be tightened without losing meaning.

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 carries the burden of explaining return values and edge cases. It covers leg prices, top_spreads_pp, compatibility codes, per-pair flags, skipped/unclassified results, temporal_alignment semantics, fee treatment, and caution about pre-mapped topics. An agent has detailed guidance for interpreting responses correctly.

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

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

The input schema already documents all three parameters with 100% description coverage, so the baseline is 3. The description adds real value by explaining how the parameters relate to the two modes, noting that explicit ticker/slug override the topic mapping, and clarifying that both modes use the identical matching logic.

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

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

The description opens with a precise statement of the tool's job: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It then distinguishes two usage modes, making the resource and scope unmistakable and differentiating it from generic single-venue or arbitrage tools.

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

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

The description explicitly defines TWO MODES and when each is appropriate: pre-mapped topic shortcuts versus explicit event ticker/slug pairing. It also warns that most pre-mapped topics currently return compatibility warnings, helping set expectations. It does not explicitly compare against sibling tools like polymarket_arbitrage, but the mode guidance is strong.

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

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted, providing context beyond annotations.

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

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

Three focused sentences, no fluff, with the core action first. Each sentence adds value: what it does, when to use, and how it relates to siblings.

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 single-parameter tool with no output schema, the description fully covers purpose, usage, scoping, and sibling relationships. No obvious gaps remain.

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

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

Schema covers the single key parameter fully with the omit-to-list behavior. The description adds contextual examples of keys (ticker, address, research notes), enriching the semantics 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 retrieves a value previously saved via remember or lists all saved keys. It distinguishes itself from siblings by explicitly naming remember and forget, making the resource and action 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 explicitly says when to use: 'Use to look up context the agent stored earlier' and mentions alternatives (remember to save, forget to delete). This provides clear guidance on appropriate usage and differentiates from related tools.

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

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

The annotations declare readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read,' which is a state-changing operation. This directly contradicts the read-only annotation, making the behavioral transparency score 1 per the contradiction rule.

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 tight three-sentence block that front-loads the main purpose and packs in filter options, mark_read semantics, polling guidance, and an alternative endpoint. Every sentence contributes distinct information 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?

With no output schema, the description fulfills the burden by mentioning the key return fields (source, citation_uri, raw payload). It also covers filtering, stateful reads, and polling. It does not explain pagination or limit behavior, but the schema covers limit, and the tool is relatively simple.

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

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

The schema already provides full descriptions for all 5 parameters (coverage 100%), so the baseline is 3. The description adds value by giving a concrete example for type ('sec_8k'), clarifying the effect of mark_read (only newer events on next call), and reinforcing the since parameter's ISO timestamp format.

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 'Pull fired events from your subscription feed,' which is a specific verb+resource statement that clearly distinguishes this tool from siblings like list_subscriptions. It also details the output contents (source, citation_uri, raw payload), making the purpose unambiguous.

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

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

The description provides clear context on how to use the tool: filter by type and since, set mark_read for stateful reads, and notes that polling is acceptable. It also mentions an alternative endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: fan-out to multiple sources, fallback logic (GDELT preferred, GNews when rate-limited or 5xx), PatentsView API sunset behavior, and soft-fail semantics. It also explains the return structure and citation URIs. 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 efficient; every sentence provides context—examples, data sources, fallbacks, parameter formats, return structure, and alternative tool. It is longer than a minimal description but well-structured and front-loaded with usage examples. Slight deduction for length, but no waste.

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 (multi-source, fallback, soft-fail), the description covers all necessary context: return output (changes[] grouped by source, total_changes, citation URIs), parameter syntax, source behavior, and when to use the sibling entity_profile. Since no output schema exists, the description adequately compensates.

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 thoroughly documents all three parameters with examples (e.g., 'since' accepts ISO date or relative shorthand with recommended '30d' or '1m'). The description adds little beyond providing query examples, so it earns the baseline 3 for high schema coverage without needing to compensate.

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

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

The description states a specific verb+resource+scope: 'change feed for a company in the last N days/weeks/months in ONE parallel call' and names the exact sources (SEC EDGAR, GDELT/GNews, USPTO). It clearly distinguishes from the sibling tool entity_profile by contrasting the dynamic change feed with a static profile.

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

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

The description provides explicit guidance on when to use this tool ('What's new with X', 'latest on Y', etc.) and gives an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also mentions the one-call efficiency benefit, which conveys when this tool is preferred.

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

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

Annotations indicate this is a write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds valuable behavioral context: key-value pairs are scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. It does not contradict annotations, though overwrite semantics are not explicitly 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 three sentences long, front-loaded with the core purpose, and every sentence provides useful information (when to use, persistence details, sibling pairing). No redundant or filler content.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage scenarios, persistence rules, scoping, and relationships with related tools. It is sufficiently complete for an agent to select and 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% with descriptions for both key and value, so the baseline is 3. The description adds meaning by framing the parameters as a key-value pair and explaining that the value stores findings, addresses, etc., which enriches the schema's minimal descriptions.

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

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

The description uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly distinguishing the tool from siblings by mentioning it pairs with recall and forget. It also provides concrete examples of what to save, further clarifying 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?

The description explicitly states when to use the tool ('Use when you discover something worth carrying forward') and names the alternatives recall and forget for retrieval and deletion. It also clarifies scoping and persistence conditions, giving the agent clear decision criteria.

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

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

The description discloses rich behavior beyond the annotations: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF or OpenFIGI is unavailable, returns 'figi_candidates' on ambiguous matches, labels each identifier with its source, and explicitly reports unresolved identifiers. These details go well beyond the readOnly/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-organized and front-loaded with purpose and examples. Every operational constraint (bond issuer naming, ambiguity behavior, graceful degradation) earns its place, though some repetition and density could be tightened without loss of clarity.

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

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

Even with no output schema, the description tells the agent what identifiers will come back, how ambiguity is handled, what 'unresolved' means, and what happens if enrichment sources fail. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the schema's value description is already detailed (e.g., bond issuer naming), so a baseline of 3 applies. The description adds extra semantic value by stating that ISIN is an accepted input and explaining how an ISIN resolves to the legal entity via GLEIF mapping, which is not in the schema.

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

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

The description opens with concrete query examples and a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It goes on to define exactly which identifier types are produced for 'company' and 'drug', making the tool's role unambiguous even among 30+ sibling tools.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' giving a clear condition for when to invoke the tool. It does not name sibling alternatives or explicitly state when not to use this tool (e.g., vs entity_profile), so it falls short of a full 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 cover safety (read-only, idempotent, non-destructive). The description adds behavioral detail beyond annotations by explaining it 'Probes each entity ... with ai_visibility_check, ranks by score' and returns a 'ranked list with score, confidence, signal density per entity'. This enriches understanding of internal mechanics and output. No contradiction.

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

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

The description is compact and front-loaded: two substantive sentences plus a brief illustrative query. Every sentence serves a purpose—function, process, use case, and output—without 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?

Given no output schema, the description adequately explains the return format ('ranked list with score, confidence, signal density per entity'), the process, and the intended use case. It is complete for an AI agent to understand when and how to invoke this tool.

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

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

Schema coverage is 100%, so all parameters are described. The description adds minimal extra value; the note about 'your brand + N competitors' aligns with the schema's 'first entry subject' but does not introduce new meaning. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Compare' and clearly identifies the resource as 'AI visibility across multiple entities side-by-side'. It distinguishes from siblings by explicitly referencing ai_visibility_check and mentioning ranking, making it clear this is a multi-entity composite tool unlike single-entity checkers.

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 clear context for use: 'competitive AI-marketing audits' with an example query. However, it does not explicitly name alternatives or exclusions (e.g., 'for a single entity, use ai_visibility_check instead'), 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond those: it fans out to two external services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timed-out sources. This goes well beyond the structured annotations and provides critical operational expectations.

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

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

The description is dense and front-loaded with the core purpose, followed by usage guidance, return fields, ecosystem limitation, and failure behavior. Every sentence provides distinct information, but it is a long single paragraph rather than a more scannable structure, so it loses one point for conciseness.

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

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

Despite having no output schema, the description enumerates the returned summary fields, per-advisory details, links, and recent alternative versions. It also covers performance caveats, partial failure behavior, and ecosystem boundaries. This is comprehensive for an agent to decide when to use the tool and what to expect from the response.

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

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

Schema description coverage is 100%, so both parameters ('package' and 'version') are fully documented in the input schema. The description does not add new parameter-specific meaning; it mentions the ecosystem and default behavior, but those are already in the schema. With high schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Composite 'should I add this npm package to my project' check in ONE call' and identifies the specific data sources (deps.dev for license/advisories/version history, bundlephobia for bundle size/dependency count/ESM support). It names the resource (npm package) and verb (scan/check), and distinguishes itself from sibling tools by being a specialized dependency evaluation tool with no direct overlap.

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 trigger conditions: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states an explicit exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This satisfies the when-to-use and when-not-to-use requirements.

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, idempotentHint, etc.), the description discloses the underlying algorithm (BGE-base-en embeddings, cosine similarity), the chunking strategy (500-char overlapping windows), the 200K char cap with truncation flag, and the return structure (offsets and scores). This rich behavioral detail helps the agent predict outcomes without invoking 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 five sentences, each with distinct value: core action, use case, companion tool, mechanics, and constraints. It is front-loaded with the primary purpose and maintains density without fluff, earning every sentence.

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 explains the return format (top-N passages, character offsets, similarity scores) and operational constraints (embedding model, window size, character cap). It provides enough context for an agent to select and invoke the tool correctly, including how to verify quotes and integrate with ask_pipeworx_grounded.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context like 'text you already pulled' and 'top-N passages' but does not provide new syntax or format details beyond what the schema already documents. It reinforces but does not materially extend parameter understanding.

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

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

The description states 'Semantic search INSIDE a fetched record' with a specific verb and resource, clearly distinguishing it from sibling tools that fetch or retrieve data. It emphasizes searching within already-retrieved text and specifies return values (top-N passages, offsets, scores), 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 explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, naming an alternative workflow. This gives clear when-to-use and complementary tool guidance, going beyond mere implication.

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, the description discloses substantial behavioral details: the always-on feed channel, optional email/sms/webhook delivery with verification requirements, a 10/day SMS cap, one-time webhook signing secret, HMAC signature verification, and auto-disable after 10 consecutive failing runs. This far exceeds what annotations already provide.

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

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

The description is front-loaded with the core purpose, then logically organizes prerequisites, supported types, and delivery channels. It is dense but each sentence carries necessary information; the length is justified by the tool's complexity and there is no filler.

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

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

Given the tool's nested objects, multiple subscription types, and no output schema, the description is remarkably complete. It tells the agent what is returned (subscription id), how to authenticate, what delivery options exist, and even failure semantics. No critical usage aspect is left unexplained.

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

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

Although the schema has 100% parameter coverage, the description enriches each parameter with practical semantics: per-type params examples (e.g., items:['5.02'] for sec_8k, {topic:'fed'} for polymarket_edge), delivery channel constraints (verified phone, standard email pattern, HTTPS-only webhook), and failure behavior. This adds significant meaning beyond the schema fields.

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 action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the verb, resource, and output, and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides strong usage context by enumerating supported subscription types with concrete examples and specifying the critical prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'). It does not explicitly name alternative tools for when not to use this tool, but the context is clear enough for an agent to decide.

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

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

Beyond the readOnly/idempotent annotations, the description explains it draws from a live catalog of thousands of tools, returns category-bucketed example questions with the exact tool and argument shape, and supports a topic focus. This gives substantial context about the tool's behavior and output beyond what annotations provide.

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

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

The description is longer than average but every sentence adds value: it lists example prompts, states the purpose, describes the output, and gives usage guidance. It front-loads the user intent and is well-structured, though slightly verbose due to the introductory prompt examples.

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

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

With no output schema, the description fully explains return values: category-bucketed example questions across listed domains, each with the tool and argument shape. It also covers parameter behavior and the onboarding use case, making it complete for a simple read-only tool.

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

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

Schema coverage is 100%, so the parameter is fully documented. The description adds meaningful use context by explaining 'Call with no arguments for the full spread, or pass topic to focus' and provides examples ('finance', 'pharma', 'betting'), clarifying the default and filtering behavior.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions, and distinguishes itself from meta-tools like ask_pipeworx, entity_profile, and compare_entities. It uses a specific verb ('suggest questions') and identifies the resource (Pipeworx capabilities).

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' It also shows example prompts that trigger the tool and notes the optional topic parameter, giving clear when-to-use guidance and naming 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 beyond the annotations by disclosing that ownership is enforced and that cancellation deactivates rather than deletes, with historical events remaining available via recent_alerts. This adds meaningful behavioral context that the structured annotations alone do not convey, without contradicting any annotation.

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, each providing essential information: the action, the ownership constraint, and the behavioral outcome. It is front-loaded with the core verb and resource, and every sentence earns its place with no redundancy or fluff.

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

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

For a simple single-parameter tool with rich annotations and a clear schema, the description covers the key aspects: the operation, ownership, side effects, and data retention. It even connects to a sibling tool (recent_alerts) for follow-up context. No output schema is needed for this simple cancel action, and the description fully equips an agent to use it correctly.

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

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

The schema already documents the only parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'), so schema coverage is 100%. The description reinforces this by referencing 'by id' but adds no new parameter-specific meaning beyond the schema, making the baseline score of 3 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 'Cancel a subscription by id' with a clear verb and resource, distinguishing it from siblings like subscribe and list_subscriptions. The added detail about deactivation (not deletion) further clarifies the exact nature of the operation.

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

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

It clearly communicates when to use the tool: to cancel a subscription you own, with an explicit ownership constraint. It also sets expectations by noting the row is deactivated rather than deleted, which guides appropriate use. However, it does not explicitly name alternative tools or specify when not to use it, so a small gap remains.

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 and idempotentHint annotations, the description adds critical behavioral detail: the distinction between 'could_not_verify' (meaning the check didn't happen and must not be treated as evidence) and 'unsupported' (no source covers it). It also discloses the routing logic to SEC EDGAR/XBRL vs. grounded pipeline and the return structure (verdict, actual value, citation, reasoning). This is exactly the kind of transparency needed for correct invocation.

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 densely informative but well-structured: examples → purpose → routing → output → caller warnings → efficiency note. Every sentence adds value, and the key 'IMPORTANT for callers' caveat is clearly flagged. Despite its length, it avoids redundancy and remains 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?

With no output schema, the description fully enumerates the possible verdicts and explains the error case ('could_not_verify' with verification_error). It also covers the two main input paths, mentions citations, and clarifies unsupported. For a tool with this complexity, the description provides complete operational context, 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?

Schema coverage is 100% with both parameters fully described. The description echoes the schema's explanation of tolerance_pct ('Overrides the tolerance implied by the claim wording') and adds context about 'exact percent-delta math,' but this is marginal. It does not introduce new parameter-level meaning beyond what the schema already provides, so a 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 natural-language phrasings ('Is it true that…', 'fact check') and states clearly that the tool performs 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by detailing the SEC EDGAR + XBRL fast path for financial claims and the grounded pipeline for all other claims, making it unique among the sibling tools.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also notes that it 'replaces 4–6 sequential calls,' signaling that it should be chosen over chaining multiple simpler tools. Internal routing rules (company-financial vs. other claims) further guide when specific paths are taken.

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