Snb Ch

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

Annotations already declare read-only, idempotent, open-world, and non-destructive, so the bar for adding value is lower. The description meaningfully adds that the default model is free, that using Anthropic requires a BYO key and direct payment, and that it returns per-model score/confidence/signals/raw_response plus a combined view. This enriches the agent's understanding of cost and external behavior.

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

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

Three sentences with no redundancy: the first states the action and output, the second covers configuration and cost, the third outlines return structure and use cases. Every sentence earns its place, and the most important information is front-loaded.

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

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

There is no output schema, so the description's explicit mention of per-model {score, confidence, signals, raw_response} + combined view fills that gap. It also covers configuration (default, models, key) and use cases. It could go deeper on how visibility is scored or what 'signals' means, but for an agent seeking to select and invoke the tool, the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by linking `_apiKey` to the 'anthropic' model (the schema merely says 'optional Anthropic API key') and clarifying that omitting models defaults to workers-ai. This contextual relationship is not obvious from the schema alone.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs'), with clear scope ('business / brand / product / topic') and a measurable output ('score visibility (0-100) per model'). It effectively distinguishes itself from sibling tools by emphasizing visibility scoring rather than Q&A or research, and the 'Useful for' list further clarifies its niche.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model vs. the optional Anthropic key with cost implications. However, it does not explicitly name alternative tools or state 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it fills arguments automatically, returns a structured answer, always returns citations, emits stable pipeworx:// citation URIs, and may route to web search when appropriate. It stops short of describing failure modes or exact answer formatting, but the behavior is well disclosed.

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

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

The description is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and organized into clear usage and exclusion sections. It is longer than necessary and contains some jargon and abrupt transitions ('vibe-coded synthetics', the inserted 'START HERE' note), which prevents a perfect score.

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

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

For a complex meta-router with no output schema, the description is remarkably complete: it defines scope, domain coverage, trigger phrases, concrete examples, exclusions, alternatives, and return guarantees (structured answer with citations). An agent has enough context to decide when to invoke it and what to expect back.

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 all six parameters are aliases of 'question', so the schema fully documents the parameter surface. The description adds natural-language usage examples and trigger phrases but does not introduce new parameter-level semantics beyond what the schema already provides.

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

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

The description clearly identifies the tool as a router for factual, current, and historical data questions, with a specific verb ('Routes') and a concrete resource: 5,798 tools across 1,517 verified sources. It also explicitly distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell them apart.

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

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

Usage guidance is explicit and thorough: prefer over web search, use for defined example triggers ('what is', 'look up', 'get the latest'), and avoid for abstract/analysis, synthetic, or endpoint-specific questions. It names specific alternatives (ask_pipeworx_grounded, deep_research) for particular cases, leaving little to inference.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description adds beta status, the fact that no candidate routing improvement is currently active, and a clear 'falls back to nothing' guarantee that this is a complete working router rather than a stub. It also states the response shape matches ask_pipeworx. No contradiction with annotations.

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

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

The description is dense but purposeful, front-loading the beta/universal-router identity before explaining the live-testing context and current equivalence. The date and candidate-retirement detail are useful context, though the text is slightly longer than strictly necessary.

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 one-question-parameter tool with safety annotations already covering side effects, the description covers the key facts: identity, relationship to the stable router, current state, and the guarantee that it fully works. The only minor gap is that it defers the response shape to ask_pipeworx rather than describing it, which is acceptable given the sibling tool is present.

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 all six parameters documented as aliases for the required `question`, so the schema already carries full parameter meaning. The description adds no parameter-level detail beyond saying arguments match ask_pipeworx, which is unnecessary for calling it correctly.

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

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

The description opens by naming the tool as the beta counterpart of ask_pipeworx and states it is an identical universal router over 5,798 tools with the same arguments and response shape. This clearly distinguishes it from the stable ask_pipeworx sibling and frames it as the experimental routing edge.

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

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

It gives an explicit trigger: use exactly like ask_pipeworx when you want the newest routing, and notes results are compared with the stable router to decide merges. It also says no candidate is active so the behavior currently matches ask_pipeworx exactly. It does not provide when-not-to-use guidance or mention ask_pipeworx_grounded, so it falls just 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 mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: exact success/refusal response shapes, the full list of refusal reasons, grounding in verbatim evidence, and the fact that it costs an extra LLM call. No contradictions with annotations.

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

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

The description is dense and front-loaded with the most important differentiator, and it packs a lot of useful detail into a compact space. It is slightly lengthy but every major sentence contributes value, including the refusal reasons and usage guidance.

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 the return shape with explicit fields and possible refusal reasons, covers when to use it, and notes the cost trade-off. For a grounded question-answering tool, this is enough for an agent to select and call it correctly in 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?

The input schema is fully documented with the 'question' parameter and all its aliases, so the description does not need to add parameter details. The description focuses on behavior rather than parameter meaning, which is acceptable given 100% 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 identifies this as a hallucination-resistant grounded answer mode, distinct from the plain ask_pipeworx tool. It states the core behavior: pick a tool, fetch data, and extract answers only from the tool result, which makes the purpose immediately recognizable.

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 tells the agent when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative (ask_pipeworx) and gives a clear preference rule for casual lookups, including the extra LLM call cost trade-off.

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

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

Despite safe-read annotations (readOnlyHint=true, destructiveHint=false), the description goes far beyond them, disclosing fan-out patterns, response shapes, resolver contracts, safety short-circuiting, closed-market handling, wide-spread warnings, and cancellation-rule risks. It adds rich behavioral context that is essential for safe and correct use, with 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 densely packed with operational details. It is front-loaded with a clear purpose sentence and organized into labeled sections (CLASSIFIERS, FAN-OUT, RESPONSE, SAFETY, etc.), making it navigable. While some sentences could be trimmed, the length is justified given the tool's complexity and the critical safety information conveyed.

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 thoroughly documents return shapes: result.market fields, result.analysis fields, result.evidence keying, resolver contract (market_match_confidence, score, alternatives, suggestions), parent_event extractor, news fallback fields, and statuses for low-confidence and closed markets. It is complete for an AI 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 description coverage is 100% (3 parameters, all documented). The description adds meaning beyond the schema, particularly for the 'market' parameter by explaining how slug/URL/question text are resolved and that this drives category-specific fan-outs. It also gives examples that illustrate the parameter syntax, adding value over the bare 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 verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (Polymarket bet research with market-vs-model comparison) and provides concrete examples, making its purpose unmistakable and distinct from siblings.

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

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

Explicitly gives use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly indicates when to use the tool. It does not explicitly name alternatives or exclusions, but the context is clear and the examples cover common scenarios, 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 the readOnly/idempotent annotations, the description discloses significant behavioral details: pulls from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This adds valuable context not available in annotations.

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

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

The description is dense but every sentence adds value: trigger phrases, usage rule, data sources, metrics, sorting, output. Slightly longer than necessary but well-structured and front-loaded with 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?

Despite no output schema, the description fully informs the agent about input, behavior, and output expectations. It covers data source nuances (fiscal calendar), sorting logic, and result format, making it highly complete for a comparison tool.

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

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

Schema coverage is 100% with enum and array constraints, so the baseline is 3. The description enriches parameter meaning by giving concrete examples for companies (tickers/CIKs) and drugs (names), and explains what data each type pulls, which goes 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 performs side-by-side comparison of 2–5 companies or drugs, using specific verbs like 'compare', 'rank', 'head to head'. It distinguishes itself from sequential lookups and provides concrete example phrases.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive on when to use this tool versus the alternative of multiple lookups. It also lists trigger examples and explains the two entity types.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the default cube ID (devkua), the list of verified-live IDs, and what each ID represents. It does not describe return format, but given the simple tool and no output schema, the added context is valuable.

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

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

The description is four sentences, all purposeful: purpose, usage, verified IDs, and default. It is front-loaded with the core action and immediately clarifies value. No redundant phrasing or padding.

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

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

For a tool with one optional parameter, no output schema, and rich annotations, the description provides complete context: what it does, when to use it, what inputs are valid, and the default. The mention of 'dimension items / series keys' hints at the response nature, making it adequately comprehensive.

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

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

Schema coverage is 100% with a description and examples for cubeId. The description enriches this by explaining what each cube ID means (e.g., devkua = foreign exchange rates, zimoma = money market), which is not present in the schema. This helps the agent select appropriate parameter values.

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

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

The description starts with a specific verb ('Fetch') and resource ('Swiss National Bank cube's dimensions/structure'), and clarifies with parenthetical detail ('dimension items / series keys'). It explicitly contrasts with sibling get_cube by stating 'Use this to understand what a cube contains before/after calling get_cube', clearly distinguishing its role.

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

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

The description gives explicit usage context: use it before/after get_cube. It also provides a list of verified-live cube IDs with meanings, which guides the agent on valid inputs and when to apply each. No alternative is named, but the relationship to get_cube is sufficient.

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/openWorld/idempotent annotations, the description discloses auth requirements, paid tier, latency, gaps never invented, contradictions scan, stable fetchable citations, and semantic excerpting. 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?

After a genuinely front-loaded core, the description degenerates into an enormous repeated self-referential block saying the text seems garbled. This tail is hundreds of repetitions and provides no value, violating every-sentence-earns-its-place.

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

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

For a tool with no output schema, it fully explains result contents, behaviors, source scope, auth, cost, and expected latency. Nothing an agent needs to decide whether to invoke it and what to expect is missing.

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

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

The input schema already documents both parameters thoroughly, including depth semantics and the paid nature of thorough. The description adds latency expectations but little new parameter-level meaning, so the 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 states a specific operation: grounded multi-source research across Pipeworx's 1517 structured data sources in one call, with facet decomposition and parallel routing. It also distinguishes itself from siblings by saying this is NOT open-web search and by routing single lookups to ask_pipeworx.

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

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

It explicitly says to use ask_pipeworx when not signed in or for a single lookup, and says deep_research is best for broad/multi-part questions over structured data. This gives an agent clear decision rules with named 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing the return format (top-N tools with names, descriptions, full input schemas, curated examples) and the convenience of being 'ready to call directly, no second schema lookup needed' — useful context beyond annotations.

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

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

The description is three sentences and front-loaded with the core purpose. The second sentence lists many domains, which is informative but a bit long; however, it earns its place by clarifying scope. 'Call this FIRST' is a concise actionable guideline. Overall efficient with minimal 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 no output schema, the description sufficiently explains return values (names, descriptions, schemas, examples) and the 'no second lookup' benefit. It covers purpose, context, and usage guidance well. Minor gaps like result ordering or pagination are not critical for a discovery tool with safe annotations.

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

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

The input schema is very complete (100% coverage) with descriptions for query and its aliases (q, task, search, description) plus limit. The tool description adds little beyond 'describing the data or task' and 'top-N', which the schema already conveys. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description opens with 'Find tools by describing the data or task' — a specific verb and resource that clearly states the tool's meta-purpose. It distinguishes itself from sibling tools by positioning itself as a discovery/exploration layer over the actual task tools, listing many domain examples to clarify scope.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies you would not use this when you already know the exact tool, though it doesn't explicitly name 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 mark this read-only/idempotent/non-destructive, but the description adds substantial behavioral context beyond that: it fans out across multiple data sources, portions may soft-fail (USPTO patents sunset), empty sections are legitimate "no data" rather than failures, and sources_used/sources_failed reveal which sources worked. It also discloses that name resolution goes through SEC EDGAR and that a private company yields resolved:false instead of a bare error—exactly the kind of behavior an agent needs to interpret results correctly.

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 deliberately dense, front-loading the purpose and trigger examples before detailing output sections and edge cases. Every sentence adds value—the source fan-out, soft-fail note, empty-section expectation, and input-shape flexibility are all actionable. It is slightly longer than necessary for a single-purpose tool, but the complexity of the operation 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?

For a tool with no output schema and a complex multi-source operation, this description is remarkably complete. It covers input variants, output sections with formats (e.g., up to 5 recent_filings with URIs), failure semantics (patents soft-fail, private company behavior), and how to interpret empty sections. An agent selecting and invoking this tool has everything it needs to set expectations and parse the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that value can be a ticker, zero-padded CIK, or company name, that names resolve via SEC EDGAR, and that type and ticker are interchangeable and behave identically. This goes beyond the schema's descriptions by clarifying behavioral equivalence and edge cases, so a 4 is warranted.

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

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

The description states a specific verb+resource: "full cross-source profile of a US public company" and distinguishes itself from chainable single-pack lookups with "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups." It also enumerates concrete user phrasings ("Tell me about X", "research Acme", "brief me on Tesla"), leaving no ambiguity about what the tool does. It stands apart from siblings like resolve_entity or deep_research by scope and output.

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 to prefer this tool over single-pack lookups when the user asks for a holistic view, and it gives exact trigger examples. It also clarifies edge-case usage: private companies return resolved:false with a notes line, and the type field accepts company/ticker interchangeably. This gives the agent clear when-to-use and when-not-to-use guidance without naming alternatives aloud.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds some context about clearing 'sensitive data' and pairing with memory tools, but does not add significant behavioral details beyond what annotations convey.

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

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

The description is concise, with the main action front-loaded in the first sentence. The second sentence adds usage context efficiently without redundancy.

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

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

For a simple one-parameter delete tool with annotations covering destructiveness and idempotency, the description provides enough context for an agent to select and invoke it correctly. It includes when to use and related tools, making the description complete.

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

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

Schema description coverage is 100%, and the parameter description 'Memory key to delete' is clear. The tool description reinforces the 'key' parameter but does not add additional meaning or syntax beyond the schema.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' This is a specific verb+resource combination and distinguishes the tool from siblings like 'remember' and 'recall' by indicating a destructive delete 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 context on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also pairs with 'remember and recall,' but does not explicitly mention when not to use it or name alternatives beyond these siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool fetches the page and extracts specific elements, plus the output format (standard llms.txt markdown). It explicitly states the output is a single text blob, which is helpful.

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 purpose and process, followed by practical use cases. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description explains the output as a single text blob and clarifies where to deploy it. Combined with the annotations and parameter schema, the tool is fully understandable.

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%; both url and max_links are described with meaningful descriptions. The description does not add parameter-specific details beyond the schema, which is acceptable given 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 clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb (generate) and resource (llms.txt file). It distinguishes itself by describing the process (fetches, extracts, emits) and names the target AI crawlers (ChatGPT, Claude, Perplexity).

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, drafting for one's own project, or auditing a competitor. It does not name alternative sibling tools, but the scenarios give clear context for when 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), the description discloses that cube discovery is limited to a set of verified-live IDs and provides the exact list and default, which are crucial for correct invocation. 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?

Two sentences, front-loaded with the action and output type. The ID mapping is compact and efficient, with 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?

For a single-parameter tool with no output schema and strong annotations, the description fully covers what the agent needs: purpose, valid inputs, default, and output format. Nested or complex behavior is absent.

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 has a description for cubeId, and the tool description enriches this by mapping each known ID to its semantic meaning (e.g., devkua = FX rates). This goes beyond the schema's basic example list.

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 'Fetch' as a specific verb and identifies the resource as 'Swiss National Bank statistical data cube's time series'. It distinguishes from sibling cube_structure by focusing on time series data, not structure.

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

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

Provides clear context by listing four valid cube IDs and their meanings, and states the default. However, it does not explicitly mention when to use this vs alternatives like cube_structure, so no explicit exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the notion of 'active' subscriptions, which is beyond the annotation metadata.

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 main purpose and return fields, followed by a concise usage tip. Every word contributes value and there is no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It states the scope (caller's subscriptions), the return fields, and provides context for when to use it relative to adding or cancelling subscriptions. No significant information 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 description coverage is 100%, so the single parameter include_inactive is fully documented in the schema. The tool description does not mention the parameter or add additional semantics, so it stays at the baseline of 3.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also enumerates the returned fields, and the usage note about finding an id to cancel implicitly distinguishes it from subscribe/unsubscribe 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 provides explicit use cases: review existing subscriptions before adding more, or find an id to cancel. It does not mention explicit alternatives or when-not-to-use, but the context is clear enough to guide tool selection.

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

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

Despite annotations already indicating non-readonly and non-idempotent behavior, the description adds substantial context: returns a claim_token for anonymous filing, rate limit of 5 per identifier per day, free/no quota impact, team reads digests daily, and roadmap influence. 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?

Although the description is long, every sentence earns its place: purpose, usage triggers, exclusions, claim_token flow, rate limits, and quota status. It is front-loaded with the purpose and immediately gives actionable guidance.

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 four parameters, a nested context object, no output schema, and no required params, the description covers all essential operational aspects: what counts as valid feedback, how to file anonymously, how to retrieve status later, and practical constraints (rate limit, quota). It is fully self-contained 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?

Schema coverage is 100%, so baseline is 3, but the description goes beyond schema by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which directly enriches message/context 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all sibling research/discovery tools and explicitly enumerates feedback types (bug, feature/data_gap, praise).

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 triggers ('wrong/stale data', 'tool you wish existed', 'worked surprisingly well') and an explicit exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). Also clarifies how to identify Pipeworx tools and how to use claim_token for follow-up.

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 (read-only, open-world, idempotent), the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, excludes PII, returns only (pack, tool, count), and caches for 5min-1h depending on window. This enriches the agent's understanding of data freshness and privacy 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 well-structured and front-loaded with the purpose, followed by a numbered list of use cases and a concise note on aggregation and caching. No unnecessary filler, though it could be slightly tighter.

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 explains the return categories (top tools, top packs, total call volume) and the data format (pack, tool, count). It also covers caching and data source, making it complete enough 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?

Schema coverage is 100% with a descriptive enum for 'window' explaining the default and trade-offs. The description mentions the window values but adds no new meaning beyond what the schema already provides, so it meets the baseline without going further.

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 'What other AI agents are calling on Pipeworx right now' and explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window.' This clearly identifies the verb (returns), resource (Pipeworx trending), and unique scope (other agents' usage), distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. This provides clear 'when to use' guidance, though it does not explicitly mention when *not* to use it or name 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?

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations providing baseline safety, the description adds significant behavioral depth. It warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it,' and explains the partition filter's placeholder handling that can return null. These are non-obvious traits that impact decision-making, going well beyond the annotations.

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

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

The description is long but every sentence carries essential information, organized with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and separate mode explanations. It is front-loaded with the core purpose and then details edge cases and response formats. No filler or redundancy exists; each part earns its place given the tool's complexity.

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

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

With no output schema, the description fully specifies the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{...}' for event mode. It also covers failure modes, fill-check behavior, and relationship to another tool. For a tool with two optional parameters and multiple modes, this is complete and self-sufficient.

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

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

While the schema already covers both parameters with descriptions, the tool description greatly enriches them. It provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted for event, and explains the behavioral differences between event and topic modes. This adds meaning beyond the schema, making parameter choice intuitive.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly states the tool's function and methodology, and distinguishes between three modes (trending scan, event, topic) without confusing the reader. This is far more specific than the generic title and effectively sets it apart from sibling tools.

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

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

The description gives explicit usage instructions: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for a related but distinct need: 'For custom sizing use polymarket_fill_risk.' This provides clear context for when to use this tool and when to defer to another.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), edge calculation details ('edge_pp_net (after slippage)'), the 24h-move warning, the diagnostics funnel counters, and the special Kelly handling for partition overrounds. This far exceeds 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 a single, extremely dense paragraph without any bullet points or section breaks. While every sentence carries relevant information, the lack of structure makes it harder to parse. It is appropriately sized for the tool's complexity but poorly organized, earning a 3.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the logic behind each model segment. It also covers caching and why certain segments might be empty. This is complete for a complex 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?

The input schema already documents all 9 parameters at 100% coverage. The description adds inter-parameter context that the schema cannot convey, such as the relationship between min_kelly and min_partition_leg_kelly (partition arbs ignore min_kelly), and the fact that slippage_pp is subtracted before ranking. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage (likely for cross-market arbitrage) and polymarket_edge_tracker (likely for tracking edges over time).

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 the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also mentions nuances like Fed bets being excluded from ranking. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it misses the exclusion criteria for 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 read-only, open-world, idempotent, and non-destructive. The description adds significant context beyond these: snapshot TTL limits, cache-miss behavior causing gaps, signed edge_pp_net semantics, and decay computation methodology. This fully discloses behavioral traits and edge cases.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. Every sentence carries useful information, though it could be slightly more compact without losing value.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates), including edge cases like data gaps and TTL. It also covers limitations and methodology, making it complete for an agent to invoke and interpret results 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% for both parameters. The description adds context about 'window' being a snapshot family and clarifies the meaning of the signed value, which helps the agent understand parameter semantics beyond the schema. While not strictly necessary, it enhances 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 clearly states the tool's function: tracking edge persistence and decay over time using daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from sibling tools like polymarket_edges by focusing on telemetry rather than edge computation.

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

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

The description implies when to use the tool by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), giving a clear use case. However, it does not explicitly name alternatives or state when not to use it, though the sibling context makes the differentiation clear.

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

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

Annotations already declare readOnly/idempotent/destructive hints, and the description adds substantial behavioral context: it walks the order-book ladder, returns specificity like top_of_book/vwap_fill_price, and warns about partial fills converting arb into directional exposure. 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?

Though long, the description is tightly structured with purpose, a REQUIRES clause, distinct SINGLE-MARKET and BASKET sections, and a usage callout. Every sentence adds operational value; no filler or redundancy.

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

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

For a complex tool with no output schema, the description enumerates all critical return fields for both modes, including risk outputs like thin_legs[] and forced_directional_risk. It covers prerequisites, mode semantics, and failure modes, making it essentially self-sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, and the description adds mode-specific semantics beyond the schema: size_usd is 'max spend' for buys vs 'target proceeds' for sells, and for basket mode it means settlement notional S (shares per leg). It also documents the default 1000 and clamp range, significantly enriching the parameters.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check, and it details both single-market and basket modes.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and provides the reasoning (theoretical overround not capturable, partial basket fills create unhedged directional risk). This gives concrete triggers and contrasts with 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, openWorldHint, idempotentHint, and non-destructive, and the description goes far beyond that: it discloses that spreads are gross (Kalshi fees not modeled), that null temporal_alignment means 'could not be computed' not 'aligned,' that unknown metric_type/match_subtype legs are never paired, and that pairing is keyword/word-overlap based (pairing_unverified). This is exactly the non-obvious behavioral context an agent needs beyond the structured hints.

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

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

The description is front-loaded with a clear purpose and every sentence carries substantive information, so it is not padded. However, it is a very dense, single block of text with heavy capitalization and parentheticals that could be structured more readably with bullets or paragraph breaks. Given the complexity of the tool, the length is somewhat justified, but readability suffers enough to prevent a 4 or 5.

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

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

There is no output schema, so the description must fully explain return values, and it does: response shape (per-leg prices and top_spreads_pp with Kalshi − Polymarket direction), safety fields, compatibility codes, per-entry flags, skipped-unclassified counters, temporal alignment object, and the fees caveat. It even covers edge cases like null alignment and unknown metrics, so nothing critical appears missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it enumerates all 10 topic values explicitly, explains that explicit tickers override the topic-mapped side, and clarifies that both modes produce identical disclosures and matching logic. This enriches the schema's field-level comments, meriting a 4 rather than a baseline 3.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates this from sibling tools like polymarket_arbitrage by focusing on same-question spread and then details two modes (topic shortcuts and explicit tickers), so an agent can tell exactly what the tool does without opening the schema.

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

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

The description gives clear context for when to use each mode: pre-mapped topics for known macro questions, explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and notes both run the same matcher. It also provides practical when-not guidance, warning that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable.' It stops short of explicitly naming sibling alternatives such as polymarket_arbitrage for other spread scenarios, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations, such as scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieval/list-all behavior.

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

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

Three sentences, all informative with no redundancy. Front-loaded with the action verb 'Retrieve' and flows logically from action to usage to scoping to companion tools.

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

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

With no output schema, the description clarifies both usage modes: retrieving with a key and listing all keys by omitting it. Scoping and relationships to remember/forget provide complete operational context for this 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%, and the description reinforces the optional key semantics by saying 'omit the key argument' to list all. It adds meaningful examples of keys (target ticker, address, prior research notes) that go beyond the schema's minimal property 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?

Description opens with 'Retrieve a value previously saved via remember' — a specific verb and resource. It also covers the alternate use case of listing all saved keys, which clearly distinguishes it from sibling tools like remember and forget.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companion tools and their roles: 'Pair with remember to save, forget to delete,' providing clear alternative paths.

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 describes a mutation side effect with mark_read:true, but annotations declare readOnlyHint=true. This is an annotation contradiction, which misleads agents about the tool's safety profile. Despite the description being transparent about the mutation, the contradiction warrants a score of 1 per the rules.

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

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

The description is concise and front-loaded with the core purpose. Each sentence adds unique information: return format, filtering, mark_read side effect, polling advice, and alternative endpoint. No filler or redundancy.

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

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

For a tool with no output schema, the description sufficiently explains return values (source, citation_uri, raw event payload), filtering options, mark_read behavior, polling suitability, and an alternative HTTP access. This is complete given the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), explaining mark_read behavior (flagging events read for subsequent calls), and clarifying the since parameter as an ISO timestamp. This exceeds the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts. It uses specific verbs ('Pull', 'Returns') and resource ('subscription feed', 'persisted feed'), and distinguishes itself from siblings like subscribe and list_subscriptions by focusing on retrieving events rather than managing subscriptions.

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

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

Provides clear context on when to use the tool (polling, reading alerts) and explicitly mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, implying this tool is for interactive use. It does not explicitly exclude other tools, but the guidance is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive, but the description adds essential runtime behavior: fan-out to multiple sources, GDELT→GNews fallback triggers, and PatentsView sunset soft-fail. This goes well beyond the annotations and clarifies what the agent should expect.

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 each clause contributes: triggers, sources, fallback, time handling, return shape, and alternative tool. It could be better structured with bullets, but it's not bloated; the length is justified by inherent complexity.

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

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

For a multi-source aggregation tool with no output schema, the description covers trigger phrases, sources, fallback logic, soft-fail behavior, `since` formats, return structure (changes[], total_changes, citation URIs), and the sibling alternative. This is comprehensive.

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

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

Schema covers all three parameters with descriptions, but the description enriches `since` with concrete formats ('2026-04-01', '7d', '3m') and a recommended value ('30d'/'1m'). It also clarifies `value` accepts ticker or zero-padded CIK, adding practical examples beyond schema.

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

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

The description opens with natural-language query examples, then states the precise action: a change feed for a company over a time window in one parallel call, fanning out to SEC, GDELT/GNews, and USPTO. It clearly differentiates from entity_profile, which serves the 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?

Explicitly names entity_profile as the alternative when a static profile is desired, and advises '30d' or '1m' for typical monitoring. It also explains fallback conditions (GNews on rate-limit/5xx) and soft-fail for patents, giving concrete use 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 establish non-read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: persistence differences between authenticated users and anonymous sessions (24 hours) and key-value scoping by identifier. It does not mention whether storing an existing key overwrites the value, but the idempotentHint partially covers that.

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 contains five sentences, each adding necessary information: the core purpose, usage signals, storage structure, persistence rules, and related tools. There is no filler or repetition of structured data.

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

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

The tool has only two required parameters, no output schema, and annotations are present. The description covers purpose, when to use, persistence behavior, and sibling relationships. Minor gaps like overwrite semantics and response format prevent a perfect score, but the description is largely complete for a simple memory store.

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 confirms the key-value model and mentions scoping by identifier, but it does not add meaningful detail about the key/value parameters beyond what the schema already 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 opens with a specific action ('Save data the agent will need to reuse later') and identifies the resource as key-value memory. It clearly distinguishes the tool from siblings by explicitly naming recall and forget as its counterparts for retrieval and deletion.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and gives concrete examples. It mentions pairing with recall and forget, though it doesn't explicitly state when not to use it versus 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 read-only and idempotent behavior; the description adds substantial context beyond them: graceful degradation of LEI/FIGI enrichment, explicit unresolved identifier reporting, candidate-return behavior for ambiguous matches, and the fact that each call cascades through multiple endpoints. This is far more than 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 long but highly information-dense, with front-loaded usage guidance followed by per-type details and caveats. It is somewhat dense in the middle, but every sentence contributes to disambiguating a genuinely complex tool, so the length is justified.

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 and no per-parameter documentation beyond basic descriptions, the description carries full responsibility — and it delivers. It covers supported types, input formats, resolution behavior, ambiguity handling, enrichment fallbacks, and identifier sources, so an agent has enough context to call the tool correctly in nearly all cases.

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

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

Even though schema coverage is 100%, the description adds critical meaning beyond the schema: value should be the entity name only, bond lookups require the exact issuer as printed, trailing security-class words will match nothing, and an ISIN input resolves to the legal-entity issuer. These examples and caveats materially improve correct invocation.

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 precise verb+resource pair: resolving user-spoken names to canonical/official identifiers. It is clearly distinct from sibling tools like entity_profile and compare_entities by positioning itself as the required first step whenever a tool input needs an ID.

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

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

Explicit guidance appears up front: 'Use FIRST whenever you have a name but need an ID.' The description also gives example user queries and clarifies when ambiguity should be resolved by returning figi_candidates, but it does not explicitly name alternatives or when-not-to-use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral detail: it 'probes each entity with ai_visibility_check', 'ranks by score', and returns 'score, confidence, signal density per entity'. This goes beyond the annotations by explaining the underlying process and output, though it does not mention potential rate limits or error behavior.

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

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

The description is tight and front-loaded: three sentences that cover purpose, usage context, and return format without fluff. Every sentence adds value, and the structure flows logically from 'what' to 'when' to 'output'.

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

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

There is no output schema, so the description correctly takes responsibility for explaining the return value ('ranked list with score, confidence, signal density per entity'). It also covers the invocation flow (probes via ai_visibility_check). Minor gaps include not explicitly stating the 2-8 entity constraint (though in schema) or error handling, but for an agent's selection and invocation it is sufficiently complete.

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

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

Schema description coverage is 100%, with all four parameters described in detail (e.g., entities array includes the first-as-subject rule). The tool description adds little beyond repeating this, such as 'your brand + N competitors', which is already in the schema. Therefore the baseline of 3 applies.

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

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

The description clearly states the tool's purpose with specific verbs and resources: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check by focusing on multi-entity comparison and ranking, explicitly mentioning 'your brand + N competitors' and delivering a ranked list.

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: 'Useful for competitive AI-marketing audits' and gives an example query. It implies this tool is for side-by-side comparison versus single-entity checks, but it does not explicitly exclude alternatives or name sibling tools, stopping 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?

Beyond the readOnly/idempotent annotations, the description reveals composite behavior, partial failure handling, and latency expectations: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also details the return summary block, per-advisory detail, and links, adding significant insight 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?

Despite being one of the longer descriptions, every sentence serves a purpose: core purpose, usage triggers, output details, ecosystem scope, and failure behavior. It is front-loaded with the primary use case and structured logically, making it easy to parse without unnecessary verbosity.

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 composite tool with no output schema, the description fully compensates by listing the exact summary fields, per-advisory details, links, and alternative versions. It also covers ecosystem limitations, potential latency, and degradation behavior, making the tool's behavior and returns fully understood.

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 100% coverage of both parameters (package and version) with clear descriptions. The description adds no new parameter semantics beyond what the schema states, such as 'version defaults to the latest published version when omitted' which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for 'should I add this npm package to my project', with specific verbs like 'scan' and 'fans out' across deps.dev and bundlephobia. It differentiates itself from siblings by focusing on npm package evaluation, distinct from the other research/analysis tools like bet_research or deep_research.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is clear and actionable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds rich behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine, 500-char overlapping windows, and truncation flagging beyond the 200K cap. These are meaningful disclosures beyond the structured fields.

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

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

Every sentence earns its place: first defines the action, second gives use cases and benefits, third suggests a complementary tool, fourth details technical behavior. Front-loaded with the core purpose and 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?

For a tool with no output schema, the description explains the return type (top-N passages with offsets and scores), the truncation behavior, and the context of use. It covers the tool's operation and output expectations comprehensively.

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 context beyond the schema by giving examples of what to pass (e.g., SEC 10-K body) and example queries, plus the natural-language query concept, strengthening 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 opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by contrasting with ask_pipeworx_grounded and mentioning it searches within already-fetched content, not the whole knowledge base.

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: 'Use when the record is too big to cram into the prompt.' It also names the alternative ask_pipeworx_grounded and explains the pairing (fetch with the gateway, ground over relevant passages), providing clear decision guidance.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses important behavioral traits: returns a subscription id, requires authenticated accounts, describes delivery channels with phone verification and a 10/day SMS cap, and notes the feed is always on. This adds value without contradicting any 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 moderately long but every sentence contributes value. It is front-loaded with the core purpose, then covers requirements, types, and delivery channels in a logical order. No filler or redundancy.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery channels) and the absence of an output schema, the description covers the essential aspects: purpose, return value, authentication, types, and delivery options. It omits webhook details from the main description (though present in the schema), but remains sufficiently complete for an agent to understand and correctly invoke the tool.

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

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

The input schema has 100% description coverage, but the tool description adds practical meaning beyond the schema, such as explaining that items:["5.02"] means officer change for sec_8k and giving specific examples for each type. This enhances parameter understanding beyond the structured schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb+resource and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It also details supported subscription types, adding further specificity.

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: it requires a Pipeworx OAuth account, explains the always-on feed delivery and how to pull alerts (via recent_alerts or GET), and notes optional email/SMS with constraints. It doesn't explicitly contrast with alternative tools, but it clearly implies this tool is for creating subscriptions, not managing or listing them.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds meaningful behavioral context: it returns categorized example questions with tool/argument shapes, supports topic filtering, and is drawn from the live catalog. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but efficiently packs multiple example user intents, the return payload, topic filtering, and usage guidance into a single structured paragraph. Every sentence contributes to understanding the tool's purpose and invocation, though it could be slightly tighter.

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

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

With only one optional parameter and no output schema, the description carries the burden of explaining return values and usage context. It clearly describes the categories returned and the tool-shape inclusion, and provides a list of related meta-tools. It is sufficiently complete for guiding an agent, though it omits details like response size or potential edge cases.

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

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

The input schema fully documents the optional 'topic' parameter with its allowed values and the default full-spread behavior (100% coverage). The description repeats this information with examples, adding minimal extra semantic value beyond what the schema already provides.

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

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

The description clearly identifies this as the onboarding entry point for discovering what Pipeworx can do, explicitly stating it returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by mentioning meta-tools and framing itself as the 'Use this FIRST' tool.

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

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

Provides explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools') and describes parameter behavior (omit for full spread, pass topic to focus). It does not explicitly mention when not to use it or compare to similar siblings like discover_tools, but the context is clear.

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

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

Beyond the annotations (which already indicate a non-read, non-destructive, idempotent operation), the description adds key behaviors: ownership enforcement (only own subscriptions), and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This provides context not captured in the structured data.

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

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

The description is three short sentences, each adding essential information: the action, the ownership rule, and the deactivation behavior. It is front-loaded with the core function and contains 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 simplicity (one parameter, no output schema), the description covers all essential operational details: the required id, ownership constraint, and the non-destructive nature of the cancellation. It even connects the deactivation behavior to the recent_alerts tool, providing a complete picture 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?

The input schema already provides full coverage (100%) for the single `id` parameter with a description referencing subscribe. The tool description only restates 'by id' and adds the ownership constraint, which doesn't enhance the semantic meaning of the parameter itself. With high schema coverage, baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Cancel a subscription by id'), clearly distinguishing it from sibling tools like subscribe, list_subscriptions, and recent_alerts. The ownership constraint further clarifies scope.

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

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

The description implies when to use the tool (when you have a subscription id from subscribe and want to cancel your own subscription). It provides context about ownership and deactivation, and explicitly mentions that historical events remain accessible via recent_alerts, which helps an agent decide between this tool and alternatives. However, it doesn't explicitly state when not to use it or name alternatives directly.

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 annotations by detailing the verdict types, distinguishing could_not_verify from unsupported, and instructing callers not to treat could_not_verify as evidence. It also discloses the dual execution paths, which is critical behavioral context not available in 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 long but every sentence earns its place, with front-loaded examples and a clear structure that culminates in the callers-important caveat. The length is justified by the tool's complexity and the need to explain error semantics.

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 enumerates the return components (verdict, actual value with citation, reasoning) and clarifies the meaning of each failure verdict. It fully equips the agent to understand expected results and how to interpret them.

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 both parameters (100% coverage), so the baseline is 3. The description adds meaningful extra context: it explains tolerance_pct overrides the claim's implied tolerance, provides a usage range, and recommends 1–2% for hallucination detection, which the schema lacks.

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 defines a specific verb+resource: natural-language claim verification against authoritative sources, listing example query forms. It distinguishes itself from sibling tools by describing its verdict output and the two-path architecture (SEC EDGAR vs grounded pipeline), making its unique role clear.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use guidance. It doesn't name alternative tools or provide exclusions, but it does explain the automatic fallback for any non-financial claim, which helps routing decisions.

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