universities

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

Annotations already declare read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds meaningful context about the default model, the need for an API key for Anthropic, cost implications, and the return structure, which goes beyond the annotations.

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

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

The description is three tightly packed sentences with no filler, front-loading the main purpose, then key options, and use cases. Every sentence earns its place.

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

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

Even though there is no output schema, the description outlines the return shape (per-model object plus a combined view) and covers key parameters and use cases. It is reasonably complete, though it doesn't explain the scoring methodology or edge cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by explaining the default model for the models parameter and clarifying that _apiKey is only needed when Anthropic is included, adding value beyond the schema.

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

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

The description clearly states the tool probes one or more LLMs for knowledge about a business and scores visibility 0-100 per model. It uses a specific verb and resource, and distinguishes itself from siblings by emphasizing the visibility scoring and multi-model probing.

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

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

The description provides clear usage context by listing scenarios like AI-marketing audits, pre-launch brand checks, and competitive monitoring. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses many behavioral traits: it auto-fills arguments, returns structured answers with citation URIs, refuses to guess via a no-answer guard, is US-centric, has training data ending 2024-12, and is weak at advanced math. This gives the agent realistic expectations about what the tool can and cannot do.

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 overly long, repetitive, and disorganized. It repeats guidance about ask_pipeworx_grounded and deep_research, includes filler phrases like 'Just use it' and 'For all else, remember that ask_pipeworx is the primary,' and wanders between routing instructions, limitations, and safety notes without clean structure. The strong content is buried in a stream of consciousness.

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

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

Despite the messy structure, the description is very complete for a complex routing tool. It covers what inputs to send, what outputs to expect, when to prefer alternatives, key limitations, data recency, geographic coverage, and safety behavior. Since there is no output schema, the explicit mention of structured answers with pipeworx:// citation URIs is especially valuable.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents that `question` is a natural-language request and lists all aliases. The description adds useful query-type examples and emphasizes factual/real-world questions, but it does not materially deepen the meaning of the single required parameter beyond what the schema already states.

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

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

The description clearly identifies ask_pipeworx as a router over 5,798 tools across 1,517 sources, stating that it answers factual questions with structured data and stable pipeworx:// citation URIs. The verb 'routes' and the concrete resource set distinguish it from general web search and from sibling tools mentioned in the same description.

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: prefer over web search for factual/current/historical data, start here for most questions, use ask_pipeworx_grounded for tightly-scoped cited answers, use deep_research for broad/multi-part questions, and use web search for recent AI developments or advanced math. It even names the tool for Canadian law (canadian_law) and points out media uploads are not accepted.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds important behavioral context beyond that: it is a live experimental router, may be under candidate testing, and currently matches the stable version. It also explicitly states 'Falls back to nothing' to prevent the misconception that it is a degraded mode. This goes well beyond the annotations.

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

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

The description is compact yet information-dense: it states the beta nature, identical interface, current inactive status, usage guidance, comparison purpose, and fallback behavior in a few sentences. Every sentence earns its place and the most important distinction (identical to stable, experimental edge) 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?

Given the tool's simplicity (one required string parameter, rich annotations, no output schema needed beyond saying response shape matches ask_pipeworx), the description covers everything an agent needs to invoke it correctly: what it is, when to use it, current state, and expected behavior. The comparison to ask_pipeworx provides all missing contextual detail.

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

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

Schema description coverage is 100%, with each alias (q, text, input, query, prompt) documented and the primary 'question' parameter described as accepting natural language with aliases. The description also states the arguments are identical to ask_pipeworx, reinforcing semantics. However, it adds little beyond the schema, which already covers all six parameters, so a baseline of 3 is appropriate.

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

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

The description clearly identifies it as a beta variant of ask_pipeworx with identical routing behavior and explicitly states that no candidate is active, so it currently matches ask_pipeworx exactly. It distinguishes itself from siblings by positioning it as the experimental edge for routing improvements, which is a specific and meaningful distinction.

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

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

Provides explicit guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It also names the alternative (ask_pipeworx) and clarifies that it is a full working router, not a fallback stub, which removes ambiguity about 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 mark read-only/idempotent/non-destructive; the description adds grounded answer extraction, a precise success object {answer, evidence, confidence, source, fetched_at, refusal_reason}, all five refusal_reason values, and the extra-cost behavior. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: behavior, output contract, refusal contract, use cases, and cost/alternative. It is front-loaded with the core distinguishing trait 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?

With no output schema, the description supplies the return contract, failure modes, and decision criteria an agent needs to select and invoke the tool. The refusal_reason enum and the success field names are explicitly listed, making the tool fully actionable.

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

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

Schema coverage is 100% with a clear aliased question field, so the baseline is 3. The description adds no additional parameter-level detail about question formatting or length, but does not need to because the schema already carries the full 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 specifies an exact verb ('EXTRACTS the answer'), a concrete resource (Pipeworx tool suite), and a distinctive constrained behavior (using ONLY the tool result, with explicit refusal rather than inventing facts). It also differentiates from the sibling ask_pipeworx by naming it and framing itself as the hallucination-resistant mode.

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 this tool ('whenever an answer will be quoted, cited, or acted on' and high-stakes domains) and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), plus the cost tradeoff of one extra LLM call.

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

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

Even though annotations declare readOnlyHint=true and idempotentHint=true, the description goes far beyond that by detailing response shapes, low-confidence short-circuit behavior, closed-market status, wide-spread warnings, cancellation-rule parsing, and rate-limit fallback mechanisms (e.g., GDELT 429s). This rich behavioral context is exactly what an agent needs.

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

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

The description is long but well-structured with clear headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded summary. Some sections, like the exhaustive fan-out examples, could be trimmed, but overall the structure makes the length manageable and useful.

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 is exceptionally complete. It covers response shapes, resolver match confidence, parent-event extraction, news field fallback behavior, safety short-circuits, wide-spread warnings, and resolution-rule risk. This is more than sufficient for an agent to understand the tool's behavior and edge cases.

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

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

Schema coverage is 100% and all parameters (market, depth, include_raw) have detailed descriptions in the input schema itself. The description adds examples of market formats and fan-out behavior but does not provide new parameter semantics beyond what the schema already documents. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on single-bet research with data fan-out, and provides concrete usage phrases like 'should I bet on X', which solidifies the tool's purpose.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...'), giving clear context. However, it does not mention when not to use it or explicitly name alternative sibling tools, so it falls short of a 5 but provides solid 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond this by revealing specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). This rich behavioral context helps the agent anticipate outputs and limitations.

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 serves a purpose: trigger examples, usage guidance, data source specifics, and output behavior. It is appropriately front-loaded with the most critical information. While slightly long, the complexity of the tool justifies the length, and nothing feels like filler.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers all essential aspects: what it does, when to use it, what data it accesses, how results are sorted, and what output format to expect (paired data + citation URIs). It also quantifies the efficiency gain ('Replaces 8–15 sequential lookups'), making the tool's value proposition clear. No critical gaps remain.

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

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

Schema coverage is 100% with both parameters described, providing a baseline of 3. The description adds substantial value by explaining that type='company' pulls specific financial metrics (revenue, net income, cash, long-term debt) and type='drug' pulls FAERS counts, along with concrete examples for the values parameter. This goes beyond the schema's generic 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 explicit trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly defines the tool's core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sequential single-pack lookups, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance through example queries and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' naming an alternative approach. However, it doesn't explicitly state when NOT to use this tool (e.g., for a single entity), though that is implied by its naming of the alternative for multi-entity comparisons.

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

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

The description goes far beyond the annotations, disclosing account requirements, paid depth tiers, parallel routing across 5,798 tools, output contents (verbatim evidence, confidence, source, fetched_at, citations), the gaps[] behavior, contradiction scanning for standard/thorough, semantic excerpting rather than head-truncation, and latency expectations. The annotations only say read-only/open-world/idempotent; the description adds rich behavioral context 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 contains all required information but is overly long and somewhat rambling, with awkward phrasing like 'Decomposes your question into focused facets, routes each to the right one of 5,798 tools IN PARALLEL, and returns a findings packet.' The account requirement is front-loaded before the core purpose, and the parentheticals make it harder to parse. It earns a middle score: valuable content, poor brevity.

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

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

For a complex tool with no output schema, the description thoroughly covers the full call lifecycle: prerequisites, auth tiers, input shape, internal behavior, output format, edge cases (gaps[] and contradictions[]), citation fetchability, and latency. There is no significant missing context an agent would 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?

Schema description coverage is 100%, but the description still adds meaningful value by explaining that 'question' can be broad and multi-part, and by detailing the depth parameter's behavior (quick=3 single hop, standard=3 with gap recovery and contradiction scan, thorough=6 paid with iterative lead-chasing). This adds semantics beyond the schema's enum 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 and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, returning a findings packet. It also explicitly distinguishes itself from open-web search and names the sibling ask_pipeworx as the alternative for single lookups, making its purpose unambiguous.

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

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

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also provides an auth-based routing rule: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' This is strong, actionable routing information.

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?

Adds meaningful behavioral context beyond the annotations: it describes the return format (top-N tools with names, descriptions, and full input schemas with curated examples) and that results are ready to call directly, eliminating the need for a second schema lookup. No contradiction with the readOnly/idempotent hints.

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

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

The description is front-loaded with the core purpose and includes a useful but somewhat long list of supported domains. It remains focused; each sentence adds value, but the category enumeration could be trimmed without losing critical meaning.

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

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

For a tool with no output schema, the description adequately explains the return payload and the recommended usage flow ('Call this FIRST'). Combined with exhaustive schema documentation, it gives an agent enough to invoke the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter-level detail beyond what the schema already provides; it only restates the query concept in prose. No additional semantic enrichment is given.

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 tools') and explains the tool's purpose as a discovery mechanism across many domains (SEC filings, FDA drugs, etc.). It clearly distinguishes itself from sibling tools by framing itself as the meta-tool for finding other 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context on when to invoke this tool versus simply asking for a direct answer.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context beyond that: fan-out across many sources, soft-fail behavior for USPTO patents, expected empty results for FDA products with only small-molecule drugs, 'sources_used'/'sources_failed' semantics, and the resolved:false + notes behavior for private companies. All of this helps the agent interpret results correctly and matches the annotations.

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

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

The description is long but dense, front-loading examples and usage precedence before enumerating output fields and edge cases. Every sentence carries useful information, though the length is near the upper limit and could be tightened with bulleted structure for the return fields. Still, it remains readable and purposeful.

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

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

Given the tool's complexity, the description is remarkably complete. It explains what sources are fanned out, what each result segment contains, what URIs look like, how failures are represented, and how empty results should be interpreted. Since there is no output schema, the description properly carries the burden of explaining return values and edge cases, and it does so thoroughly.

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

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

Schema coverage is 100%, but the description substantially enriches parameter understanding. It explains that 'type' accepts 'company' or 'ticker' interchangeably and that 'value' can be a ticker, zero-padded CIK, or company name with resolution via SEC EDGAR. Concrete examples ('AAPL', '0000320193', 'Moderna') and the private-company edge case go well beyond the schema's field descriptions.

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

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

The description opens with concrete example queries and states the core function precisely: a 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company), the action (profile/research), and distinguishes itself from single-pack SEC/XBRL/news lookups. This is unambiguous and immediately actionable.

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

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

The description explicitly tells the agent when to prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and provides example phrasings that trigger it. It does not explicitly state when NOT to use it or how it relates to siblings like resolve_entity or compare_entities, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, indicating a destructive, idempotent delete operation. The description adds context about clearing sensitive data, but no additional behavioral details beyond what annotations provide. 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 two concise sentences, front-loaded with the primary action and followed by usage and pairing guidance. Every word earns its place with no redundancy or fluff.

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

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

For a simple one-parameter delete tool with solid annotations (destructive, idempotent) and no output schema, the description fully covers what, when, and how it relates to other tools. No gaps in practical information.

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% (the 'key' property is already described as 'Memory key to delete'). The description only says 'by key,' which adds no new semantic value beyond the schema. Baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and distinguishes it from sibling tools by mentioning 'Pair with remember and recall.' This makes it obvious that this tool removes memories, unlike remember (store) or recall (retrieve).

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

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

It provides explicit when-to-use conditions ('when context is stale, the task is done, or you want to clear sensitive data') but does not explicitly state when not to use it or name direct alternatives beyond the pairing sentence. Still, the guidance is clear and actionable.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior. The description adds process detail ('Fetches the page, extracts title/description/key links') and output format ('single text blob ready to drop at site-root/llms.txt'), which enriches the behavioral picture beyond 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 compact and front-loaded: the first sentence states the tool's core function, the second explains the mechanism, and the third lists concrete use cases. Every sentence adds useful information with no redundancy or filler.

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

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

Given the tool's moderate complexity, good annotations, and full schema coverage, the description covers purpose, process, output format, and use cases. It lacks explicit notes about error handling or prerequisites (e.g., URL accessibility), but this is a minor gap for such a straightforward read-only operation.

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% for both parameters (url and max_links), so the schema already fully documents them. The description doesn't add specific parameter-level details beyond the schema, but it does contextualize the output format and the extraction process, which is marginal. This aligns with the baseline of 3 for high schema coverage.

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

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

The description uses a specific verb ('Generate'), names the exact resource ('llms.txt file'), and explains the purpose ('so AI crawlers can index the site cleanly'). It also outlines the steps and output format, making it distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides clear use cases in the 'Useful for' list (client sites, own projects, competitor audit), giving actionable context for when to select this tool. However, it doesn't explicitly mention when not to use it or name alternative sibling tools, so it's strong but not fully prescriptive.

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 non-destructive hints, and the description does not contradict these. It adds useful context by specifying the scope ('caller's') and the exact return fields, which helps the agent understand what to expect without needing an output schema. No additional side-effect disclosure is needed for a simple list operation.

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

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

The description is concise: three sentences that lead with the action, then list return fields, and finally provide usage context. No word is wasted, and the structure 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?

For a simple read-only tool with one optional parameter and no output schema, the description provides sufficient detail: it states the action, scope, return fields, and gives a practical use case. Annotations cover safety, making this contextually complete.

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

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

The schema description for include_inactive is complete ('Include cancelled subscriptions in the response (default false)'), covering 100% of the parameter. The tool description does not add further parameter semantics, 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 states the tool lists the caller's active subscriptions, using a specific verb and resource. It further distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and even mentions the return fields to clarify its output.

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

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

The description explicitly says to use this tool to review what you're monitoring before adding more subscriptions or to find an id to cancel. This provides clear when-to-use guidance, but it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations provide no safety profile (all hints false), so the description carries the full burden. It compensates comprehensively by disclosing rate limiting (5 per identifier per day), cost (free, doesn't count against quota), return behavior (claim_token), and post-submission workflow (digests read daily, signal affects roadmap). 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 sentence contributes operational insight (scope limits, filing rules, claim flow, rate limits, cost). It is front-loaded with the core purpose and organized by usage conditions, making it efficient despite 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?

Given the tool's nuanced purpose, nested parameters, and lack of an output schema, the description is thorough. It covers the complete workflow (submit, receive token, check status), including edge cases like anonymous filing, and provides enough context for the agent to invoke correctly without consulting external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to use claim_token ('pass it back later to read whether it was fixed') and clarifying message expectations ('don't paste the end-user's prompt'). It enhances parameter understanding without needing to compensate for gaps.

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 actions of the tool: sending feedback to the Pipeworx team (bug, feature, praise). It specifies the exact target (Pipeworx connection tools) and differentiates from sibling tools like ask_pipeworx and discover_tools, stating 'ONLY for tools served by this Pipeworx connection.'

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise), when NOT to use it (different MCP server), and provides a clear decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). It also explains how to check status later using the claim_token, which is actionable guidance beyond basic triggers.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses meaningful behavioral traits: it is self-aggregating, derived from an analytics engine, contains no PII, returns only (pack, tool, count), and is cached for 5min-1h depending on window. This adds real context about data provenance and freshness.

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

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

The description opens with a clear purpose sentence, lists returns and use cases, then adds essential transparency details about data source, PII, and caching. Every sentence earns its place; the bullet-like use-case list improves scannability without padding.

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

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

With no output schema, the description compensates by specifying what is returned (top tools, top packs, total call volume) and the data shape (pack, tool, count). It also covers caching, privacy, and the meaning of window choices, making the tool's behavior fully understandable for an agent.

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

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

The only parameter (window) is already fully described in the input schema, including its default and the semantic difference between shorter and longer windows. The tool description mentions the window values but does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Returns') and names the exact resource and outputs: top tools, top packs, and total call volume over a recent window. It clearly distinguishes itself from siblings by focusing on aggregate trending data from other AI agents, not a specific lookup or research tool.

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

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

The description provides an explicit 'Useful for' list with three concrete use cases, giving clear guidance on when to invoke the tool. It does not explicitly name alternatives or say when not to use it, but the use cases provide strong contextual direction.

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

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

Beyond annotations (read-only, open-world, idempotent), the description discloses critical behavioral details: the fill check reveals that theoretical edge may not be realizable in the book, and it explicitly warns 'do not trade it' when realizable_edge_pp ≤ 0. It also exposes filters like placeholder slug removal and the ≥0.30 Jaccard similarity threshold, providing deep insight into internal decision-making.

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

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

The description is lengthy but well-structured: it opens with the core purpose, then separates sections for event mode, topic mode, semantic anchor, partition filter, response format, and fill check. Each sentence adds necessary detail for a complex tool, though some could be condensed. Overall, it's efficiently organized for its complexity.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: opportunities[] with specific fields, partition_check with its fields, and the fill check outputs. It also covers behavioral nuances like skipped_low_similarity and thin_legs. For a tool of this complexity, the description is remarkably complete.

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

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

Both parameters have schema descriptions, but the tool description massively extends their meaning. It gives concrete example slugs (e.g., 'fed-decision-may-2026') and seed questions, explains what each mode does, and even the difference between single-event and cross-event behavior. The description is a tutorial for using the parameters effectively.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the unique method (monotonicity + partition-sum) and the resource (Polymarket), distinguishing it from generic market edge tools. The three modes (trending_scan, event, topic) are explicitly spelled out, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It even recommends event mode for a specific market and explains the cross-event mode's advantage. It also directs users to polymarket_fill_risk for custom sizing, naming an alternative tool, which fully satisfies the 'alternatives' requirement.

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 safety, so the description adds value through detailed behavioral context: output structure per segment, edge metrics, the 24h-move warning, diagnostics to explain empty segments, and caching behavior. It also discloses nuances like Fed bets being excluded from ranking and partition arbs returning kelly_fraction_half=0 at the parent level, which agents need to interpret results correctly.

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

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

The description is front-loaded with purpose and organized into labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). However, it is long and includes some implementation minutiae (per-sport α values, historical 'Run 8' gate relaxation) that are not necessary for selecting or invoking the tool, though they add transparency. It earns its length for a complex tool but is not as tightly pruned as it could be.

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

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

With no output schema, the description furnishes the full response shape: by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains why segments can be empty and how knobs affect filtering, covering the agent's need to interpret results and tune parameters. The caching note adds operational context.

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

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

Schema descriptions cover 100% of the 9 parameters with detailed explanations, so the baseline is 3. The description's mention of 'TRADEABLE-EDGE KNOBS' summarizes existing schema content but does not add new meaning beyond what the schema already provides; it only groups them conceptually. Thus it stays at the baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings by focusing on Pipeworx-model disagreement and by defining the output segments (model_driven, structural_arbitrage, concentrated_longshot).

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

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

It states a clear use case ('what should I bet on today') and notes that it avoids paging hundreds of markets. However, it does not explicitly mention alternative tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state when not to use it, so it stops at clear context without 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?

The description adds significant behavioral context beyond the annotations. It discloses that 'snapshots are written when polymarket_edges runs on a cache-miss, so gaps mean nobody scanned that day,' that history depth is bounded by the '60-day snapshot TTL,' and that decay numbers 'come from daily closes of edge_pp_net, not intraday.' These details help the agent interpret data gaps and time-series correctly. No contradiction with annotations (readOnlyHint=true, destructiveHint=false).

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 heavily information-dense. It is structured with 'Args', 'RESPONSE', and 'LIMITS' sections, making it easy to parse. Every sentence provides useful detail; there is no fluff or repetition. The length is justified by the absence of an output schema, which requires the response structure to be described inline.

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 does so thoroughly: tracked[] with fields (full edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. It also explains limitations (TTL, cache-miss gaps, daily closes) which are critical for correct interpretation. For a read-only telemetry tool with two simple params, this is fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') mostly repeats the schema, but adds the phrase 'snapshot family' which clarifies that the window parameter selects between families of snapshots (24hr vs 1wk vs 1mo), reinforcing the schema's 'window family' phrasing. This is marginal value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb (track) and distinct resource (historical edge snapshots), and differentiates from the related polymarket_edges tool by focusing on how edges persist and decay over time. The phrase 'Answers "how long has this edge existed and is it shrinking?"' ties it to a concrete use case.

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

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

The description provides clear context on when to use it: 'a fresh wide edge and a 3-week-old wide edge are different trades' implies this tool is for historical persistence analysis. However, it does not explicitly name an alternative tool or state 'use this instead of polymarket_edges'; the guidance is implicit rather than explicit. The mention of 'daily polymarket_edges snapshots' indirectly points to the relationship with the sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds behavioral detail: it 'walks the ladder,' returns specific metrics like vwap_fill_price and slippage_pp, and highlights risks like forced_directional_risk and thin_legs. 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 lengthy but well-structured with ALL-CAPS mode labels and a final usage directive. Every sentence adds information—modes, parameters, outputs, and risk context—making it dense rather than verbose. The front-loaded first sentence immediately conveys the core purpose.

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 enumerates the return fields for both modes (top_of_book, vwap_fill_price, capture_ratio, etc.), explains edge cases (thin legs, partial fills, forced directional risk), and ties usage to sibling tools. This is comprehensive for a tool of this complexity.

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

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

Although the input schema covers all four parameters with 100% coverage (baseline 3), the description deepens semantics by explaining the dual interpretation of size_usd (max spend for buys vs target proceeds for sells vs settlement notional in basket mode) and the auto side selection based on partition sum. It also clarifies the required presence of either market or event, which the schema leaves optional.

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 defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly specifies the two modes (single-market and basket) and the sibling tools it complements, distinguishing it from polymarket_arbitrage and 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 explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial fills converting arb to unhedged directional position), giving a strong when-to-use rationale.

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 read-only, idempotent, and non-destructive, and the description adds considerable behavioral context beyond that: spreads are gross and do not model Kalshi fees, compatibility warnings must be read even when matched pairs exist, and temporal_alignment null means uncomputed rather than aligned. This caveat-heavy disclosure gives an agent a realistic model of the tool's limits.

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

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

Although long, the description is front-loaded with purpose and organized into clearly labeled sections: modes, response, safety fields, fees, and skipped comparisons. Every block earns its place, and the density is justified by the tool's complexity and the absence of an output schema.

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

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

The description fully compensates for the missing output schema by enumerating the relevant response fields, warning flags, fee caveats, temporal alignment semantics, and skipped-comparison counters. An agent would be able to select and invoke this tool appropriately without additional documentation.

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

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

The description goes beyond the schema by explaining that the three parameters form two mutually reinforcing modes, that explicit ticker and slug override the mapped sides, and that both modes share the same matching behavior. This makes parameter semantics clearer than the raw schema alone, though the schema already carries the same enum-like details.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which names a specific resource and a precise comparative function. It clearly differentiates itself from single-venue siblings like polymarket_edges by the cross-venue focus and explains scope through the two input modes.

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

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

The description gives clear usage context: use `topic` for pre-mapped shortcuts or explicit ticker/slug for custom pairings, and notes that BOTH modes run the same matcher. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly name when to prefer this over sibling tools such as polymarket_arbitrage, so it stops just short of a 5.

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

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

Annotations already mark it read-only and idempotent. The description adds valuable behavioral context not captured in annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual mode (value retrieval vs. key listing). 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 three sentences, each earning its place: core function, use case, and scoping/pairing. It is front-loaded with the primary action and contains no fluff or redundancy.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers the essential information: how to use it (with/without key), why it exists (avoid re-derivation), and its boundaries (scoped to identifier, paired with remember/forget). No missing information that would confuse an agent.

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

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

The schema has 100% coverage—one parameter 'key' with description 'Memory key to retrieve (omit to list all keys).' The description repeats this usage pattern ('omit the key argument') and adds scoping context, but does not add significant semantic detail beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys' with a specific verb and resource. It distinguishes from siblings by explicitly mentioning remember and forget, making its role in the memory lifecycle unambiguous.

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

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

The description provides clear use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch,' and references complementary tools with 'Pair with remember to save, forget to delete.' It lacks explicit when-not-to-use conditions but otherwise gives solid guidance.

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

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

The description reveals that mark_read:true flags events as read, which modifies state, contradicting the readOnlyHint:true annotation. This is a serious inconsistency because the annotation claims read-only behavior while the tool can mutate read status. Therefore, the description contradicts 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, each serving a distinct purpose: core function, payload composition, filtering options, and behavioral nuance plus alternative access. It is tightly written with no redundancy, front-loading the action verb and resource.

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 compensates by detailing what each alert contains (source, citation_uri, raw payload), covering filtering and mark_read behavior, and noting an alternative HTTP endpoint. It fully equips an agent to select and use the tool correctly, including polling suitability.

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 100% means the schema already documents all parameters. The description adds meaningful value by explaining the consequence of mark_read (only newer events on next call) and giving a concrete type filter example. This goes beyond the baseline of 3, warranting a 4.

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

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

The description clearly states the tool pulls recent alerts from the subscription feed and describes the payload fields, making the purpose specific and unambiguous. However, it does not explicitly differentiate from sibling tools like recent_changes, 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 context: it mentions polling works fine and points to an HTTP endpoint for scripts, which provides guidance on when to use the tool versus external access. It also explains the mark_read effect for subsequent calls, implying a polling workflow. No direct comparison with sibling tools, but the context is sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavior: fan-out to multiple sources, GDELT→GNews fallback on rate limits or 5xx, USPTO soft-fail due to PatentsView sunset, and the structured output shape. This gives the agent a realistic model of how the tool behaves.

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 likely user questions, then delivers a dense but well-organized summary of behavior, fallbacks, outputs, and the alternative tool. Every sentence adds value and there is no fluff; the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by explicitly stating the return shape: structured changes[] grouped by source, total_changes count, and citation URIs. It also covers data sources, error/fallback behavior, and the key alternative, making the description complete for an agent to select and invoke the tool.

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

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

The input schema already covers all three parameters with 100% coverage, including format details for `since` and examples for `value` and `type`. The description repeats the `since` format but adds no new parameter-level semantics beyond what the schema provides, 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 defines the tool as a change feed for a company over a recent window, with concrete natural-language examples ('What's new with X', 'updates on Acme'). It distinguishes itself from the sibling entity_profile by explicitly positioning recent_changes as the windowed dynamic feed versus the static profile.

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

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

The description provides explicit guidance on when to use this tool, including the quoted user-intent patterns. It also names the alternative entity_profile and specifies the exact condition under which to use it instead (static profile regardless of window), giving the agent clear decision criteria.

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

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

The description discloses behavioral traits beyond annotations: storage as key-value pair scoped by identifier, persistence duration for anonymous sessions (24 hours) vs authenticated users, and cross-session availability. These are not available in annotations and add critical context.

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

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

The description is four sentences, front-loaded with the primary purpose, and each sentence provides essential information (when to use, storage mechanics, persistence, companion tools). No redundancy or unnecessary 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?

Despite lacking an output schema, the tool is simple (2 required params) and the description sufficiently covers purpose, usage triggers, scoping, persistence, and pairing with recall/forget. It gives an agent everything needed to invoke appropriately.

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

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

Schema covers 100% of parameters with descriptive examples. The description does not add substantial new parameter semantics beyond the schema, though it reiterates the kind of data to store (e.g., resolved ticker, target address). Baseline 3 is appropriate given high schema coverage.

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

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

The description uses a specific verb 'Save' with a clear resource 'data the agent will need to reuse later', and explicitly differentiates from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.' It clearly states the tool persists key-value pairs.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples, and it contrasts with recall/forget as complementary operations. It also clarifies persistence rules for authenticated vs anonymous users, covering context.

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

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

The description goes far beyond the annotations by disclosing internal behavior: it cascades through multiple lookup endpoints, degrades gracefully when LEI/FIGI enrichment is unavailable, returns figi_candidates when a name matches multiple instruments, and explicitly lists unresolved identifiers. This gives the agent a rich mental model of what to expect.

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

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

The description is long, but well-structured with front-loaded examples, a clear 'Use FIRST' instruction, and organized supported-type sections. Some repetition exists (multiple example phrasings), but each substantive detail earns its place; it is thorough rather than bloated.

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

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

Given that there is no output schema, the description compensates by explaining return semantics: named identifiers with source labels, unresolved fields, figi_candidates for ambiguous matches, and graceful degradation. It is complete enough for an agent to call this tool correctly in the vast majority of 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?

Although schema coverage is 100%, the description adds substantial meaning beyond it: it explains that 'value' should contain the entity name only, warns about trailing security-class words for bonds, and clarifies how tickers, CIKs, ISINs, and drug names map to lookups. This materially improves correct invocation.

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

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

The description clearly states a specific action — resolving a user-spoken name to canonical/official identifiers — and identifies the resource and output. It differentiates itself from sibling tools like entity_profile or compare_entities by framing resolve_entity as the provider of the identifiers those tools would need as input.

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

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

It gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported entity types. However, it does not explicitly name sibling tools or state when NOT to use this tool in favor of alternatives like entity_profile or compare_entities, 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 declare readOnly and idempotent hints. The description adds that it 'probes each entity' with ai_visibility_check and returns a ranked list with score/confidence/signal density, which is not in annotations. This clarifies the orchestration behavior.

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

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

Four sentences with no fluff; front-loaded with the core purpose. The use case and return description earn their 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?

No output schema, but the description explicitly states the return format (ranked list with score, confidence, signal density). It also names the underlying probe, providing context for an agent to decide if this is the right batch tool. It doesn't mention rate limits or per-probe errors, but these are minor gaps given schema coverage.

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 covers 100% of parameters with detailed descriptions, including the entities' first-entry-as-subject behavior. The description adds no new parameter syntax but contextualizes entities as 'your brand + N competitors'.

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

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

The description clearly states it 'Compare AI visibility across multiple entities side-by-side', naming the resource (AI visibility) and the verb (compare). It distinguishes from siblings by mentioning 'across multiple entities' and the ranking behavior, which differentiates it from the single-entity 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?

It gives a concrete use case ('competitive AI-marketing audits') and an example question. It indicates that it probes each entity with ai_visibility_check, implying the alternative for single entity, but doesn't explicitly exclude other comparison tools like compare_entities.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses key behavioral aspects: the fan-out across two third-party services, graceful degradation on partial failures ('sources_failed will list it if it times out'), and the potential 5-30s delay for bundlephobia's first measurement on a new version. These details are not visible in the annotations and add significant operational context.

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

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

The description is well-structured and front-loaded with the core purpose, followed by use cases, return value breakdown, ecosystem limitation, and failure behavior. Every sentence carries useful information, and the use of em dashes and semicolons keeps it readable despite its length. No filler or redundant content.

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

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

Given the tool's complexity (composite of two sources) and the absence of an output schema, the description thoroughly explains what is returned (summary block fields, per-advisory detail, links, alternative versions) and handles edge cases (timeouts, partial failures, ecosystem support). It provides enough detail for an agent to understand the tool's scope, latency, and output without needing additional documentation.

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

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

The input schema already describes both parameters (package and version) with 100% coverage, including scoped package acceptance and version default behavior. The description does not add new parameter-level semantics; it only implies version usage by mentioning 'latest published version' in the context, which is already stated in the schema. Hence, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, specifying the two data sources (deps.dev and bundlephobia) and the types of information gathered (license, advisories, version history, bundle size, dependency count, ESM/tree-shake). This distinguishes it from sibling tools like deep_research or bet_research, which serve different domains.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an important exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which guides users away from this tool for other ecosystems. However, it doesn't mention alternative sibling tools by name, so it doesn't fully cover when not to use relative to all siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context by listing the return fields (name, country, state/province, web pages, email domains) and the input requirement that at least one of name/country is needed, which is not enforceable from the schema alone. No contradiction with annotations.

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

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

Three short sentences deliver the core purpose, return data, and a key precondition. Each sentence earns its place, with no filler. The description is front-loaded with the verb.

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 search tool with a rich output schema and complete annotation set, the description covers the essential behavior and a necessary input rule. It does not need to explain return values or safety, as those are captured in the output schema and annotations. The description is complete for the given complexity.

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

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

The schema has 100% description coverage, with all six parameters documented including aliases. The description adds a cross-parameter constraint that at least one of name or country must be provided, which is not captured in the schema's required field list. This adds meaning beyond the individual property 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 action ('Search universities worldwide') with a defined resource and an external API (Hipolabs). It mentions return fields, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools, though the university focus likely sets it apart.

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

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

The description provides a usage constraint ('At least one of name or country must be provided') but does not offer guidance on when to use this tool over alternatives. No exclusions or alternative tool suggestions are mentioned, so the usage context is implied rather than explicit.

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

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

Beyond the readOnlyHint annotations, the description discloses the embedding model (BGE-base-en), windowing (500-char overlapping windows), the 200K char cap with truncation and flagging, and that results include offsets and similarity scores. This adds meaningful operational context that annotations do not convey.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds a distinct insight (what it does, when to use, how it works). There is no wasted text.

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

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

Despite lacking an output schema, the description explains the return value (passages with offsets and similarity scores), limitations (200K cap, truncation flag), and a clear example workflow with ask_pipeworx_grounded, making the tool's usage and behavior well-specified.

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 a few useful examples (SEC 10-K body, article, long tool result) and clarifies that text is 'the text you already pulled'. However, it does not add substantial parameter semantics beyond the schema, so a 4 is appropriate.

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

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

The description uses the specific verb 'Semantic search INSIDE a fetched record', naming both input (text, query) and output (top-N passages with character offsets and similarity scores). It clearly distinguishes itself from siblings by referencing ask_pipeworx_grounded and positioning itself as the passage-level search step.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt', giving a clear use case. It also states 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document', which points to the complementary alternative and usage pattern.

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

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

The description adds meaningful behavior beyond annotations: it requires an OAuth account, states anonymous/BYO cannot persist subscriptions, notes SMS phone verification and a 10/day cap, and explains feed semantics. Annotations already cover read-only/destructive/idempotent hints, so this extra context is valuable rather than redundant.

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 not bloated: it front-loads the core action and return value, then organizes types and delivery channels compactly in a single paragraph. Every sentence contributes useful information without 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 complex create operation with nested objects, multiple subscription types, and delivery options, the description is complete. It covers auth, return value, supported types, feed behavior, and alternative pull mechanisms; the schema handles fine-grained webhook details. No output schema is needed since the return type (subscription id) is stated.

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

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

Schema coverage is 100%, but the description adds interpretive context for type-specific parameters (e.g., items:['5.02'] = officer change, 'Polymarket↔Kalshi cross-venue mispricings'). This goes beyond the bare schema descriptions and helps the agent understand the meaning behind the parameter values.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream,' and clarifies the return value ('Returns the new subscription id'). It clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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

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

It provides clear usage context by explaining the persistent feed ('always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json') and the optional email/SMS channels. While it doesn't explicitly say 'use this instead of X for one-off queries,' the proactive-monitoring framing and mention of recent_alerts imply the 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 declare readOnly/openWorld/idempotent/non-destructive. The description adds behavior beyond that by detailing what the tool returns (category-bucketed example questions with tool+argument shape), that it draws from a live catalog of thousands of tools, and that it can be called with no arguments or a topic. No contradiction with annotations.

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

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

The description is long but front-loaded with natural language queries, then a concise purpose statement, return description, parameter guidance, and usage recommendation. Every sentence serves a clear function, and the structure flows logically from 'what' to 'how' to 'when'.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is fully complete: it explains the return format, invocation modes, the meaning of the topic parameter, and the intended use case. It also situates the tool among related meta-tools, which is valuable in the broader context.

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

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

Schema has 100% coverage already, including a description of the `topic` parameter and the behavior of omitting it. The description adds example values and phrases the parameter in terms of 'focus', but this is mostly redundant with the schema and does not provide significant new semantic meaning.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('Returns', 'Use this FIRST') and explicitly differentiates from sibling tools by positioning itself as the starting point for agents unfamiliar with Pipeworx.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names alternatives (ask_pipeworx, entity_profile, compare_entities) and explains the optional topic parameter for focused vs. full-spread queries.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context: the row is deactivated but not deleted, and historical events remain available via recent_alerts. This explains the non-destructive behavior and the side effect clearly, going beyond what annotations alone convey.

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

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

The description is two sentences and front-loads the action ('Cancel a subscription by id'). Each sentence earns its place: the second explains ownership enforcement and the deactivation side effect. No filler or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the core action, the ownership constraint, and the non-deletion behavior. It does not mention error cases or return values, but given the simplicity and schema coverage, it is sufficiently complete.

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

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

The input schema already fully describes the 'id' parameter (including that it is the subscription id returned by subscribe), providing 100% coverage. The description only repeats 'by id' without adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Cancel a subscription by id.' It also clarifies the scope ('only cancel your own subscriptions') which distinguishes it from canceling others' subscriptions and from related tools like list_subscriptions and subscribe. The deactivation note further differentiates its effect from a pure delete.

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

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

The description implies when to use the tool (when you have a subscription id and want to cancel it) and mentions the ownership prerequisite, but it does not explicitly state when to use this over alternatives or exclude contexts. There is no direct comparison to subscribe or list_subscriptions, so the guidance is implied rather than explicit.

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

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

Annotations mark this as read-only, open-world, idempotent, and non-destructive. The description goes further by explaining the verdict vocabulary and the crucial distinction that could_not_verify means the check didn't happen (with verification_error) and must not be treated as evidence, while unsupported means no source covers it. This is essential behavioral context beyond the annotations.

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

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

The description is long but well-organized with a trigger list, purpose, routing explanation, return details, and a critical caveat. Each sentence provides value, though the list of example phrases is somewhat redundant and the text could be tightened.

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

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

Despite no output schema, the description enumerates all possible verdict values, specifies that it returns the grounded/structured value with a pipeworx:// citation and reasoning, and explains error semantics (could_not_verify vs unsupported). This gives an agent everything needed to interpret results, and the two routing paths cover the tool's full behavior.

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

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

The input schema provides full descriptions for both params (claim and tolerance_pct) with examples and defaults, so schema coverage is 100%. The description itself does not add parameter-level detail, meeting the baseline of 3

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

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

The description opens with natural-language trigger phrases and clearly states 'natural-language claim verification against authoritative sources.' It then specifies two routing paths (SEC EDGAR/XBRL for financials, grounded pipeline for other claims) and notes it replaces 4–6 sequential calls, fully distinguishing it from sibling research/query tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains when the structured financial path is used vs the grounded pipeline. However, it does not name alternative tools to use for non-claim queries, so it lacks explicit when-not guidance and alternative tool references.

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