Phillips

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavior beyond that: the default model (Llama-3.3-70b), the free tier, the cost implication of passing _apiKey ("you pay Anthropic directly"), and the external call to api.anthropic.com. This enriches the annotations without contradicting them.

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

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

The main action is front-loaded in the first sentence, and each subsequent sentence earns its place: cost/model behavior, return format, and use cases. It is slightly dense — the cost point and return format could be tightened — but there is no fluff or redundancy beyond a minor BYO-key/pay overlap.

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

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

With no output schema present, the description correctly fills the gap by specifying the return shape (per-model score, confidence, signals, raw_response + combined view). It also covers cost, defaults, and use cases. Minor gaps remain: the meaning/orientation of the 0-100 score (higher = better visibility?) and failure behavior when anthropic is requested without _apiKey are not explained.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters with examples and format hints. The description adds only marginal enrichment — the concrete default model identity (Llama-3.3-70b) and the free-vs-paid cost distinction for models/_apiKey. This is a solid baseline with slight bonus, but the schema carries the heavy lifting.

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 specific verbs and resources: "Probe one or more LLMs... and score visibility (0-100) per model." It names the subject (business/brand/product/topic), the action (probe + score), and the output shape, making it clearly distinguishable from Q&A siblings like ask_pipeworx and research tools like deep_research.

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

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

The final sentence gives concrete use cases ("AI-marketing audits, pre-launch brand checks, competitive monitoring"), and the second sentence provides operational guidance on model selection (default free model vs. BYO Anthropic key). However, it does not name alternative tools or state when not to use it, e.g., versus the sibling scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds meaningful behavioral context: it routes to 5,908 tools across 1,540 verified sources, automatically fills arguments, and returns structured answers with stable citation URIs. It doesn't mention rate limits or failure modes, but it goes beyond the annotations without contradicting them.

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

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

The description is long but front-loaded with a strong directive, then delivers scope, routing behavior, trigger phrases, and examples in a logical order. The final note about breaking-news routing is slightly awkwardly placed but adds useful nuance. There is minimal fluff relative to the amount of guidance provided.

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 an open-world router with no output schema, the description is exceptionally complete: domains, trigger phrases, examples, routing mechanism, and return format with citation URIs are all covered. It could still mention differences from ask_pipeworx_beta/ask_pipeworx_grounded and potential error behavior, but an agent has enough context to invoke this tool correctly.

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

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

The input schema documents all six parameters with 100% coverage, including aliases and the natural-language semantics of question. The description's examples illustrate acceptable input values but don't add novel parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate here.

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 directive to prefer this tool over web search for a broad set of factual/current-data questions, then states the core behavior: routes the question to one of 5,908 tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. This is a specific verb+resource combination that distinguishes it from web search and specialized siblings.

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

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

The description provides explicit trigger phrases ("what is", "look up", "find", "get the latest", "how much", "current"), concrete examples, and the directive "START HERE for most questions". It also names web search as the alternative to prefer this tool over, making the selection rule explicit. It doesn't distinguish among ask_pipeworx_beta/grounded, but the broad router role makes that less critical.

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 test-only, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it is an experimental edge with candidate routing improvements enabled live when under test, currently none active, and results are compared against the stable router. This clarifies the volatile nature of the tool without contradicting the annotations.

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

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

The description is four sentences with no filler. Key information is front-loaded: beta identity, identical functionality, current state, and usage guidance. Each sentence earns its place, covering the critical nuances of an experimental tool without unnecessary verbosity.

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

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

The description provides enough context for an agent to correctly invoke the tool: it is identical to ask_pipeworx, so the agent can delegate understanding to that sibling. It covers current status, usage, and fallback behavior. It does not explain the response shape, but the statement 'same response shape' delegates that to the known sibling, which is acceptable. A slight gap remains for agents completely unfamiliar with ask_pipeworx.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds no parameter-level detail beyond saying 'same arguments as ask_pipeworx', which is not specific to this schema. With high schema coverage, a baseline of 3 is appropriate, and the description neither compensates nor detracts.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by emphasizing the experimental routing candidate aspect, so an agent can tell what it does. It falls short of 5 because it does not explicitly differentiate from the 'ask_pipeworx_grounded' sibling and assumes some familiarity with what a 'router' means.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and gives the condition (wanting newest routing), along with the clarification that it is a full working router, not a fallback stub. It does not list formal exclusions, but the context is clear enough for correct 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=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, and the description adds substantial behavior beyond them: the exact success return shape, the explicit refusal contract with its full refusal_reason enum ('not_in_source'|'no_tool_match'|'tool_error'|'data_truncated'|'llm_error'), the grounded-extraction guarantee, and the extra LLM call cost. 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 (roughly 130 words) but every sentence earns its place: it moves logically from purpose to mechanism to return contract to refusal contract to usage guidance to cost tradeoff. It is front-loaded with the core differentiator. Slightly long, but the information density justifies the length.

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

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

This is a complex QA tool with no output schema, so the description must document the return contract itself — and it does, completely: success payload, refusal payload, and refusal_reason enum values. Combined with annotations covering the safety profile (read-only, idempotent, non-destructive, open-world), nothing an agent needs to invoke it correctly or interpret its result 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% and the schema already documents the question parameter and its five aliases thoroughly. The description adds mild context — that the question drives routing across 5,908 tools and gets filled into arguments — but provides no parameter-specific syntax or formatting details beyond the schema. Baseline 3 is appropriate when the schema carries the semantic load.

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, differentiating claim: 'Hallucination-resistant answer mode for high-stakes reads.' It names the verb (answer), the resource (Pipeworx data across 5,908 tools and 1540 sources), and the distinguishing mechanism (extracts the answer using ONLY what the tool result contains). It explicitly contrasts with the sibling ask_pipeworx ('Same routing... then EXTRACTS'), so an agent can tell them apart without opening the schema.

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

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

Usage guidance is explicit and actionable: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes domains listed (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and the tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' Both when-to-use and when-not-to-use are stated.

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 the description layers extensive behavior: parallel fan-out, status codes (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), news fallback/retry fields, and resolution-rule risk including the 50¢ void settlement. It describes what gets suppressed on low confidence, which is exactly the kind of context annotations cannot 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 text is long, but it is organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) and every block adds operationally relevant detail. The core purpose is front-loaded in the first sentence before any lists or examples.

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

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

This tool has no output schema, so the description carries the full burden of explaining return values. It specifies result.market, result.analysis, result.evidence, resolver confidence fields, parent_event, news fallback flags, and blocking statuses, covering edge cases and tradeability. Nothing critical for correct invocation or output interpretation 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%: market, depth, and include_raw are all documented in the schema, so the baseline is 3. The description adds interpretation of the market parameter (slug/URL/question text) and mentions fan-out, but does not explain depth or include_raw beyond what the schema already says. It adds some meaning but doesn't compensate for a missing 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 ('Research'), a resource ('a Polymarket bet'), and a defined scope ('pulling the relevant Pipeworx data for it in one call'). It explains the resolution/classification/fan-out pipeline and gives explicit example queries like 'should I bet on X', which clearly differentiates it from generic research siblings like deep_research or validate_claim.

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 user intents: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also covers safety paths and blocking statuses, but does not name sibling tools or state when NOT to use this tool, leaving some routing comparison to the agent.

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, the description reveals important runtime behavior: it executes as one parallel call, pulls specific financial fields from SEC EDGAR/XBRL or FAERS data, handles off-calendar fiscal years, sorts results by the primary metric, and returns paired data with citation URIs. This is far more than the annotations alone provide.

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

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

The description is dense but every sentence earns its place: trigger phrases, selection guidance, type-specific data sources, output ordering, and citations. Important guidance is front-loaded with the natural-language triggers and the 'ALWAYS PREFER' instruction.

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 tells the agent what data will come back, how results are ordered, what citations are included, and why this tool beats sequential lookups. An agent has enough information to select and invoke it correctly without needing 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?

Although the schema already covers both parameters at 100%, the description adds meaningful semantics: it explains what each type value retrieves, gives concrete ticker and drug examples, and clarifies that values must be 2–5 entities. This goes well beyond the schema's minimal descriptions.

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

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

The description opens with concrete user phrasings ('Compare X and Y' / 'X vs Y' / 'rank these companies') and then states the core operation: side-by-side comparison of 2–5 companies or drugs in one parallel call. It also distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear selection rule. It gives trigger examples, the entity types, the count range, and the value proposition ('Replaces 8–15 sequential lookups'), so an agent knows exactly 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?

Annotations already flag readOnly/idempotent, and the description adds substantial behavior beyond: the facet-decomposition and parallel-routing process, the findings packet shape (verbatim evidence + confidence + source + fetched_at + citation, gaps[], contradictions[]), the "never invented" honesty guarantee, the citation_uri-only-when-fetchable caveat, and concrete latency expectations (15-60s, up to ~90s for thorough). It also discloses the account/paid-plan requirement, which annotations do not cover.

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?

Long but densely packed and logically ordered — auth constraint first, then identity (NOT open-web), then behavior, when-to-use, return format, and latency. Two minor redundancies (the ask_pipeworx routing and contradictions[] scanning are each stated twice) keep it from being maximally tight.

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

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

With no output schema, the description carries the full burden for return-value semantics and meets it: findings packet fields, gaps[], contradictions[], hop, and the citation-uri-only-when-fetchable caveat are all spelled out. For a tool of this complexity (parallel tool routing, tiered depth, latency, auth), nothing an agent needs to invoke it correctly or set expectations 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% and the schema already documents both parameters, including per-depth facet counts. The description adds operational meaning the schema lacks: depth:"thorough" requires a paid plan (which should influence value selection), latency varies by depth, and example question phrasings demonstrate what a good `question` looks like. That pushes it modestly above the high-coverage baseline.

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

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

States a specific verb and resource: "Grounded multi-source research across Pipeworx's 1540 STRUCTURED data sources ... in ONE call." It actively distinguishes itself from siblings by declaring "this is NOT open-web search" and routing single-lookup users to ask_pipeworx, so an agent can differentiate it at a glance.

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

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

Gives explicit conditions: "If you are not signed in, use ask_pipeworx instead — it works on every tier" and "For a single lookup use ask_pipeworx instead." It also states when it is the right choice: "Best for broad/multi-part questions over structured data," backed by concrete example questions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds substantial value by disclosing the exact return shape: top-N relevant tools with names, descriptions, full input schemas and curated examples, and that results are ready to call without a second schema lookup. This is especially useful because no output schema is provided.

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, followed by use cases, return value, and a clear first-step instruction. Each sentence earns its place, and the domain list is dense but directly relevant.

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 discovery tool with straightforward parameters, high schema coverage, and no output schema, the description fully compensates: it explains what the tool does, when to use it, and exactly what the response contains. Nothing materially needed by an agent 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%, and the schema already documents query, all aliases, and limit defaults/max. The description only restates that the input is a natural-language description of a data/task, adding no parameter-level meaning beyond the schema.

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

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

The first sentence names a specific action and resource: 'Find tools by describing the data or task.' It also lists concrete domains and frames the tool as a discovery/meta tool, which distinguishes it from the many operational sibling tools and clarifies it is not itself a domain-specific search.

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

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

The description explicitly says when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST when many tools are available. It does not name specific alternative tools or give explicit exclusions, though 'not just one answer' hints at when a direct tool is more appropriate.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds genuinely useful behavioral context: one parallel call, USPTO soft-fail behavior, FDA small-molecule expected-empty case, resolved:false + notes for private companies, and sources_used/sources_failed semantics. This goes well beyond what annotations provide, though it doesn't document rate limits or latency.

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; the trigger examples are front-loaded, then the fan-out list, then return semantics. It earns its length by covering many data-source edge cases and expected failures. It could be tightened with bullets, but the content is purposeful and 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?

Given the tool's broad fan-out and no output schema, the description covers inputs, resolution behavior, per-source quirks, and failure semantics well. The main gaps are missing names or numbers of sibling tools that would further disambiguate it from deep_research or compare_entities, and no explicit mention of typical latency or upper bound on sources.

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 fully, including the interchangeability of type values and the accepted value shapes. The description reinforces the same semantics and adds the resolved_from/resolved_to nuance for name-based values, but its baseline is the schema doing the heavy lifting.

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 trigger phrases and a clear verb-object pair ('full cross-source profile of a US public company'). It names the resource and the fan-out sources, and explicitly contrasts with chaining single-pack lookups, which differentiates it from siblings like deep_research, compare_entities, and 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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', gives accepted input shapes, and explains the empty-section semantics and private-company fallback. This gives clear when-to-use and when-not-to-fail guidance.

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

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

The explicit 'Delete' verb aligns with the annotations destructiveHint=true and readOnlyHint=false, and key-based deletion is consistent with idempotentHint=true. No contradiction. The description adds context beyond the flags by scoping the target to 'previously stored memory by key' and by noting the sensitive-data use case, though it does not describe edge-case behavior like deleting a missing key.

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 short sentences with the core action front-loaded, followed by usage triggers and sibling pairing. Every sentence earns its place; there is no filler or redundant restatement of the schema.

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

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

For a one-parameter delete action, the description covers purpose, usage conditions, sibling context, and destructive nature; annotations cover idempotency and mutation, and the schema covers the parameter with an example. Nothing material an agent needs 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% and the schema already documents key as 'Memory key to delete' with an example. The description merely restates the mechanism as 'by key,' adding no format, lifecycle, or edge-case semantics beyond what the schema provides. 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?

States a specific verb ('Delete') with a specific resource ('previously stored memory') and the mechanism ('by key'). The description also names the paired sibling tools remember and recall, making the tool's role in the memory family 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?

Gives three explicit trigger conditions: stale context, task complete, and clearing sensitive data previously saved by the agent. Names the related tools remember and recall as its pair, though it stops short of an explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety/purity of the operation is established. The description adds valuable behavioral context: it fetches the page, extracts specific elements, and emits a single text blob ready for site-root deployment. It does not disclose edge cases (e.g., inaccessible URLs), but the annotation coverage 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 three tight sentences: purpose, process/output, and use cases. Every sentence earns its place, the core action is front-loaded, and the use-case list communicates practical value without drifting into irrelevant 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?

This is a simple tool with only two parameters, full schema coverage, and annotations covering safety and idempotence. The description explicitly states the output format and where to place the result, compensating for the absence of an output schema. An agent has everything needed to invoke it correctly for typical use cases.

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

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

Schema description coverage is 100%: url and max_links are both explained, including max_links' default (25) and maximum (50). The description adds no meaning beyond 'any URL' and does not mention max_links at all, so it stays at the baseline of 3 where the schema carries the parameter documentation.

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: 'Generate a production-ready llms.txt file for any URL.' It clearly details the process (fetches page, extracts title/description/key links) and the exact output (single text blob in standard llms.txt markdown), making it easy to distinguish from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The 'Useful for:' section provides concrete scenarios for when to invoke this tool: indexing a client's site, drafting for one's own project, or auditing how an AI crawler sees a competitor. It does not explicitly name alternative tools or describe when not to use it, but the context is sufficiently clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail by scoping to the caller's active subscriptions and enumerating the returned fields, which goes beyond what annotations provide.

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

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

Two sentences carry all the essential information: what the tool lists, what it returns, and when to use it. The primary action is front-loaded and there is no redundant wording.

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 list tool with one optional documented parameter and no output schema, the description is complete: it names the resource scope, the returned fields, and the use cases. Nothing critical 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 single optional include_inactive parameter is already fully documented. The description does not add further parameter context, which matches the baseline of 3 for high schema coverage.

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

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

The description names a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact return fields, making the operation concrete and clearly distinct 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 explicitly says when to use this tool: 'review what you're monitoring before adding more' and 'find an id to cancel.' It gives clear context, though it does not explicitly name sibling alternatives 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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds concrete detail about what will be returned, including realized price composition, hammer price, estimate range, sale date, and image, which helps the agent set expectations 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 a single front-loaded sentence that names the tool's purpose, then enumerates the returned fields, followed by one short sentence explaining the dependency. Every sentence earns its place with no wasted words.

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

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

For a read-only single-lot detail tool, the description covers the input dependency, the scope, and the content of the response. With annotations handling side-effect safety and schema handling parameter semantics, nothing essential 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, including the decorative nature of slug. The description mostly restates the lot_id provenance from phillips_results_search without adding new parameter-level 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 specific verb ('Full detail for one Phillips lot') and a clear resource scope, then enumerates the exact fields returned. It is clearly distinguished from the sibling phillips_results_search by targeting a single lot rather than search results.

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 correct workflow by stating that it takes the lot_id from phillips_results_search, which tells an agent when to use it: after a search has produced a lot id. It does not explicitly list exclusions or contrast with other alternatives, but the dependency is clear enough for correct 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 read-only/idempotent, and the description adds genuine behavioral context: the keyword search is closed to crawlers, so it reads the artist index page; results are per-maker and limited to the 24 most recent past lots of the reported total. This discloses important limitations and data-source workarounds beyond the structured hints.

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

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

The description is dense but well-structured: it front-loads the purpose and return fields, then explains the crawler constraint, then the optional filter. Every sentence adds information without repetition or filler.

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

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

For a tool with no output schema, the description enumerates the returned fields (realized price, estimate, currency, lot/sale number, saleroom, department, sale date) and flags the key limitation (24 most recent reported lots). Combined with annotations, an agent has enough context to select and invoke the tool correctly.

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

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

With 100% schema coverage, the schema already documents all parameters. The description adds a meaningful semantic: that the 24-lot limit is not merely a client-side cap but the total accessible dataset per maker, and that category narrowing matches department/saleroom/sale/lot title. However, most parameter-specific meaning remains in the schema, so this is a modest increment over baseline.

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

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

The description states a specific verb-resource pairing: 'Look up realized prices for an artist or maker in Phillips' past-auction results.' It names the resource (Phillips past-auction results), the output (realized price, estimate, currency, etc.), and distinguishes itself from the sibling phillips_lot_details by focusing on per-maker recent lots rather than individual lot details.

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

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

The description provides clear context for use: it is for looking up realized prices per maker and can be narrowed by category/department with examples. It explains why it resolves names via the artist index rather than keyword search, which sets expectations. It does not explicitly mention sibling alternatives or when not to use it, so it lacks exclusion 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 are all false, so the description carries the burden—and it delivers. It discloses the anonymous claim_token flow, the behavior of passing the token later to read resolution status, rate limiting to 5 per identifier per day, freedom from quota, and the digest/roadmap impact. 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 a single dense paragraph, but every sentence earns its place: scope, exclusions, token workflow, rate limit, and content guidance are all non-redundant. Slight restructuring into bullets or shorter paragraphs would improve scannability, but it is already front-loaded and free of fluff.

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

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

For a complex feedback tool with nested objects, enum types, and no output schema, the description is remarkably complete. It explains what the response token means, how to follow up, what to include in the message, what not to include, rate limits, and scope. An agent has everything needed to invoke it correctly and to route unrelated feedback elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining how to frame the message (in terms of Pipeworx tools/packs, not end-user prompts) and how claim_token is used round-trip. It does not relist parameter names, but it enriches the practical meaning of 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 precise verb and resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly differentiates this from the sibling ask_* tools by specifying this is a feedback channel for Pipeworx itself, not a data-querying 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?

It explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to use it (issues with tools from other MCP servers, which should be filed with that server). This is the strongest possible usage guidance: concrete conditions, explicit exclusions, and a clear alternative action.

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 mark this as readOnly, openWorld, idempotent, and non-destructive, and the description adds meaningful context beyond that: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This gives the agent a strong behavioral model of what it is querying.

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

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

The description is compact and well-structured, front-loading the core purpose and then using a numbered list for use cases and a short final sentence for technical caveats. It contains minor redundancy around 'hot/current' language, but every sentence earns its place and the structure aids skimmability.

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

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

With only one optional parameter, a fully descriptive schema, and strong annotations, the description covers what an agent needs to invoke the tool correctly: what it returns, the available windows, the caching behavior, and the privacy/aggregation properties. Since there is no output schema, the description's mention of 'top tools, top packs, and total call volume' provides sufficient return-value context.

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

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

The input schema already provides 100% coverage for the single 'window' parameter, including the enum values, the default, and guidance on short vs long windows. The tool description only restates the window options and does not add unique parameter semantics beyond what the schema already covers, so the baseline of 3 is appropriate.

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

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

The description opens with a specific, question-shaped statement — 'What other AI agents are calling on Pipeworx right now' — then names the concrete outputs: top tools, top packs, and total call volume. This clearly positions it as a meta/trending tool, distinct from related siblings like discover_tools, without needing to open the schema.

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

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

The description gives three explicit, practical use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with broader agent demand. It does not state when not to use this tool or explicitly name an alternative, so it falls just short of the top bar, but the usage context is clear and actionable.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description goes far beyond that. It discloses the semantic similarity threshold (≥0.30 Jaccard), the placeholder-filter behavior, the partition_check mechanics, and the critical fill-check caveat that theoretical edge may not be realizable in the CLOB book. This is rich behavioral context that annotations alone could not provide.

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

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

The description is long but highly structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every added detail serves a functional need for correct invocation or interpretation, and the formatting makes it 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?

Despite having no output schema, the description explicitly describes the response shape (opportunities[], partition_check fields, fill_check outputs), the filters, and the failure conditions. It is complete enough for an agent to call the tool correctly and interpret results, including when to avoid trading.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions. The tool description adds concrete examples for each parameter, clarifies accepted URL formats, and explains the behavioral difference between event and topic modes, which enriches the schema without merely repeating it.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then clearly differentiates three invocation modes (no-arg trending scan, event, topic) and even names a sibling tool (polymarket_fill_risk) for custom sizing, making it easy to distinguish from adjacent tools.

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

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

The description gives explicit when-to-use guidance: no args for trending_scan, 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains what each mode is best for, when the arbitrage signal should not be traded (realizable_edge_pp <= 0), and directs to polymarket_fill_risk for custom sizing.

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?

With annotations already declaring readOnly/openWorld/idempotent, the description still adds substantial behavioral context: exact response segments, per-opportunity fields (edge_pp_net, kelly fractions, spreads), a 24h-move warning that an edge may already be priced in, the per-leg Kelly design quirk for partition arbs, diagnostics funnel counters, and 1h caching keyed on all knobs. 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 opening is front-loaded and every cluster of information is dense, but the description is a single wall-of-text paragraph with all-caps segments and parentheticals that are hard to scan. Some details (per-sport alpha values, 'gates relaxed Run 8' history) are irrelevant for tool selection or invocation and make it longer than needed.

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 return values. It fully specifies the top-level by_segment structure, fed_candidates/fed_note, _diagnostics with funnel counters, the fields on every opportunity, and how all nine knobs affect results. An agent has enough to call the tool and interpret its output correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by grouping knobs into 'TRADEABLE-EDGE KNOBS,' explaining that min_liquidity/max_spread_pp drop unrealizable edges, clarifying that min_partition_leg_kelly applies to per-leg Kelly instead of parent-level, and noting that caching is keyed on all knobs. This is meaningful extra context without restating defaults.

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 verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The intended use case is explicit ('what should I bet on today'), and the detailed model-family breakdown makes the tool's role unmistakable, distinguishing it clearly from arbitrage or tracker siblings even without naming them.

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

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

The description gives clear when-to-use context: agents discover daily opportunities without paging hundreds of markets. It also explains the tradeable-edge knobs and why Fed bets are excluded, but it never explicitly names alternative tools or states when to prefer them, leaving some routing to inference.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive. The description goes well beyond annotations by disclosing concrete behavioral traits: snapshots are written only on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage rather than intraday, and expired opportunities are those gone from the latest snapshot. No contradiction exists.

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

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

The description is long but densely informative and well-structured into purpose, arguments, response shape, and limits. Every clause carries operational value, such as the sign convention for edge_pp_net, the median lifespan as a competition clock, and snapshot date gaps. This is not padding; it earns its length.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It defines tracked[], expired[], snapshot_dates[], explains trend and decay fields, clarifies the sign of edge_pp_net, and covers edge cases like gaps and TTL. For a two-parameter, read-only tool, this is complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the input schema already documents both days and window. The description adds only mild context: days is the lookback with default/max, and window refers to the polymarket_edges window family. This does not meaningfully exceed the schema's explanations, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots and explicitly frames the question it answers: 'how long has this edge existed and is it shrinking?' This is specific and distinguishes it from the sibling polymarket_edges tool, which presumably provides current edge data rather than historical tracking.

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 does not explicitly say 'use this instead of X', but it strongly implies when this tool is appropriate: for historical edge persistence and decay analysis across snapshot history, whereas polymarket_edges would be the current-edge sibling. It also sets expectations with limits like the 60-day TTL and snapshot-gap behavior, giving an agent enough context to select it correctly.

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, destructiveHint=false, so the agent knows this is a safe read-only check. The description adds meaningful behavioral context: it walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), identifies thin legs, and names forced-directional-risk legs. It also explains the dominant loss mode (partial basket fills → unhedged directional position). It doesn't fully disclose rate-limit or data-freshness behavior, but it exceeds the annotation baseline.

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 information-dense but formatted as a single long block of text. It front-loads the core purpose, then covers modes, parameters, and usage guidance. However, it could benefit from paragraph or bullet separation to improve scannability; the density makes it slightly harder to parse quickly.

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

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

Despite lacking an output schema, the description enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites (market or event slug/URL), defaults, and failure semantics. Nothing essential is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds value by explaining the interpretation of size_usd in each mode ('max spend on buys, target proceeds on sells' in single-market; 'settlement notional S (shares per leg; each share pays $1)' in basket), and clarifies that side defaults to auto from partition sum in basket mode. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states a specific verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and distinguishes two modes (single-market vs basket). It explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) in its usage guidance, making it easy to select correctly.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable; partial fills create unhedged directional risk), which helps an agent decide between this and alternatives.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing nuanced behaviors: compatibility warnings can be non-empty even when matches exist, legs with 'unknown' metric_type are never paired, temporal_alignment null means unknown rather than aligned, and fees are gross because Kalshi's fee schedule is not modeled. This is rich, non-obvious behavior disclosed upfront.

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

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

The description is long but well-structured and front-loaded with the core purpose, then organized into modes, response, safety fields, and caveats. Every section earns its place, though some phrases are repetitive and the overall length could be tightened for faster agent parsing.

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

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

With no output schema, the description carries the full burden of explaining the response shape, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility codes, skipped fields, temporal alignment semantics, fees_note, and counters. Nothing critical seems missing for an agent to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter semantics by explaining topic as pre-mapped shortcuts, explicit ticker/slug as custom pairings, and that 'BOTH modes run the identical token-overlap matcher'. There is a small ambiguity about whether one explicit parameter alone can override a topic side or whether both are required for custom mode, preventing a 5.

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

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

Description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', a specific verb+resource statement that clearly identifies what the tool computes. It also describes two distinct invocation modes, which further disambiguates it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description clearly explains when to use each mode ('TWO MODES: topic ... OR explicit kalshi_event_ticker + polymarket_event_slug') and warns that 'pre-mapped ≠ tradeable' and 'Real cross-venue spreads are rarer than the macro-shortcut list suggests'. It stops short of explicitly naming sibling tools and stating when not to use them, so it earns a 4 rather than 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 convey read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those: the omit-key listing mode, the scoping of memory to an identifier, and the relationship to remember/forget. It does not describe missing-key or empty-result behavior, but annotations lower 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 three sentences with no filler. It front-loads the core behavior, then adds use-case context, then scoping and sibling-tool relationships. Every sentence contributes useful information.

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

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

For a simple optional-parameter lookup tool with read-only and idempotent annotations, the description is complete: it covers both invocation modes, gives realistic use examples, explains scoping, and points to related tools. No critical information is missing for an agent to call it correctly.

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

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

The input schema already fully documents the single optional key parameter, including the omit-to-list behavior, so schema coverage is 100%. The description reinforces this but adds little semantic detail beyond what the schema states, aside from concrete examples of what kind of values are stored.

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 leads with a crisp verb and object combination: 'Retrieve a value previously saved via remember, or list all saved keys.' It also names the sibling memory tools (remember/forget) and distinguishes this tool by its read-only lookup 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?

It clearly explains when to use the tool: to look up stored context without recomputing it. It also points to siblings by saying 'Pair with remember to save, forget to delete,' though it stops short of an explicit if-then exclusion like 'do not use for saving.'

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond that: return fields (source, citation_uri, raw payload), the mark_read side effect that affects subsequent calls, and polling suitability. No contradiction with annotations is present.

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

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

Four dense sentences, each earning its place: the opening states the core action, the second details return contents, the third covers filtering and mark_read semantics, and the fourth mentions polling and an alternative endpoint. It is front-loaded and contains no filler.

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

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

Without an output schema, the description compensates by describing the return payload. It also covers filtering, mark_read behavior, polling, and alternative access. Minor omissions like limit defaults and unread_only details are already present in the schema, so the description is nearly complete for a read-oriented tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO format for since, and explaining the consequence of mark_read ('so the next call only shows newer ones'). This exceeds what the schema descriptions alone provide.

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

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

The description uses a specific verb and resource ('Pull fired events from your subscription feed') and clarifies it returns recent alerts from the evaluator's persisted feed. It is conceptually distinct from siblings like list_subscriptions or recent_changes, but it never explicitly names or differentiates those alternative tools, so it falls short of a 5.

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

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

The description gives clear usage context: it says polling works fine, explains the mark_read pattern for advancing to newer events, and points to the GET registry.pipeworx.io/alerts.json endpoint as an alternative for scripts and dashboards. However, it does not explicitly contrast with sibling MCP tools, so it lacks full when-not-to-use guidance.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description still adds substantial context: the parallel fan-out to three sources, the GDELT→GNews fallback trigger conditions, and the USPTO PatentsView sunset with soft-fail behavior. It also discloses the return shape (changes[] grouped by source, total_changes, pipeworx:// URIs). No contradiction with annotations.

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

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

Dense but every sentence earns its place: the leading query examples aid intent matching, the fan-out and fallback details set correct expectations, and the closing sentence routes to the sibling. It is front-loaded with user phrasing before the technical machinery, and the length is proportionate to the tool's complexity.

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

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

Despite having no output schema, the description discloses the top-level return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs) so the agent knows what to expect. It covers sources, failure modes, since formats, and the sibling distinction — complete for a high-complexity, multi-source read tool. The only minor gap is that fields inside a changes[] item aren't enumerated.

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 and the schema already documents type, since, and value. The description adds only a usage preset ('Use "30d" or "1m" for typical monitoring') and restates the since shorthand formats; this is marginal value, not substantial new meaning beyond the schema.

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

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

States a specific verb and resource: 'change feed for a company in the last N days/weeks/months', backed by six natural-language query patterns. It distinguishes itself from the sibling entity_profile by explicit contrast (time-windowed changes vs static profile), and its multi-source scope (SEC/GDELT/GNews/USPTO) clearly separates it from 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?

Explicitly names the alternative and the condition that selects it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also prescribes a default window ('Use "30d" or "1m" for typical monitoring') and documents the fallback policy (GDELT preferred, GNews when rate-limited or 5xx).

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 write semantics (readOnlyHint=false), idempotency, and non-destructiveness. The description adds genuinely new behavioral context beyond those annotations: the key-value store is 'scoped by your identifier' and retention is auth-dependent — persistent for authenticated users versus 24 hours for anonymous sessions. 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?

Five sentences, each carrying distinct information: purpose, when-to-use triggers, storage model, retention policy, and sibling routing. The opening is front-loaded with the verb and resource, though the final pairing clause ('forget to delete') reads slightly ambiguously despite the sibling literally being named 'forget'.

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

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

For a simple two-parameter tool with strong annotations and 100% schema coverage, the description covers purpose, usage triggers, memory scoping, and retention semantics. The only notable omission is any statement of the return value or confirmation behavior, which is minor given the absence of an output schema.

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

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

Schema description coverage is 100%, with both key and value fully described in the input schema including format examples. The description reinforces the key-value storage model but adds no parameter-level detail beyond what the schema already provides, 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 opens with a specific verb and resource — 'Save data the agent will need to reuse later' — and explicitly names the sibling operations ('Pair with recall to retrieve later, forget to delete'), so an agent can distinguish it from recall and forget without opening their schemas. Concrete examples (resolved ticker, target address, user preference, research subject) make the tool's job unmistakable.

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

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

The description gives an explicit trigger condition — 'Use when you discover something worth carrying forward' — with concrete examples of what qualifies and the motivating rationale ('so you don't have to look it up again'). It routes to the related siblings (recall for retrieval, forget for deletion), though it stops short of stating explicit when-not conditions, leaving exclusion largely to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds substantial behavior beyond them: ambiguity handling ("asserts nothing and returns figi_candidates"), graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), explicit reporting of failures ("an identifier that could NOT be resolved is stated explicitly under `unresolved` rather than omitted"), source-labelled identifiers, and the internal cascade across endpoints. No contradiction with the read-only/idempotent annotations exists — the description is consistent with them.

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

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

The definition is front-loaded with purpose and trigger examples, and nearly every sentence earns its place. However, it is a dense wall of prose: the "company" type is explained in a single ~200-word run-on sentence with deep parentheticals (FIGI candidates, bond behavior, ISIN mapping all nested inside), which makes parsing harder than necessary. Reformatting into bullets or shorter sentences would preserve all content while improving readability.

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, and it largely delivers: it names response elements (figi_candidates for ambiguous matches, `unresolved` for failures, source labels, drug result shape of RxCUI + ingredient + brand + pipeworx citation). For a two-type, multi-endpoint resolver this is thorough. Minor gaps: no concrete example response object, and the drug path is given much less depth than the company path.

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, and the schema's `value` description is already exemplary. The description adds meaning beyond it: ISIN as a fourth accepted input form (the schema lists only ticker, CIK, or name), the ISIN-to-LEI legal-entity resolution for non-US issuers, and the enrichment-degradation behavior that affects what the returned identifiers mean. It also expands the `type` enum values with concrete output semantics (CIK+ticker+LEI+FIGI vs. RxCUI+ingredient+brand).

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 natural-language triggers ("What's the ticker for…", "find the CIK for…") and then states a crisp verb+resource contract: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates two supported types (company, drug) with distinct output summaries, and differentiates itself from the sibling set by claiming "Use FIRST whenever you have a name but need an ID," which separates it from research-oriented tools like entity_profile and compare_entities.

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

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

The description gives an explicit trigger condition — "Use FIRST whenever you have a name but need an ID" — and even states what it replaces ("replaces 2-3 manual lookups"). The input-format rule ("Pass the ENTITY NAME ONLY… never the question's full noun phrase") is highly actionable guidance. However, it never names sibling alternatives or provides when-not-to-use conditions, so it stops short of full exclusion 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 the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density per entity. It does not mention cost/rate-limit implications of multi-probe execution, but the core behavior is transparent.

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

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

Three sentences with no filler. The first sentence states the core action, the second explains the mechanism, and the third provides a concrete use case plus output shape. Every sentence earns its place and the key differentiator is front-loaded.

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

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

With no output schema, the description appropriately explains the return value: a ranked list with score, confidence, and signal density per entity. It covers the main intended scenario and behavior. Minor gaps remain around error cases, cost/rate-limit expectations for multi-probe execution, and explicit alternative guidance, but the description is largely complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and their semantics. The description adds no new parameter-level detail beyond what the schema provides, such as the role of the first entity or the optional Anthropic key. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

The description uses a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes this tool from the single-entity ai_visibility_check by stating that it probes each entity, ranks by score, and surfaces which entity is most/least recognized. The purpose is unambiguous and clearly separated from sibling tools.

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

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

The description gives a concrete use case: competitive AI-marketing audits, with the example 'does Claude know about us as well as our competitors?'. It also names ai_visibility_check as the underlying probe mechanism, implying when this tool is the multi-entity counterpart. It does not explicitly state when not to use it versus compare_entities or other siblings, but the context is clear enough for an agent to route appropriately.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: it is a composite fan-out call across two external services, partial failures degrade gracefully via sources_failed, and bundlephobia's first measurement on a new version can take 5-30s. The latency warning and timeout behavior are exactly the kind of operational context an agent needs before invoking.

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

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

Four dense sentences, each earning its place: purpose, usage triggers, scope/return shape, and failure/latency behavior. The core purpose is front-loaded. It is slightly run-on in the returns enumeration, but with no output schema available, listing the summary fields is justified rather than 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 composite tool with no output schema, the description is remarkably complete: it specifies sources, the summary block's fields, per-advisory detail and links, the NPM-only scope, latency behavior, and partial-failure degradation. Nothing an agent needs to decide whether and how to call it 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 baseline is 3 — both package and version are already documented with examples ('@types/node', '18.3.1'). The description adds ecosystem context (npm-only) and reveals that version interacts with the is_latest output field, but it does not materially deepen parameter-level semantics beyond the schema.

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

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

The description states a precise job — 'Composite "should I add this npm package to my project" check in ONE call' — and names the data sources (deps.dev, bundlephobia) and exact data points (license, advisories, bundle size, dependency count, ESM/tree-shake support). It is clearly distinguishable from sibling research tools like validate_claim, compare_entities, and resolve_entity, none of which evaluate npm packages.

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

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

Gives explicit trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a concrete exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. An agent gets both when-to-use and when-not-to-use with a routed alternative.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description adds genuinely non-obvious behavior: the 200K-char cap with truncation flagged, BGE-base-en embeddings with cosine over 500-char overlapping windows, and offsets enabling verbatim-quote verification. It stops short of a 5 only because how the truncation flag is represented and no-match behavior are left unspecified.

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

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

Four sentences with zero waste: the core operation, the when-and-why, the companion-tool workflow, and implementation constraints each occupy one sentence. The purpose is front-loaded in the first sentence, and no sentence repeats what annotations or schema already provide.

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 correctly carries the burden of explaining return shape — top-N passages with character offsets and similarity scores — and adds windowing mechanics and truncation behavior. For a simple 3-parameter tool with full schema coverage, only edge-case behavior (no matches, exact truncation-flag representation) is missing, which is minor.

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% — text, query, and limit each have descriptions with defaults, ranges, and examples. The description adds only marginal context (what counts as a fetched record, why the 200K cap and windowing matter) without materially extending parameter semantics, so the high-coverage baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource — 'Semantic search INSIDE a fetched record' — and immediately distinguishes itself from fetching tools by requiring 'the text you already pulled.' It names the sibling ask_pipeworx_grounded and specifies its exact output (top-N passages with character offsets and similarity scores), so an agent can tell it apart without opening the schema.

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

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

Explicit when-to-use guidance is present: 'Use when the record is too big to cram into the prompt,' with the reasoning that search_within saves context and returns only the passages that matter. It also routes around a specific sibling, describing the fetch-then-ground workflow with ask_pipeworx_grounded rather than searching the whole document.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth needs, account-type persistence limits, an SMS phone-verification prerequisite, and a 10/day rate cap. No contradiction with annotations; it enriches them with concrete operational constraints.

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 first sentence carries the core purpose, and each following sentence adds operational detail (account requirement, per-type params, delivery rules). It is dense but not bloated, with only mild redundancy against the schema's parameter descriptions and a 'Supported types' list that omits two of the five enum values.

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

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

This is a high-complexity tool — five subscription types, three delivery channels, no output schema — and the description covers the essential return value, preconditions, and delivery constraints. Remaining gaps (behavior for patent_grant/clinical_trial, duplicate-subscription behavior) are minor because the schema documents all parameters and the idempotentHint annotation signals retry safety.

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 schema already documents all three parameters, including type-specific filter shapes and webhook signing behavior. The description adds interpretive value on top, e.g. items:['5.02'] means officer change and concrete delivery examples, earning one point above the 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?

States a specific verb and resource ('Create a proactive monitoring subscription to a live-data event stream') and names the returned artifact ('Returns the new subscription id'). The creation focus clearly separates it from lifecycle siblings list_subscriptions and unsubscribe, and from recent_alerts which consumes the feed.

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

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

Gives clear context for use: proactive monitoring of live data, plus a hard precondition ('Requires a Pipeworx OAuth account — anonymous + BYO cannot persist subscriptions'). It also routes feed consumption to the sibling recent_alerts and the public URL, but never explicitly states when not to subscribe or contrasts with list_subscriptions/unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, which covers the safety profile. The description adds valuable context beyond annotations by explaining the tool returns category-bucketed examples derived from the live catalog, includes exact tool and argument shapes, and requires no arguments for a full spread. 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 longer than average but every component serves a purpose: common user phrasings, the return format, the tool's role, parameter usage, and when to call it first. The natural language examples at the start and the explicit 'Use this FIRST' directive are front-loaded and impactful. Slight redundancy in listing example topics that appear again in the schema prevents a 5.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what the tool returns, how to invoke it, how to scope it, and when to use it. It even names the meta-tools it teaches, so an agent would have no difficulty calling it correctly or interpreting its purpose.

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

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

The schema already documents the single optional topic parameter with a complete description and examples, so baseline is 3. The description adds semantic nuance by framing the parameter as 'focus' with domain examples and clarifying that omitting it yields a cross-category spread. This meaningfully enriches the schema 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 precisely identifies the tool as the onboarding entry point for a newly connected agent, explaining it returns category-bucketed example questions across domains and the exact tool and argument shape to answer them. It clearly distinguishes itself from sibling tools like discover_tools by focusing on 'what can I ask' rather than generic discovery, and even names specific meta-tools it teaches.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you,' giving a clear condition for when to invoke it. It also explains how to narrow the scope via an optional topic, but it does not explicitly name sibling alternatives or when to choose them, so it falls just short of a 5.

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

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

Discloses critical behavioral traits beyond annotations: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. This adds real context beyond the readOnlyHint/destructiveHint annotations.

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

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

Two sentences, front-loaded with the action, and no filler. The ownership constraint and deactivation detail each earn their place without bloating the definition.

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

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

For a single-parameter mutation tool with annotations covering safety, the description is fully sufficient. It covers prerequisites, side effects, and downstream visibility of historical data, leaving nothing essential missing.

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

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

The input schema already fully describes the single parameter, including its type and origin ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter-level meaning, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe and list_subscriptions by naming the action of cancellation, and further clarifies the scope with ownership enforcement.

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

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

The description provides clear context for use: you must have a subscription id, and you can only cancel your own subscriptions. It does not explicitly name alternatives, but the use case is unambiguous and no exclusions are needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to repeat safety. It adds real behavioral value by explaining that could_not_verify means the check did not happen, carries verification_error{stage,detail}, and must not be presented as evidence. It also mentions performance characteristics (replaces 4–6 sequential calls) and exact percent-delta math, which are meaningful beyond the structured annotations.

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

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

The description is dense but front-loaded with trigger phrases and a clear purpose statement. The later parts about verdict definitions and the 'IMPORTANT for callers' note are useful but could be slightly tightened; overall every sentence earns its place.

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

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

For a claim-verification tool with no output schema, the description adequately explains what returns: a verdict enum, the actual value with a pipeworx:// citation, and reasoning. It also explains the failure mode (could_not_verify vs unsupported). It lacks exhaustive detail on the grounded pipeline's source routing, but that is internal behavior an agent doesn't strictly need 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 schema already covers 100% of both parameters with useful descriptions and examples. The description adds context about tolerance_pct's effect on grading and the default cap of 5, which reinforces but doesn't fundamentally extend the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with explicit natural-language trigger phrases and identifies the tool's core action: verifying the truth of a claim against authoritative sources. It also distinguishes the two internal paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for any other factual claim), which separates it from siblings like resolve_entity or ask_pipeworx_grounded.

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

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

It explicitly says to use whenever the agent needs to check whether something a user said is factually correct, and it names the exception path: company-financial claims go through the SEC EDGAR + XBRL fast path, while any other factual claim falls through to the grounded pipeline. It also tells callers what the verdicts mean and which verdict should not be shown as evidence.

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