postcodes

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: per-model response structure ({score, confidence, signals, raw_response} + combined view), the default free Workers AI model, and the BYO-key payment model for Anthropic calls. 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 four sentences, each serving a purpose: core function, default/optional behavior, return format, and use cases. It is front-loaded with the most critical information and avoids fluff or redundancy.

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

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

Given the lack of an output schema, the description adequately explains the return value ('per-model {score, confidence, signals, raw_response} + a combined view') and the 0-100 scoring range. It also covers the Anthropic key requirement and common use cases, making it complete for an agent to select and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds semantics beyond the schema by explaining the default model ('Workers AI Llama-3.3-70b (free)') and the payment implication of `_apiKey` ('BYO key — you pay Anthropic directly'), which enriches the 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 clearly states a specific verb ('probe') with a resource ('LLMs for what they know about a business / brand / product / topic') and an outcome ('score visibility (0-100) per model'). It distinguishes itself from siblings by focusing on AI visibility scoring rather than general Q&A or research, and even mentions concrete use cases like AI-marketing audits.

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

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

Provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to pass `_apiKey` to probe Anthropic. However, it does not explicitly contrast with similar-looking siblings like `scan_competitor_ai_presence`, so exclusions are missing.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses significant behavioral detail: it routes to thousands of tools, automatically fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also notes it handles live news internally. These details help the agent predict what will happen during invocation and understand the output format. There is no contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the most important guidance ('PREFER OVER WEB SEARCH') and then layering in behavior, usage triggers, examples, and routing alternatives. The only redundancy is 'START HERE for most questions — use this tool for most questions' which repeats 'most questions'. Otherwise 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?

Even without an output schema, the description explains the return format (structured answer with citation URIs), the internal routing behavior, and the intended use cases. It also names all relevant sibling tools and the conditions for selecting them. An agent has everything it needs to decide whether to invoke this tool and what to expect from it.

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 parameters (with 100% coverage) and lists 'question' plus aliases. The description adds value by explaining the nature of acceptable inputs—natural-language factual questions—and provides multiple examples of valid queries. This gives the agent a richer sense of how to phrase the parameter beyond the schema's basic type definition.

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 begins with 'PREFER OVER WEB SEARCH' and clearly defines the tool's function: routing questions to 5,798 tools across 1,517 verified sources and returning structured answers with citation URIs. It also names sibling alternatives (ask_pipeworx_grounded, deep_research) to distinguish itself, and provides concrete example queries. An agent can unambiguously identify what this tool does and when to choose it.

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

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

The description explicitly states when to prefer this tool over web search, lists triggering question phrases ('what is', 'look up', 'find', 'get the latest'), gives six diverse examples, and explicitly routes special cases to siblings (SOP-grade needs to ask_pipeworx_grounded, broad multi-part to deep_research). It even covers breaking news handling. This leaves no ambiguity about 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?

The annotations already establish that the tool is read-only, idempotent, non-destructive, and open-world. The description adds genuinely useful behavioral context: it is a live full working router, not a fallback stub; experimental routing candidates may be active; and none are active right now as of a specific date. This goes well beyond what the 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 dense but well-structured, front-loading the beta relationship and current identical behavior before explaining the experimental context. Each sentence contributes a distinct fact: matching behavior, experimental state, usage guidance, and lack of fallback. It is slightly verbose but not padded.

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 100% schema coverage, rich read-only/idempotent annotations, and clear sibling context, the description is nearly complete. It explains current behavior, experimental status, and usage. The only notable gap is that while it says 'same response shape' as ask_pipeworx, it does not describe what that response shape actually is, and there is no output schema to fill the gap.

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

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

Schema description coverage is 100%, with question and its five aliases fully described in the input schema. The tool description only says 'same arguments' without adding parameter-level detail, which is acceptable because the schema already carries that burden. Baseline 3 is appropriate.

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

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

The description states that this is the Beta version of ask_pipeworx and a universal router with the same tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx by its experimental candidate-routing status. A small deduction because it never states the underlying user-facing function in plain terms, relying on the name 'Ask' and the router metaphor.

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 it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It also notes that no candidate is currently active, so it currently matches ask_pipeworx exactly. It does not explicitly list when not to use it, but the alternative stable router is clearly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, and the description is fully consistent with them. It adds substantial behavior beyond annotations: the tool refuses rather than fabricates when data doesn't answer, enumerates five refusal_reason values, returns a verbatim evidence quote, and carries a one-extra-LLM-call cost. The 'EXTRACTS using ONLY what the tool result contains' constraint is a significant disclosed behavioral trait.

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?

Six sentences, each earning its place: purpose, routing mechanism, success return shape, refusal return shape, usage guidance, and cost tradeoff. The differentiator is front-loaded in the first sentence, and the return-shape details are necessary because no output schema exists. There is no fluff or repetition of annotation content.

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

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

For a grounded Q&A tool with one well-documented parameter, the description covers everything an agent needs: the return contract (success and refusal), all refusal reasons, the evidence requirement, when to use, and the cost/alternative. Since no output schema exists, the inline return-shape disclosure is essential and is fully supplied.

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

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

Schema coverage is 100% — the lone question parameter and its five aliases (q, query, prompt, text, input) are fully documented in the schema. The description adds no parameter-specific format guidance, but none is needed since the schema carries the full burden. Per the baseline rule for full schema coverage, 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 opening phrase 'Hallucination-resistant answer mode for high-stakes reads' names a specific mode, verb, and resource. It further distinguishes itself from ask_pipeworx by noting it uses the same routing but then EXTRACTS the answer using ONLY what the tool result contains. An agent can tell it apart from ask_pipeworx and ask_pipeworx_beta without inspecting schemas.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives the exclusion — 'prefer ask_pipeworx for casual lookups' — backed by the one-extra-LLM-call cost rationale. This is explicit when-to-use, when-not-to, and which alternative to pick.

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 a wealth of behavioral nuance: resolver confidence levels, fan-out logic, low-confidence short-circuiting, closed-market handling, wide-spread tradeability warnings, and even cancellation-rule risk like flat-50¢ void settlements. This is far more than the annotations alone.

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

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

The description is lengthy but well-organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It front-loads the core purpose and packs dense, valuable details into every sentence. Slightly over-long, but the structured format keeps it navigable.

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

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

Given the tool's high complexity and lack of an output schema, the description covers the full response contract: resolver match confidence, parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. It effectively substitutes for a missing output schema and leaves no critical usage aspect unexplained.

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

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

With 100% schema description coverage, the baseline is 3. The description adds practical meaning beyond the schema by explaining acceptable market input varieties, showing fan-out examples that illustrate depth levels, and clarifying include_raw's size trade-off. These additions go beyond simple field definitions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states accepted input formats and target use cases ('should I bet on X'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context but does not explicitly state when not to use the tool or compare it to alternative approaches, falling just short of full exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data plus citation URIs, and efficiency benefit (replaces 8–15 lookups). These go well beyond the annotations.

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

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

The description is dense but well-organized, starting with trigger phrases, then core function, data details, output behavior, and efficiency. Every sentence adds value, though it is somewhat long; a slight trim would make it more concise without losing information.

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

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

With no output schema, the description adequately covers return values (paired data + pipeworx:// URIs), input semantics, data sources, sorting, and edge cases (off-calendar fiscal years). For a tool with only two parameters and moderate complexity, it is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning: it explains what each 'type' value pulls (10-K metrics for company, adverse-event/trial counts for drug) and provides examples for 'values'. This enriches the schema definitions meaningfully, though it doesn't add format details 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 comparisons of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'Compare X and Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups, making it unique among siblings such as entity_profile.

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

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

Explicitly provides when-to-use examples ('X vs Y', 'which is bigger', 'head to head') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', which is a clear alternative/exclusion. It also differentiates between company and drug types, giving context for each.

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 read-only/idempotent annotations, it discloses major behavioral traits: account requirement and tiered depth, decomposition and parallel routing, the exact findings packet fields, fetchable pipeworx:// citations, gaps[] instead of invented answers, contradictions[] for higher depths, semantic excerpting, and expected latency. No annotation contradiction.

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

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

The description is dense and front-loaded with the most decision-relevant facts (account, alternative tool), and nearly every clause earns its place. It is not a short or cleanly structured text — it uses heavy parentheticals and asides — but it avoids fluff.

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

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

With no output schema, the description fully covers return contents (evidence, confidence, source, fetched_at, citation, gaps, contradictions), runtime expectations, auth prerequisites, and edge behavior for long records. Nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents question and depth, including depth-level facet counts and hop behavior. The prose adds examples and motivational framing but no new parameter semantics; 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 names a specific, multi-part action ('Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources') and a concrete mechanism (decomposing into facets, routing in parallel, returning evidence-cited findings). It distinguishes itself from both open-web search and the ask_pipeworx sibling, so an agent can confidently tell it 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?

Explicitly states when to use (broad/multi-part questions over structured data) and when not to: not signed in or single lookup → use ask_pipeworx instead, and 'this is NOT open-web search'. This is a clear when/when-not/alternative pattern.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral details beyond that: returns top-N tools, includes full schemas with curated examples, and eliminates the need for a second schema lookup. This gives the agent confidence in what to 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 front-loaded with the core purpose, then gives usage context and return details. It is three sentences long; the middle domain list is long but purposeful as it sets expectations for what can be searched. No redundant fluff, but slightly wordier than 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?

There is no output schema, so the description carries the burden of explaining return values. It does so well by stating that it returns 'names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly'. It also covers 'no second schema lookup needed', making the tool's behavior clear for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The tool description doesn't add significant parameter-specific semantics beyond the schema; it merely lists example domains, which helps formulate queries but doesn't explain parameter syntax or edge cases.

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', which is a specific verb+resource statement. It clearly differentiates from siblings by positioning itself as the meta-search/discovery tool, listing concrete domains and return format.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It implies when not to use it (when you already know the exact tool), providing clear actionable guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior, and the description adds substantial behavioral detail: one parallel call, soft-fail for the USPTO patents API, empty sections as real 'no data' not bugs, name resolution via SEC EDGAR, and private company behavior returning resolved:false with notes. 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 long, but the length is justified by the tool's complexity and the many edge cases an agent must understand. Examples and purpose are front-loaded, and each subsequent clause adds meaningful detail about sources, return fields, or failure 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?

There is no output schema, so the description carries the full burden of explaining what the tool returns. It enumerates every important result section, source failure behavior, input resolution behavior, and the semantics of empty results. No critical information needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds extra meaning beyond the schema by giving concrete examples of tickers, zero-padded CIKs, company names, and clarifying that type values are interchangeable.

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, well-scoped purpose: a 'full cross-source profile of a US public company' produced in one parallel call, backed by many input examples. It lists the exact sources it fans out across and the return sections, which clearly distinguishes it from single-source lookup tools and siblings like resolve_entity.

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

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

It explicitly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving strong when-to-use guidance. It does not contrast itself with closely related siblings like compare_entities or deep_research, so the agent must infer some routing decisions for those 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 destructiveHint=true and idempotentHint=true. The description adds behavioral nuance by highlighting the purpose of clearing sensitive data, which goes beyond the bare delete action. No contradiction; it reinforces the destructive nature without redundancy.

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

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

Three concise sentences, front-loaded with the action, followed by when-to-use and pairing advice. Every sentence provides value with no extraneous detail.

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?

A simple one-parameter, no-output-schema tool with strong annotations. The description is fully self-contained: it states the action, the trigger conditions, and related tools, making it complete for an agent to understand 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% with the 'key' parameter clearly described as 'Memory key to delete'. The description does not add new meaning beyond the schema, but there is no gap, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Delete' and a clear resource 'previously stored memory by key', making the action unambiguous. It also implicitly distinguishes from sibling tools like 'remember' and 'recall' by stating it deletes rather than stores or retrieves.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also tells the user to pair with 'remember and recall', providing clear context for use relative to 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=true and destructiveHint=false, establishing a safe read operation. The description adds process details (fetches the page, extracts title/description/key links) and mentions output format (standard llms.txt markdown), but it doesn't disclose edge behaviors like timeout handling or errors. With strong annotation coverage, a 3 is appropriate as the description adds some context beyond 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 sentences long, front-loaded with the core purpose, and every sentence adds value. It avoids fluff and repetition, efficiently covering purpose, process, output, and use cases in a compact format.

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

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

For a simple tool with 100% schema coverage, useful annotations, and no output schema needed (since output is a text blob), the description covers the essential context: what it does, how it works, and when to use it. It's slightly incomplete in terms of edge-case behavior, but it's well-suited to the tool's simplicity.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are fully documented in the schema itself. The description does not add extra parameter-specific context, such as how max_links interacts with pagination. Baseline 3 is correct since the schema carries the heavy lifting and the description adds no extra semantic value.

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 ('Generate') and a concrete resource ('a production-ready llms.txt file for any URL'), clarifying both the action and the target. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on producing the actual llms.txt markdown, not just analyzing visibility.

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 three practical use cases: getting a client's site indexed, drafting llms.txt for your own project, and auditing a competitor. While it doesn't state when to avoid this tool or mention alternatives by name, the use-case list provides clear context for when it is appropriate, earning a 4.

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 and idempotent, and the description adds useful context about scope (caller's subscriptions) and default behavior (active only, with the include_inactive parameter). It doesn't contradict annotations and provides meaningful behavioral detail beyond safety flags.

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: first states action and return fields, second gives usage context. No fluff, front-loaded, every word earns its place.

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

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

With no output schema, the description explicitly names return fields. The single optional parameter is explained in the schema, and the tool's role relative to subscribe/unsubscribe is clearly stated. The description is complete for an agent to select and call the tool correctly.

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

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

The input schema covers the single parameter include_inactive with a clear description. The tool description does not need to add more, as schema coverage is 100%; baseline 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.). This specific verb+resource combination distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This differentiates it from subscribe/unsubscribe and covers the main 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, covering the safety profile. The description adds valuable context by specifying what data is returned (coordinates, region, district, ward, constituency), going beyond the annotation-level information without contradicting it.

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

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

The description is two sentences, front-loaded with the primary action, and includes an example and return fields. Every sentence earns its place with no fluff or repetition.

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

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

The tool has a single parameter, comprehensive annotations, and an output schema. The description fully covers the tool's purpose and return values, making it complete for a simple lookup tool. No additional behavioral context is needed given the simplicity and rich structured metadata.

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

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

Schema coverage is 100%, and the schema already provides a clear description and examples for the postcode parameter. The description repeats an example ('SW1A 1AA') but adds no new semantic information beyond what the schema documents, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'geographic details for a UK postcode', and it lists specific return fields (coordinates, region, district, ward, constituency). This distinguishes it from sibling tools like validate_postcode or random_postcode by focusing on retrieval of geographic details for a given postcode.

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

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

The description implies usage when geographic details for a UK postcode are needed, but it does not explicitly state when to use this tool versus alternatives like validate_postcode or nearest_postcodes. No exclusions or alternative tool mentions are provided.

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 the operation read-only, non-destructive, and idempotent. The description adds useful behavioral details beyond annotations, such as sorting by distance and returning coordinates, which helps set expectations without contradiction.

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

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

The description is one concise sentence, front-loaded with the main purpose ('Find nearby UK postcodes'), followed by the sorting and output details. Every word earns its place 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?

For a simple read-only tool with one parameter, an output schema, and rich annotations, the description is completely adequate. It specifies the input, the sorting behavior, and the return shape, leaving no critical gaps for an agent to misuse 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?

Schema coverage is 100% with the single 'postcode' parameter fully described. The description only repeats the example and adds no additional parameter semantics beyond what the schema already provides, so the 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 states a specific verb ('Find') with a clear resource ('nearby UK postcodes') and distinguishing behavior (sorted by distance from a given postcode). This clearly separates it from sibling tools like lookup_postcode, random_postcode, and validate_postcode.

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 clearly implies when to use the tool: when you need nearby postcodes for a given postcode. It does not explicitly mention alternatives or exclusion cases, but the context is clear enough for an agent to select it over related sibling tools.

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

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

Extends far beyond the annotations: explains the claim_token workflow for anonymous reports and later follow-up, daily rate limit of 5 per identifier, free/no quota impact, and that the team reads digests daily. These are non-obvious behaviors the agent needs to invoke and set expectations 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 information-dense; every sentence carries operational instructions (routing, claim_token, rate limits). It is front-loaded with purpose and use cases, though the volume of detail is higher than strictly necessary, so it doesn't earn a top conciseness 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?

With four optional params and no output schema, the description covers all key context: when to file, how to identify Pipeworx tools, the claim_token lifecycle, rate limiting, and cost. It is sufficient for an agent to select and invoke the tool correctly without further clarification.

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

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

The schema already describes all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining the claim_token round-trip ('Filing without an account returns a claim_token; pass it back later...') and by advising message specificity and 1-2 sentence typical length, which goes beyond schema constraints.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete report types (bug, feature/data_gap, praise), making the tool's role unmistakable and clearly distinct from siblings like ask_pipeworx.

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

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

Explicit when-to-use guidance is provided for each category ('Use when a tool returns wrong/stale data (bug)...'), along with a clear exclusion: reports must be for tools served by this Pipeworx connection, not other MCP servers. This tells the agent exactly when to choose this tool over 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description adds valuable context: caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). These details disclose how the data is gathered and its freshness.

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: a hook, output summary, numbered use cases, and data provenance/caching notes. Every sentence contributes value, and the numbered list makes the use cases easy to scan. No redundant or fluff content.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the output contents, use cases, data source, privacy, and caching. It is fully self-contained and leaves no critical gaps for an agent to resolve.

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 parameter coverage with an enum and semantic explanation ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats the window options but adds no new parameter semantics beyond what the schema already states.

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

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

The description opens with a clear question 'What other AI agents are calling on Pipeworx right now' and enumerates exact outputs: top tools, top packs, and total call volume over a recent window. This clearly distinguishes it from siblings like discover_tools and ask_pipeworx, which serve different purposes.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming a canonical tool, checking alignment with user needs). It does not mention alternatives or when not to use, but the use cases are specific enough to guide appropriate 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description goes far beyond this by disclosing specific behavioral quirks: placeholder slug filtering, the >20% placeholder fraction returning null, the Jaccard similarity threshold (≥0.30), and the fill-check mechanism that can override a signal. It also explains what happens when realizable_edge_pp ≤ 0, which is critical for safe use. 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?

Although lengthy, every sentence carries operational value. The description is organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and uses imperative guidance like 'do not trade it.' It front-loads the core usage pattern ('Call with NO args...') and structures detail logically. No filler or repetition.

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

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

No output schema exists, so the description must explain return values—and it does: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}'. It also covers edge cases (placeholder filtering, low similarity), pricing depth checks, and cross-event mode benefits. For a tool with two optional parameters and complex internal logic, this is fully 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% with both event and topic having descriptions. The description adds substantial meaning beyond the schema: concrete slug examples, seed question examples, the fact that full Polymarket URLs are accepted, and the exact behavior of each mode. It also clarifies that zero arguments are valid, which 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges (which likely focuses on edges) and polymarket_fill_risk (which the description explicitly differentiates for custom sizing). The three modes (trending_scan, event, topic) are precisely described.

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 for each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative tool: 'For custom sizing use polymarket_fill_risk.' The fill-check section explains when not to trade (realizable_edge_pp ≤ 0), making usage conditions exceptionally clear.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing internal algorithms, slippage assumptions, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostic output. It also warns about 24h-move signal and explains why certain segments might be empty, providing excellent transparency.

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

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

The description is extremely long and dense, covering model formulas, specific alpha values, gate relaxations, and response field details. While it's well-organized with numbered segments, it's far from concise—many sentences contain implementation specifics (e.g., 'tennis 1.02, soccer 1.10, MMA 1.15, default 1.0') that could overwhelm an agent and hinder quick scanning.

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: by_segment, fed_candidates/fed_note, and _diagnostics. It describes the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume) and why segments might be empty (via filter_skips), making it highly complete for a tool of this complexity.

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

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

Even though schema coverage is 100%, the description adds substantial meaning to parameters. It explains the rationale for knobs like min_liquidity and max_spread_pp ('drop opportunities where edge isn't realizable'), the difference between min_kelly and min_partition_leg_kelly, and gives guidance on slippage_pp values ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade').

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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-driven edge detection and its built-in segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT.

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

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

The description states its intended use case ('Built for what should I bet on today') and explains when to use it: to discover opportunities without paging hundreds of markets. It also provides a caveat about Fed candidates being unreliable at meeting-month horizons, but it doesn't explicitly name alternative tools or state when not to use this one.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond this by explaining the response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot gaps), and interpretation details (decay based on daily closes, signed edge values). This provides rich behavioral context 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?

Description is long but well-structured with clear divisions (Args:, RESPONSE:, LIMITS:). It front-loads the core purpose, then details parameters and output, ending with limitations. Every sentence adds substantive information; no filler.

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

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

Given the tool's moderate complexity and absence of an output schema, the description fully compensates by detailing the response objects (tracked, expired, snapshot_dates) and their fields, plus important caveats. The agent has enough information to invoke the tool 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 covers 100% of parameters (days, window) with clear descriptions. The description adds minor context like 'snapshot family' and echoes defaults but doesn't significantly improve on the schema. It omits the min clamp for days (2) that the schema includes. 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?

Description clearly states the tool's unique function: edge persistence and decay telemetry. It answer a specific trading question (how long has an edge existed and is it shrinking?) and distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshots. The verb 'answers' gives a concrete use case.

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

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

The description implies when to use this tool: when you need to understand edge persistence over time, not just current edges. It mentions being built from daily polymarket_edges snapshots, which suggests it complements the sibling polymarket_edges tool. However, it doesn't explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses intricate behaviors: it 'walks the ladder', computes vwap_fill_price and slippage_pp, and returns a verdict (clean|degraded|cannot_fill). It also reveals risk-related behavior such as 'thin_legs[]' and 'forced_directional_risk naming the legs most likely to strand you unhedged', which is critical operational context.

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

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

The description is long but meticulously structured with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections, front-loading the core purpose. Every sentence carries operational value, with no filler; the density is justified by the tool's two-mode 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 carries full weight for return-value documentation, and it delivers: it enumerates all return fields for both modes (top_of_book, vwap_fill_price, capture_ratio, profit_usd, thin_legs[], etc.). It also covers edge cases like partial fills and forced directional risk, making it self-sufficient for an agent to decide when and how to invoke it.

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

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

Though schema coverage is 100%, the description adds substantial meaning: it explains that `market` means single-market mode and `event` basket mode, that `size_usd` is 'max spend on buys, target proceeds on sells' in single-market but 'settlement notional S (shares per leg)' in basket mode. It also documents defaults and clamps ('Default 1000, clamp 10–1,000,000'), far exceeding the schema.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') that clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. It elaborates two distinct modes (SINGLE-MARKET and BASKET) with explicit output fields, making the tool's function unmistakable.

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

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

It explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming the exact sibling tools and conditions. It also warns why (theoretical overround not capturable, partial basket fills create unhedged directional risk), providing both when and why guidance.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive. The description goes far beyond this by disclosing specific behavioral traits: compatibility_warning/codes that can accompany returned pairs, skipped_unclassified and low_confidence_pairs handling, the gross (not net) spread and missing Kalshi fee modeling, and counters for dropped comparisons. It also warns that returned pairs may still be unverified because matching is keyword-based. This is abundant value beyond the annotations.

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

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

The description is dense and long, with the first sentence immediately stating the tool's purpose and the modes introduced early. Every sentence carries information about response fields, safety codes, fee disclosure, or edge cases, so there is little redundancy. However, the sheer volume of detail in a single paragraph makes it harder to parse than a more structured or higher-level description would be.

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 bears the full burden of explaining the response. It covers leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility_warning/codes, temporal_alignment fields, fees_note, skipped_cross_type/subtype counters, and behavior for unknown legs. For a tool with this analytical complexity and two modes, nothing an agent needs to safely interpret results is missing.

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

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

Schema coverage is 100% for all three parameters, and the description adds meaning beyond the schema: the `topic` parameter is fully enumerated with its 10 shortcuts, and the explicit parameters are described as overrides that replace the topic-mapped side. It also states that both modes run the identical token-overlap matcher, which clarifies the interaction between parameters. This is substantial enrichment over 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 opening sentence states a specific purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the venues and the measured quantity, so an agent understands what the tool does. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edges, so it lacks direct sibling differentiation.

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 clearly explains two invocation modes (topic shortcuts vs explicit ticker/slug pairings) and when each is appropriate, including the list of pre-mapped topics. It also gives strong expectations about reliability: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly compare against sibling tools, but for its own modes the guidance is concrete 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 indicate read-only, idempotent, non-destructive behavior. The description adds useful context by specifying that the postcode is random and valid, and lists the returned geographic details, which goes beyond the annotations. It does not disclose additional limitations or caveats, but the positive annotation profile lowers the burden.

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, front-loaded sentence that states the main purpose and then enumerates the returned data fields. There is no wasted wording, and the structure is easy to scan.

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

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

The tool is simple with 0 params and has a strong annotation profile. The description covers the core function (random valid UK postcode) and the key outputs (coordinates, region, etc.), which, combined with the output schema, offers a complete picture for an agent to invoke the tool correctly.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. With 0 params, the baseline is 4, and the description appropriately omits parameter details since none exist. It adds nothing about parameters, but nothing is needed.

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

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

The description clearly states the action ('Get a random valid UK postcode') and highlights it returns full geographic details like coordinates, region, district, ward, and constituency. This distinguishes it from sibling tools such as lookup_postcode or validate_postcode, which serve different purposes.

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

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

The description implies the tool is for obtaining a random postcode rather than a specific one, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. Given the sibling names, an agent could infer the use case, but the guidance is not explicit.

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 convey read-only and idempotent behavior, and the description adds useful context such as scoping ('Scoped to your identifier') and the dual-mode behavior (omit key to list). It does not describe error handling or return format, but this is partially covered by the annotations.

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

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

The description is three sentences, front-loaded with the main action, then provides examples, scope, and pairing. Every sentence contributes essential information 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?

For a simple read-only tool with strong annotations, the description covers functionality, usage context, scoping, and related tools. Since there is no output schema, not detailing return format is acceptable. The tool is appropriately 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% for the 'key' parameter, so the baseline is 3. The description enriches the parameter meaning by explaining that the key retrieves a value 'previously saved via remember' and that omitting it lists all keys, providing context beyond the schema.

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

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

The description clearly states the tool's function with specific verbs and resources: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes itself from siblings by explicitly mentioning remember and forget, and by describing both operational 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 provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives for related operations: 'Pair with remember to save, forget to delete,' effectively delineating when not to use recall.

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 directly contradicts the annotations. Annotations declare readOnlyHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state-changing write. This is a serious inconsistency that undermines agent trust.

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: the first sentence states the core purpose, followed by details on return payload, filtering, mark_read, and alternative access. It is slightly dense but each sentence contributes useful information without excessive verbosity. It does not repeat schema descriptions unnecessarily.

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

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

The description covers return format (source, citation_uri, raw payload), filtering, mark_read behavior, and alternative endpoint access. However, it omits interaction between parameters (e.g., unread_only vs mark_read) and does not mention the default limit or range, though these are in the schema. The annotation contradiction further reduces completeness, as the behavioral contract is inconsistent.

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 meaningful semantics beyond the schema: it gives a concrete example filter value ("sec_8k"), clarifies the use of 'since' as ISO timestamp, and explains the effect of mark_read:true (next call only shows newer events). This enriches the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It specifies the resource (subscription feed alerts) and the action (pull/return), distinguishing it from siblings like recent_changes. It also mentions key aspects like filtering and mark_read behavior.

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 says 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and 'Polls work fine', indicating suitable scenarios (polling, filtering). It also points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral detail: data source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), specific fallback triggers (rate-limited or 5xx), and the PatentsView sunset condition causing soft-fail. This goes well beyond the annotations.

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

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

The description is longer than average, but every sentence contributes essential operational detail (sources, fallbacks, parameter syntax, return structure, alternative tool). It is front-loaded with the most common use cases. Slightly dense, but not wasteful.

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, multi-source aggregation tool with no output schema, the description is thorough: it explains return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs), fallback behavior, parameter formats, and the appropriate alternative tool. No critical gaps for an agent to invoke it correctly.

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

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

Schema covers 100% of parameters, but the description adds meaningful semantics: `since` formats (ISO date vs relative shorthand like '7d', '30d', '3m', '1y'), `value` examples (ticker vs zero-padded CIK), and `type` restriction to 'company'. This adds value beyond the schema definitions.

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

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

The description opens with concrete user intents ('What's new with X' / 'latest on Y') and clearly states this is a change feed for a company over a time window, aggregating multiple sources in one parallel call. It also distinguishes itself from entity_profile, making the purpose unmistakable.

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

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

Provides explicit guidance on when to use this tool vs. the sibling entity_profile tool: 'Use entity_profile instead when you want the static profile... regardless of window.' Also clarifies supported entity type (company only) and gives typical usage examples (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

The description adds valuable behavioral context beyond the annotations: persistence semantics (authenticated users get persistent memory, anonymous sessions retain for 24 hours) and key-value scoping. It complements the idempotentHint and readOnlyHint without contradiction.

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

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

The description is well-structured: opens with the core purpose, provides concrete usage examples, then explains storage mechanics and related tools. Every sentence contributes value, and it is appropriately concise for a simple tool.

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

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

Given the tool's simple key-value nature, the description is complete: it explains when to use it, how it behaves across sessions, and how to retrieve/delete data. The lack of an output schema is not a gap because the tool returns no complex result.

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 covers both parameters with descriptive examples (100% coverage). The description adds the context that values are 'scoped by your identifier', which clarifies how the key is namespaced, slightly enriching parameter meaning.

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

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

The description states a clear, specific purpose: 'Save data the agent will need to reuse later.' It identifies the resource (memory data) and the action (save), and distinguishes itself from sibling tools like recall and forget by explaining that this is the store operation.

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

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

It explicitly provides usage guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also states when to pair with recall and forget, giving clear direction on alternative tools.

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

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

Goes far beyond the readOnly/idempotent annotations by describing ambiguity handling (returns figi_candidates rather than asserting), explicit unresolved identifiers, graceful degradation of LEI/FIGI enrichment, cascading internal lookups, and non-equity instrument coverage. It is fully consistent with annotations.

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

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

The description is long but front-loaded with user intent and clearly structured by SUPPORTED TYPES and enrichment notes. Each clause carries behavioral or usage information; dense parentheticals prevent a perfect conciseness score, but there is no filler.

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

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

With no output schema, the description carries the return-value burden. It enumerates returned identifiers (CIK, ticker, LEI, ownership, FIGI candidates, unresolved, RxCUI, ingredient, brand, citation), labels data sources, and explains degradation and ambiguity behavior. An agent has enough context 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%, and the description adds substantial value beyond the schema: accepted input formats per entity type, the exact-passing rule for bond issuer names, why trailing security-class words fail, ISIN-to-LEI behavior, and brand/generic examples. This meaningfully reduces the chance of misusing the 'value' parameter.

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: it resolves user-spoken names to canonical/official identifiers for company and drug entity types. It also explicitly positions itself as the entry point when you have a name but need an ID, distinguishing it from sibling lookup/research tools.

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

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

Provides explicit when-to-use guidance via 'Use FIRST whenever you have a name but need an ID' and rich trigger examples. It does not explicitly state when not to use it or name alternative sibling tools, but the scope boundary ('name → ID') is clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral detail beyond annotations: it 'Probes each entity with ai_visibility_check, ranks by score' and returns 'ranked list with score, confidence, signal density per entity'. This informs the user about the internal mechanics and output shape, which is valuable. It does not mention potential latency or multi-call effects, but given strong annotations, this is sufficient.

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, tight and front-loaded. It states the core action, the method, a use case, and the return format with no wasted words. 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?

Given the tool's moderate complexity (multi-entity comparison, dynamic model selection) and the absence of an output schema, the description adequately covers the return value ('ranked list with score, confidence, signal density per entity'). It mentions the key constraint that the first entity is the subject, which is also in the schema. It could add notes about failure modes or rate limits, but it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters. The description adds no new parameter semantics beyond what the schema already provides, such as the entities array's first entry being the subject. It echoes the concept but does not enrich it. Thus the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and specifies it 'Probes each entity with ai_visibility_check, ranks by score'. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). The purpose is specific and actionable.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. It implies this is for multi-entity comparison versus the single-entity ai_visibility_check. It does not explicitly name alternatives or exclusions, but the context is clear enough for a user to know when to invoke 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, openWorld), the description reveals important runtime behaviors: fans out across two services, partial failure degradation, bundlephobia first-measurement latency (5-30s), and the sources_failed field. 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?

Description is front-loaded with the core purpose, then details the fan-out sources, return fields, success/failure behavior, and ecosystem scope. Every sentence carries unique information; it is long but efficient and well-structured.

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

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

For a composite tool with no output schema, the description comprehensively covers inputs, outputs (summary fields, advisories, links, alternative versions), failure modes, timing, and scope. It is fully self-contained for an agent to decide and invoke.

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

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

Input schema covers both parameters fully (package name, version) and the description mostly restates the schema's own descriptions (e.g., version defaults to latest). Since schema coverage is 100%, baseline is 3, and the description adds no additional parameter meaning.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, with specific verb ('scan') and resource (dependency). It differentiates itself by listing the exact data sources and output fields, making it distinct from any sibling tool.

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

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

Explicitly states when to use ('whenever an agent asks is X safe / popular / small'), and provides a clear exclusion for non-NPM ecosystems (use deps.dev:version directly). This gives the agent unambiguous guidance.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds implementation details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging. It also mentions verifiable offsets for quotes, adding useful behavioral context. 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?

Three tightly written sentences. Starts with the core action, moves to use case, and ends with technical details. No filler; every clause adds value. The structure is well front-loaded, with the most important information first.

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

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

No output schema exists, but the description explicitly states the return format: top-N passages with character offsets and similarity scores. It also covers the 200K cap, truncation flag, and pairing with ask_pipeworx_grounded, providing enough context for an agent to invoke the tool correctly. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with each parameter (text, limit, query) having a description. The description adds workflow context (pass already-pulled text, natural-language query) and reinforces the 200K char limit, but doesn't add meaning beyond what the schema already documents. However, it clarifies how the parameters interact, giving a 4 instead of 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?

Clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. Differentiates itself from sibling tools by emphasizing it operates on already-fetched text, and explicitly mentions returning top-N passages with offsets and scores. The pairing with ask_pipeworx_grounded further distinguishes 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context and returns only relevant passages. Provides a direct alternative/companion relationship with ask_pipeworx_grounded, suggesting a workflow. This gives the agent clear decision criteria for when to use this tool 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?

The description adds significant behavioral context beyond annotations: requires OAuth, returns subscription id, feed is always on, SMS requires verified phone with 10/day cap, and schema details include webhook auto-disable and one-time signing secret. These are meaningful operational traits not implied by readOnly/destructive/idempotent hints.

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

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

The description is front-loaded with purpose, then auth, then types, then delivery—well-structured and compact. Every sentence adds value, including concrete examples and constraints.

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 nested objects and no output schema, the description covers prerequisites, supported types with examples, delivery channels, and return value. It is sufficiently complete to guide invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with type-specific examples. The description adds some explanatory color (e.g., 'items:["5.02"] = officer change') but largely mirrors the schema, offering minimal additional meaning.

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+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by stating it returns a new subscription 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?

Usage is implied from the purpose but no explicit alternatives or when-not-to-use are provided. It mentions prerequisites (OAuth account) and alternative pull methods for the feed, but doesn't direct to sibling tools for listing or canceling subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond that. It specifies the return format (category-bucketed example questions with tool + argument shape), the categories covered, the effect of the topic parameter, and that it draws from the live catalog of thousands of tools. 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 effective; it packs the purpose, output, parameter behavior, and usage guidance into one long paragraph. Every sentence contributes, but the structure could be improved with bullet points or shorter sentences. It is appropriately sized for the information it conveys.

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

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

Given that there is no output schema, the description fully explains what the tool returns and how to invoke it. It covers the main use case, the topic parameter, and the source of the suggestions, making it complete for an agent to decide when and how to call it. The lack of mention of pagination or rate limits is not a gap for this onboarding 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 schema describes the single `topic` parameter with a list of possible values, but the description adds meaningful guidance: examples ('finance', 'pharma', 'betting'), instruction to omit for a cross-category spread, and the note that topic focuses the output. This goes well beyond the schema's basic 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's purpose: it is the onboarding entry point for an agent to discover what questions are worth asking, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and naming the meta-tools it teaches you to call (ask_pipeworx, entity_profile, compare_entities). The verb 'suggest' and resource 'questions' are specific.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic filtering and the default behavior when called with no arguments, giving the agent clear context for choosing this tool 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?

Even with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable details: ownership enforcement, row deactivation (not deletion), and preservation of historical events via recent_alerts. This meaningfully clarifies the tool's 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 two sentences, front-loaded with the main action, and contains no filler or redundancy. Every sentence contributes useful detail.

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 fully covers the action, constraint, and side effects. The mention of recent_alerts also helps the agent understand the broader context.

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

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

Schema coverage is 100%, with the parameter id already described as 'Subscription id (uuid) returned by subscribe.' The description only echoes 'by id' and adds no new semantic information about the parameter, 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 clearly states 'Cancel a subscription by id' — a specific verb with a resource and method. It also distinguishes the tool's effect (deactivation rather than deletion) from related tools like recent_alerts.

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 for when to use (cancel a subscription you own) and mentions ownership enforcement. However, it does not explicitly contrast with sibling tools like subscribe or list_subscriptions, so it stops short of full alternative guidance.

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

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

Beyond the safety annotations, the description discloses critical behavioral nuances: the meaning of 'could_not_verify' as a pipeline failure (not evidence), the distinction with 'unsupported', the existence of an error payload, and the dual structured/grounded pipeline. This is valuable, non-obvious context that agents need.

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

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

The description is longer than average but every sentence adds substance—examples, pipeline details, verdict semantics, and caller warnings. It is well-structured with an 'IMPORTANT for callers' note, though it could be tightened slightly for readability 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?

Despite lacking an output schema, the description fully describes return values (verdict, actual value, reasoning, error fields) and explains edge cases (could_not_verify vs. unsupported). It also covers the tool's relationship to an alternative multi-step workflow, making it very complete for a tool of this complexity.

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

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

While the schema covers both parameters with descriptions, the tool description adds important semantic details: tolerance_pct overrides claim wording, is capped at 5 by default, and 'set 1–2 for hallucination detection.' This goes beyond the schema's documentation and helps agents choose correct 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 states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this tool from siblings by focusing on fact-checking with verdicts, and even notes that it replaces 4–6 sequential calls, making its niche unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the conditional routing for financial vs. other claims, but does not explicitly name alternative tools or provide exclusions, so it falls slightly 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 cover safety (readOnly, non-destructive, idempotent). The description adds that it returns validity and format details, which is useful but does not disclose limitations such as not checking real-world existence or handling of whitespace/case. 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?

A single, tightly worded sentence that immediately conveys the tool's purpose and output. No filler, front-loaded with the key action, and includes a concrete example.

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

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

For a simple single-parameter validator with rich annotations (readOnly, idempotent) and an output schema, the description provides enough context. It could optionally mention edge cases like case sensitivity or non-existence checks, but the tool's simplicity makes the description largely complete.

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

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

Schema description coverage is 100% with an example already provided. The description repeats the postcode example, adding no significant meaning beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description uses the specific verb 'Validate' with a clear resource 'UK postcode format' and provides an example. It distinguishes from sibling tools like lookup_postcode, which focuses on retrieving data, and random_postcode, which generates postcodes.

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

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

The description implies usage for format validation but does not explicitly state when to use this tool over alternatives such as lookup_postcode or nearest_postcodes. No exclusions or alternative tool guidance is provided, leaving usage context implicit.

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