Pub Dev

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds cost behavior (free default vs. BYO key for Anthropic) and return structure, enhancing transparency beyond annotations.

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

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

Three sentences, front-loaded with main action, no redundant words. Efficiently covers purpose, usage, and return format.

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

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

With no output schema, description adequately details return structure (per-model object with fields, combined view). Explains when to use and parameter roles. No gaps for a 4-parameter tool with 100% 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?

Schema description coverage is 100%, so baseline is 3. Description adds minimal extra meaning beyond schema (default model, API key usage). Does not significantly deepen parameter understanding.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource ('LLMs for visibility'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on probing multiple models for brand visibility scoring.

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 default model and how to add Anthropic with API key. Mentions use cases (AI-marketing audits, pre-launch checks, competitive monitoring) but does not contrast with alternatives like sibling tools.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints; the description adds meaningful behavior by explaining that it routes to thousands of tools, auto-fills arguments, and returns citations with stable URIs. It scopes the answer to authoritative structured data, though it does not discuss edge cases like unsupported queries or response latency.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and each subsequent section adds routing, example, or alternative value. It is longer than minimal, but the density is mostly justified; the trailing enumeration of sibling conditions is slightly heavy.

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

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

For a one-required-param router with no output schema, the description covers selection triggers, examples, alternatives, and return behavior. The citation-URI description compensates for the missing output schema, so an agent has enough context to call it correctly.

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

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

All six parameters are already described in the schema, so the baseline is 3. The description earns extra by providing realistic example queries that clarify acceptable natural-language input and the alias flexibility, even though it does not add constraints 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 identifies a specific action: routes a natural-language question to one of 5,798 verified-data tools, fills arguments, and returns a structured answer with pipeworx:// citations. It clearly distinguishes this tool from web search and from sibling tools like ask_pipeworx_grounded and compare_entities.

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

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

Explicitly says to prefer it over web search for current/historical factual data, lists trigger phrases and example queries, and names alternatives: ask_pipeworx_grounded for grounding, compare_entities for comparison, and DEFAULT web search for single-best web results. This leaves little ambiguity about when to select 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 say readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: no candidate is currently active, so it matches ask_pipeworx exactly, and it is a full working router with no fallback. This goes beyond the annotations without contradicting them.

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

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

Three sentences, each adding a distinct fact: beta status, current state, and usage guidance. The specific retirement date is extra detail but not bloated. Front-loaded with the core identity.

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 universal router with 5,798 tools, the description explains it is fully functional, currently identical to ask_pipeworx, and has the same response shape. Combined with rich annotations and a fully documented schema, an agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, with the description saying 'same arguments' as ask_pipeworx. The schema already documents all six aliases, so the description adds no new parameter-level meaning beyond referencing the sibling tool.

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

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

States it is a beta version of ask_pipeworx and a universal router with the same 5,798 tools, arguments, and response shape. Clearly distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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

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

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains results are compared against the stable router. It does not mention when not to use it or alternatives like ask_pipeworx_grounded, but the context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the refusal behavior, exact success and refusal response shapes, refusal reasons, and the extra LLM call cost. It directly addresses hallucination risk by stating the answer is extracted using ONLY what the tool result contains, which is valuable behavioral context.

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

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

The core mode and primary behavior are front-loaded, and every sentence adds meaningful information: routing, extraction constraint, output contract, refusal conditions, usage guidance, and cost trade-off. It is dense without being redundant.

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

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

There is no output schema, so the description's explicit return contract and refusal reason enum are necessary and sufficient. It also covers cost, relationship to ask_pipeworx, and safe usage contexts, making the tool complete for selection and invocation.

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

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

The input schema has 100% description coverage and clearly documents the question parameter plus aliases. The description does not need to re-explain parameters; it adds pipeline context but no additional parameter semantics beyond the schema.

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

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

The description names a specific mode—'Grounded'—and its defining behavior: being hallucination-resistant and extracting answers using ONLY the tool result. It clearly distinguishes itself from the sibling ask_pipeworx with 'Same routing as ask_pipeworx' and the contrast between grounded extraction and casual lookups.

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

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

It states explicit when-to-use conditions: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with high-stakes examples. It also provides the alternative and trade-off: 'prefer ask_pipeworx for casual lookups' and 'Costs one extra LLM call vs ask_pipeworx.'

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 provides extensive behavioral details beyond the annotations: it explains confidence thresholds (low-confidence short-circuit, closed markets, wide spreads), resolution-rule risk (cancellation rules), and dynamic fan-out behavior. It also clarifies safety mechanisms (suppressed analysis for phantom matches). No contradictions with annotations found.

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 comprehensive but overly verbose, with multiple sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) that could be consolidated. Repetition occurs (e.g., low-confidence handling mentioned twice). While structured, it lacks conciseness, making it harder for an agent to parse quickly.

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

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

Given the absence of an output schema, the description fully covers return shapes (market, analysis, evidence, parent_event, news), edge cases (closed markets, low confidence, wide spreads), and error handling (429 retries, fallback). It also provides enough examples and classifiers for the agent to understand the tool's capabilities.

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

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

Schema coverage is 100% and the description adds significant context: it explains the default for 'depth', provides multiple examples for 'market', and details the effect of 'include_raw' on response size. This goes beyond the schema's basic descriptions, earning 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 immediately states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It clearly distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on comprehensive data pulling and analysis.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of when it's appropriate, but does not directly name alternative tools for scenarios where it should not be used. Nevertheless, 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?

Beyond annotations (read-only, idempotent, non-destructive), description adds: makes ONE parallel call, returns sorted by primary metric, provides citation URIs, explains data sources and fields for each type, and mentions handling of off-calendar fiscal years. 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 moderately long but each part is valuable: trigger phrases upfront, key usage instruction, then data details. Could be slightly more structured (e.g., bullet points) but is well-organized and 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?

No output schema, but description explains return format (paired data + citation URIs), covers both entity types with specific metrics, mentions edge case (off-calendar fiscal years), and describes sorting. Provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds meaning by explaining what data each type returns (e.g., revenue, net income for company) and concrete examples for values. This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with explicit trigger phrases. It distinguishes from siblings by explicitly preferring over sequential single-entity lookups, and sibling list includes entity_profile which is a single lookup.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Provides specific user query examples that trigger this tool, and specifies limits on entity count and type.

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

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

Annotations already carry the safety profile (readOnly, non-destructive, idempotent, open-world), and the description goes far beyond them: auth requirements, latency windows (15-60s, up to ~90s for thorough), the never-invents guarantee via explicit gaps[], citation fetchability (citation_uri present only when resolvable), multi-hop iteration behavior, contradictions[] scanning, and semantic excerpting of large records. 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?

Long but unusually dense — nearly every sentence carries a distinct operational fact (auth, fallback, scope, mechanism, output format, latency, citation guarantee, excerpting), and the most critical constraints (account required, use ask_pipeworx if not signed in) are front-loaded ahead of the purpose statement. Not a 5 only because some internal mechanics (the 5,798 parallel tools, hop field details) could be trimmed without losing agent-relevant guidance.

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

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

For a complex multi-hop tool with no output schema, the description is fully self-sufficient: it specifies the return format (verbatim evidence + confidence + source + fetched_at + citation_uri), gap and contradiction handling, iteration depth per tier, latency, prerequisites, and the fallback sibling. Nothing an agent needs to select, invoke, or interpret the result is missing.

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

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

Schema coverage is 100% and the depth enum description is already rich (quick/standard/thorough semantics, paid flag), so the baseline is 3. The description adds real value above that: practical depth behavior (re-angles unanswered gaps, chases best leads), the paid-plan gate tied to 'thorough', and question-shape guidance with examples. Not a 5 because the schema already does the heavy lifting for both parameters.

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

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

States a specific verb+resource: grounded multi-source research across 1,517 structured data sources with a clear mechanism (facet decomposition, parallel routing to 5,798 tools, findings packet). Explicitly distinguishes itself from siblings ('this is NOT open-web search', 'For a single lookup use ask_pipeworx instead'), so an agent can tell it apart without opening the schema.

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

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

Gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') with two concrete worked examples, and names the alternative tool (ask_pipeworx) under two distinct conditions: not signed in, and single-lookup questions. Also discloses prerequisites up front: GitHub sign-in required, thorough depth needs a paid plan.

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

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

Annotations indicate readonly, idempotent, non-destructive. The description adds that results include full schemas with examples and are ready to call directly, which provides behavioral context beyond annotations.

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

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

The description is well-structured and front-loaded with purpose, but includes a long list of domains that could be condensed. Most sentences 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?

Given the tool's simplicity (1 required param, 100% schema coverage), the description fully explains expected behavior and return value (top-N tools with schemas), making it easy for an agent to use.

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 parameter descriptions. The description adds no new parameter details beyond what the schema already provides, and thus adds minimal extra value.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.). It distinguishes from siblings by noting 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description explicitly states when to use ('Use when you need to browse, search...') and advises calling it FIRST. However, it does not explicitly state when not to use it, such as when you already know the specific 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 readOnly/idempotent/safe, and the description adds substantial behavioral context: it fans out across multiple sources in parallel, returns detailed sections, and explicitly explains that empty sections are real 'no data' via sources_used/sources_failed rather than bugs. It also discloses the resolved:false behavior for private companies. This goes well beyond what annotations alone provide.

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

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

The description is long and dense, but nearly every sentence carries useful operational detail. It front-loads purpose and usage preference before enumerating sources and return fields. The main drawback is that it is one large unbroken paragraph, which hurts scannability; bulleted sections would improve structure without removing 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 high complexity, no output schema, and no nested-object schema, the description must carry the burden of explaining return values and edge cases. It thoroughly lists the returned fields, enumerates all data sources, clarifies empty-section semantics, and addresses private-company resolution failures. Nothing critical is missing for an agent to call this tool correctly.

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

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

The input schema already covers both parameters 100%, including detailed descriptions for type and value. The description adds value with concrete examples ('AAPL', '0000320193', 'Moderna'), clarifies zero-padded CIK formatting, and explains name resolution and private-company fallback behavior. This is above the baseline for schema-covered parameters but not extraordinary.

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 then states 'full cross-source profile of a US public company in ONE parallel call.' This gives a specific verb (profile/brief), resource (US public company), and scope (cross-source holistic view). It also distinguishes itself by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups,' which sets it apart from sibling lookup tools.

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

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

It explicitly tells the agent when to choose this tool: 'when the user asks for a holistic view' and to prefer it over chaining multiple single-source lookups. It also clarifies acceptable inputs (ticker, CIK, or name), how private companies are handled, and that 'type' accepts 'company'/'ticker' interchangeably. This is clear routing guidance with no ambiguity.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description adds no new behavioral context beyond confirming deletion. No contradiction.

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

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

Two sentences, front-loaded purpose and usage. 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?

Simple tool with 1 param, no output schema. Description and annotations together are sufficient for an agent to select and invoke.

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

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

Schema coverage is 100% with the key parameter described. Description adds no further parameter meaning beyond 'by key'.

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

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

Description states 'Delete a previously stored memory by key' – specific verb and resource. Siblings include remember and recall, making deletion distinct.

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: stale context, task done, clearing sensitive data. Mentions pairing with remember/recall. No explicit exclusions but context is clear.

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

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

Adds context beyond annotations: fetches page, extracts title/description/key links, emits standard markdown, output ready for site-root/llms.txt. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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?

Concise, well-structured: main action first, then process details, then use cases. Every sentence adds value, no redundancy.

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

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

Given simple tool with 2 params, no output schema, and rich annotations, the description fully covers purpose, behavior, output format, and common use cases. No gaps.

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

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

Schema coverage is 100%, so description adds little beyond what schema already provides. It notes default and max for max_links, which are already in schema description. Implicitly clarifies that url is the target to fetch.

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

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

Description clearly states it generates an llms.txt file for a URL, with examples of use cases (client indexing, own project, competitor audit). Distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on generating the standard file format.

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

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

Explicitly lists when to use (getting a client's site indexed, drafting for own project, auditing competitor). Does not provide explicit when-not-to-use or alternatives, but the specific function makes usage clear.

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

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

Annotations already establish the operation is read-only and idempotent. The description adds value by enumerating the returned fields (latest version, description, homepage, repository, SDK environment, publish date) and noting the publish date comes from the pubspec. This gives the agent a concrete expectation of the response without contradicting the annotations.

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

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

The entire description is one well-structured sentence with the core purpose front-loaded and a compact list of returned metadata. Every part contributes useful information with no filler.

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

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

The tool is simple, has one well-documented parameter, and is fully annotated as read-only and idempotent. The description compensates for the lack of an output schema by explicitly listing the return fields, so nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, and the single 'name' parameter is already well documented with examples. The description adds contextual framing (Dart/Flutter package on pub.dev) but does not add significant new meaning to the parameter itself, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Get metadata'), the resource ('Dart/Flutter package on pub.dev'), and the specific fields returned. This distinguishes it from sibling tools like get_package_score and list_versions, which cover different aspects of a package.

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

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

The description implies the tool should be used when package metadata is needed, but it does not explicitly contrast it with alternatives such as search_packages, get_package_score, or list_versions. There is a clear usage context but no when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful detail about what data the tool reports, but it does not disclose behavioral aspects such as whether it queries live pub.dev data, possible latency, or how missing packages are handled. This stays at the calibrated baseline for annotation-covered read tools.

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

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

The description is a single, front-loaded sentence that immediately identifies the tool's purpose and then lists the returned data components. Every part adds useful information without repetition or filler.

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

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

For a simple one-parameter read-only tool with no output schema, the description is largely complete: it identifies the input and describes the main output categories. It could go slightly further by noting behavior for invalid or nonexistent package names, but such an edge case is minor given the openWorldHint and the simplicity of the tool.

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

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

Schema coverage is 100%, with the 'name' parameter already explained and given an example. The description reinforces that the package is a Dart/Flutter pub.dev package, but it does not add materially new parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Get') and a specific resource ('the pub.dev quality score for a Dart/Flutter package'), and then enumerates concrete components of that score. This distinguishes it well from nearby siblings like get_package or search_packages, which target package metadata or discovery rather than scoring.

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

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

The description gives clear context for when the tool is appropriate: whenever the agent needs a package's pub.dev quality score and its component metrics. It does not explicitly mention alternatives or exclusion conditions, but its specificity makes the use case obvious and effectively routes around search or metadata tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details (returns specific fields, active by default) without contradicting annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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

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

Given the simplicity (1 optional param, no output schema), the description fully covers purpose, usage, and return structure.

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%, so baseline 3. Description does not add meaning beyond schema for the parameter; it only states implicit 'active' default.

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 lists the caller's active subscriptions, and specifies the returned fields, which distinguishes it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No explicit when-not, but context is clear.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful context beyond those annotations by scoping the operation to 'published versions' on pub.dev and describing the exact output shape, without contradicting any annotation.

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

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

The description is a single efficient sentence with no filler. The core action and resource are front-loaded, and the return payload details are included without unnecessary elaboration.

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

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

For a one-parameter, read-only tool with no output schema, the description is complete: it states what the input is, what scope is covered, and what the response will contain. Annotations cover the behavioral safety profile, so nothing necessary for correct invocation is missing.

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

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

The schema has one parameter, 'name', with clear documentation ('pub.dev package name, e.g. "http"'), giving 100% schema description coverage. The tool description adds no new parameter-level meaning, so the baseline score 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 the specific verb 'List' and clearly identifies the resource: 'all published versions of a Dart/Flutter package on pub.dev.' It also specifies the return contents (version strings, publish dates, current latest version), making it distinct from siblings like get_package or search_packages.

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

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

The description implies this tool should be used when version history is needed, but it does not explicitly mention alternatives or state when not to use it. Sibling tools like get_package or get_package_score may also be relevant for package metadata, and no routing guidance is provided.

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

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

Annotations provide no safety hints (all false), so the description must disclose behavior fully. It does: filing returns a claim_token, you can later read the response by passing that token alone, the team reads digests daily, rate-limiting is 5 per identifier per day, and it's free and doesn't count against quota. 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?

Though the description is longer than average, every sentence earns its place. It starts with the main purpose, then usage cases, exclusion criteria, formatting guidance, token workflow, and policies. No fluff or redundancy; the structure is logical and front-loaded.

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

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

There is no output schema, but the description explains what to expect (claim_token) and how to follow up. The nested context object is sufficiently documented in the schema, and the description adds the important scoping constraint (only this Pipeworx connection) and rate-limit info. Nothing critical is missing for an agent to use this correctly.

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

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

Schema coverage is 100%, but the description adds critical usage context beyond the schema: it explains the claim_token dual-mode workflow (file vs read), specifies that message should be 1-2 sentences typical and not include the user's prompt, and maps type categories to real scenarios. This goes well beyond the baseline schema descriptions.

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

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

The description opens with a clear, specific purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team) and the action (feedback), and distinguishes itself from the sibling research tools by focusing on reporting issues rather than retrieving information.

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 by categorizing bug, feature/data_gap, and praise scenarios. It also provides a clear when-not-to-use rule: if the tool came from a different MCP server, file with that server instead. It even includes a fallback ('Not sure? Pipeworx tool names are the ones this connection lists') and formatting instructions, making it unambiguous for an agent.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). These details go beyond annotations and help the agent understand side effects.

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

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

Two sentences with clear structure: core output, use cases, then data provenance. Every sentence adds value. No redundant or vague phrasing.

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 (1 param, no output schema), the description covers purpose, use cases, parameter semantics, data origin, caching, and privacy. Nothing missing given the complexity.

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

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

Schema covers 100% with enum description. Description adds functional meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the right window.

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?

Clear verb ('Returns') and resource ('top tools, top packs, and total call volume over a recent window'). Use cases explicitly listed, distinguishing it from siblings that are mostly query/entity 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?

Three specific use cases provided, plus guidance on window selection (short vs long windows). Does not explicitly say when not to use, but 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?

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context: algorithmic details (Jaccard similarity, partition filter, fill check), response structure, and concrete conditions for acting on signals. No contradiction exists between annotations and description.

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

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

The description is front-loaded with the core purpose, then structured into clear sections for each mode, followed by important filters and fill check. Every sentence adds value for such a complex tool; no unnecessary verbosity.

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

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

Despite lacking an output schema, the description thoroughly explains the response: opportunities array fields, partition_check object, and fill check details. It also covers edge cases like placeholder filtering and similarity thresholds, making the tool fully explainable to an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial extra context: examples of valid event slugs, explanation that topic searches related events, and behavior of each mode. This exceeds the baseline of 3 for high coverage, meriting 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: trending scan, event-specific, and cross-event topic scan. The verb 'find' and resource 'arbitrage opportunities' are specific, and the detail differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit usage guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also advises when not to trade via the fill check and points to an alternative tool: 'For custom sizing use polymarket_fill_risk'.

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?

Description fully discloses behavior: three response segments, caching (1h), diagnostics, and detailed edge calculations. Annotations already confirm readOnlyHint=true, and description reinforces that the tool reads and analyzes, no mutation. No contradictions.

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

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

Description is thorough and well-structured with clear sections (segments, knobs, response structure), but it is lengthy. Every sentence adds value, but conciseness is slightly sacrificed for completeness.

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

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

Given no output schema, the description fully explains the response structure (by_segment, diagnostics, per-opportunity fields) and all filters/knobs. It provides enough context for an agent to understand what the tool returns and how to use it effectively.

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

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

Schema coverage is 100% with descriptions, but the description adds significant value with usage tips (e.g., 'Bump for very thin partitions'), clarifies tradeable-edge knobs, and explains how knobs interact like min_partition_leg_kelly vs min_kelly.

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

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

Description clearly states the verb 'scan' and resource 'Polymarket markets', and specifies the unique purpose of finding opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools by detailing specific model families and segments.

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?

Description provides clear context for use ('what should I bet on today') and implies discovery without paging. However, it does not explicitly exclude alternatives or mention when not to use this tool over siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 provides extensive behavioral context beyond annotations: it details the output structure (tracked, expired, snapshot_dates), explains limits (60-day TTL, daily closes), and clarifies that decay is computed from daily closes. Annotations already indicate read-only, idempotent, and non-destructive behavior.

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

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

The description is well-structured and front-loaded with the key question. It covers args, response format, and limits in a logical order. While somewhat dense, every sentence adds value, and the length is appropriate for 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?

The description is comprehensive given the lack of an output schema. It fully explains the response structure (tracked, expired, snapshot_dates) and important caveats (TTL, decay calculation). For a tool with moderate complexity, this is complete and self-contained.

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

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

Schema coverage is 100%, and the description largely repeats schema info for days and window. It adds minimal extra context (e.g., 'clamp 2-30' for days), but overall does not significantly enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's purpose: to provide edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends.

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 edge persistence info is needed) but does not explicitly mention alternatives or when not to use it. Given the sibling context, it is clear enough for an agent to decide.

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

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

Annotations indicate read-only and idempotent behavior; description adds critical context: walks the order-book ladder, returns fill metrics, and warns that partial basket fills convert arbitrage into unhedged directional positions—the dominant loss mode. No contradictions.

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

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

The description is long but well-structured with explicit single-market and basket sections. Every sentence provides essential information. Slightly verbose but 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?

Despite no output schema, the description thoroughly enumerates return fields for both modes, including verdicts, profit, and risk indicators. With 4 parameters and no nested objects, the description is fully adequate.

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

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

Schema coverage is 100%, but description enhances each parameter with mode-specific meanings, defaults, and constraints (e.g., side defaults differ by mode, size_usd interpretation). Adds substantial value beyond schema.

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

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

The description clearly states it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinctly explains single-market and basket modes. It differentiates itself from siblings by advising use before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500.

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 specifies when to use (before arbitrage/edge signals above ~$500) and prerequisites (requires 'market' or 'event'). Does not explicitly state when not to use, but context makes it clear.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing fee handling (gross vs net spread), compatibility codes and their meanings, the semantic of null temporal_alignment, and skipped comparison counters. It even exposes the tool's own heuristic limitations, such as keyword-only pairing.

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

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

The description is long but information-dense; it front-loads purpose and then systematically covers modes, response, safety fields, and caveats. While not concise in word count, no sentence is filler, and the structure is logical. Slight deduction for the repetitive warnings about non-tradeability.

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 fully compensates by explaining response fields (top_spreads_pp, compatibility_warning/codes, temporal_alignment, fees_note, skipped counters) and edge cases (unknown metric types, null alignment, unclassified legs). Nothing an agent needs to correctly invoke and interpret the tool is missing.

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

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

The schema already provides 100% parameter descriptions with examples, but the main description adds the crucial behavior that kalshi_event_ticker and polymarket_event_slug overrides the topic-mapped side, and that both modes run the identical token-overlap matcher. This enriches understanding beyond the schema.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names exactly what the tool compares, distinguishes this from Polymarket-only siblings by naming both venues, and immediately explains the core 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?

It defines two explicit modes (topic shortcuts vs explicit tickers), explains when each is appropriate, and warns that pre-mapped shortcuts are not guaranteed tradeable. It stops short of naming sibling alternatives for when not to use the tool, but the context is strong 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping ('scoped to your identifier') and the relationship with other tools. No contradiction with annotations.

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

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

The description is three sentences long, front-loaded with the primary purpose, and each sentence adds necessary context without redundancy. Highly efficient.

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 adequately explains the return behavior (value or list). It covers usage, scoping, pairing, and provides examples. For a simple read tool with comprehensive annotations, it is fully complete.

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

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

Schema coverage is 100% with a single optional 'key' parameter. The description adds meaning by stating that omitting the key lists all saved keys, and provides examples of what keys are used for (target ticker, address, research notes).

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: 'Retrieve a value previously saved via remember, or list all saved keys.' It specifies the verb (retrieve/list) and resource (stored memory values), and distinguishes from sibling tools like remember and forget.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds value by explaining the mark_read flag's effect on subsequent calls and the returned fields, providing behavioral detail beyond annotations.

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

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

Three sentences, front-loaded with the main purpose. Each sentence adds value: purpose, return fields/filtering, behavioral note, and alternative access. Could be slightly tighter but no wasted words.

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

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

With no output schema, the description explains return structure (source, citation_uri, payload). Combined with annotations covering idempotency and safety, and mention of polling/alternate URL, it provides sufficient context for a simple read tool.

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

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

Schema covers 100% of parameters with descriptions. The description reiterates filtering by type and since, but adds meaningful context for mark_read (flagging events as read to affect next call). This goes beyond repeated info.

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 'Pull[s] fired events from your subscription feed' and specifies return fields (source, citation_uri, payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on events, not subscription metadata.

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 mentions filtering by type and since, and notes that polling works fine. Also provides an alternative endpoint for scripts/dashboards, giving context on when to use the tool vs. direct HTTP access. Could be improved by stating when not to use it.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable behavioral details: parallel calls, GDELT→GNews fallback, USPTO soft-fail, return format with citations. No contradictions.

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

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

Description is information-dense yet well-structured: example queries first, then source logic, parameter details, return format, alternative tool. Every sentence adds value with no redundancy.

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

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

Given no output schema and multi-source complexity, the description fully covers behavior (fallback, soft-fail), parameter options, return structure, and sibling tool differentiation. Compensates for lack of output schema.

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

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

Schema coverage is 100% with descriptions for all parameters. Description reinforces parameter formats (e.g., 'since' examples) but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool provides a change feed for a company in a given time window, listing specific sources (SEC, GDELT/GNews, USPTO) and example queries. It distinguishes from sibling tool entity_profile, which offers static data.

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

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

Explicit advice: 'Use entity_profile instead when you want the static profile...' provides clear guidance on when not to use. Also implies usage for recent changes/news/filings.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

The description is four sentences, each adding essential information. It front-loads the main purpose and efficiently covers usage, scope, and pairing with siblings. No wasted words.

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

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

The tool is simple (two required params, no output schema). The description explains persistence behavior and pairing with recall/forget, which is sufficient. A small improvement could mention that the tool likely returns nothing or a confirmation, but the omission is minor.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description provides example key names and clarifies value as 'any text,' but these largely repeat the schema's own descriptions. Thus, the description adds minimal semantic 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: 'Save data the agent will need to reuse later.' It specifies the action (save), the resource (data as key-value pairs), and distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning them.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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 signal read-only, open-world, idempotent, and non-destructive behavior; the description adds substantial meaningful context on top: multiple internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, `figi_candidates` for ambiguous matches, source-labelled identifiers, and ownership data when available. This goes well beyond structured fields.

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

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

The description is long and dense, with many nested parenthetical clauses, but it is front-loaded with examples and scoping, and every cluster adds necessary behavior for a complex tool. It could be better organized with bullets or shorter sentences, but it earns most of 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?

Despite having no output schema, the description covers what the tool returns for each type, how ambiguity is handled, what happens on partial enrichment failure, what inputs are accepted, and how to phrase names. It also explains the internal cascade so an agent understands the cost and value of the call. This is unusually complete for a tool with no structured output schema.

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

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

Schema coverage is 100%, but the description still adds significant value beyond the schema. It explains what `type: company` resolves (CIK, ticker, LEI, FIGI, ownership), what `type: drug` resolves (RxCUI, ingredient, brand), and gives precise `value` guidance including negative examples like 'NEW YORK ST DORM AUTH' vs 'NEW YORK ST DORM AUTH revenue bonds'.

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

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

The description opens with concrete natural-language triggers, then states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require.' This clearly distinguishes it from siblings like entity_profile and compare_entities: this tool is specifically about getting identifiers from names, not building profiles or comparing entities.

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

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

It gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies that an ISIN resolves to the issuing legal entity, that non-equity instruments resolve, and warns against passing full noun phrases for bonds. It does not explicitly name alternatives to use instead in specific cases, but the 'when to use' guidance is strong and unambiguous.

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

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

The description explains internal behavior (probes each entity with ai_visibility_check), output structure (ranked list with score, confidence, signal density), and does not contradict annotations (readOnlyHint, idempotent, etc.).

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

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

Two sentences, front-loaded with key action, no fluff. Every sentence adds value.

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

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

Despite lacking an output schema, the description explains the return format sufficiently. All necessary context (parameters, use case, internal call) is covered.

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 includes detailed descriptions for all parameters. The description adds minimal extra meaning beyond restating the schema's first-entity-as-subject convention, so baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, and ranks results. It differentiates from sibling 'ai_visibility_check' which is a single-entity probe.

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?

Description gives explicit use case ('competitive AI-marketing audits') and example question. It mentions the underlying tool but does not discuss when not to use or compare with other siblings 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details: bundlephobia first measurement can take 5-30s, and sources_failed lists failures. No contradiction.

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

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

The description is dense and front-loaded with purpose, but slightly verbose. Every sentence adds value, though it could be tightened without losing clarity.

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

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

Given the tool's complexity (multiple sources, partial failures, return summary), the description covers key aspects: return structure, fallback behavior, and timing. No output schema exists, but the description compensates.

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

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

Schema coverage is 100%, already describing both parameters. The description adds that version defaults to latest and scoped packages are accepted, but these are minor additions 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 as a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, and tree-shake support. It distinguishes itself from the fallback deps.dev:version tool for other ecosystems.

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 tells when to use: 'whenever an agent asks "is X safe / popular / small"'. Also notes NPM-only in v1, and mentions graceful partial failure handling.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior, so the description need not restate safety. It adds meaningful context by naming pub.dev as the source and disclosing that results include matching names and a next-page URL.

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

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

Two sentences with no filler. The search target and input framing appear first, and the return summary follows immediately.

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 two-parameter external search tool with full schema coverage and read-only annotations, the description covers source, behavior, and return content. No output schema exists, so the explicit mention of package names and next-page URL fills that gap.

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

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

Schema coverage is 100%: query and page are both described, including default page. The description's only parameter-related contribution is the general keyword framing, which does not raise it above 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 clearly identifies a search over pub.dev for Dart & Flutter packages by keyword, which is a specific verb+resource. It does not explicitly contrast with sibling tools like get_package or list_versions, but the search-vs-retrieve distinction is reasonably evident.

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 use case is implied by 'by keyword': choose this tool when the agent needs to discover packages rather than fetch a known package. It offers no explicit guidance about when not to use it or which sibling (get_package, list_versions) to prefer for package details.

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 (readOnlyHint, idempotentHint), the description discloses the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character cap (200K chars with truncation+flag), and output details (offsets, scores). 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 well-structured, starting with the core purpose, then usage guidance, then technical details. It is moderately long but every sentence adds value. Minor redundancy could be trimmed, but overall it is concise and 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 tool with no output schema and moderate complexity, the description covers input, output (passages with offsets/scores), limits (200K chars), and technical details (embeddings, chunking). It also mentions a sibling pairing, making it a complete reference for the agent.

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

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

Schema coverage is 100% with descriptions, but the description adds value by giving concrete examples for the query parameter and explaining how to use the text parameter (e.g., SEC 10-K body, article). This helps the agent understand the intended use beyond schema types.

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 that the tool performs semantic search inside a fetched record, returning top-N passages with offsets and scores. It distinguishes itself from siblings by mentioning its pairing with ask_pipeworx_grounded and the use case for large records.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative and pairing suggestion: 'Pairs with ask_pipeworx_grounded.' This gives clear guidance on how to choose this tool among 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?

The description adds valuable behavioral context beyond annotations: OAuth requirement, delivery channel specifics, SMS cap, webhook signing secret one-time return, and auto-disable condition. Annotations indicate idempotentHint=true and readOnlyHint=false, which are consistent.

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 main purpose and is well-structured, but it is somewhat lengthy. It could be slightly trimmed while retaining all essential information.

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

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

For a tool with no output schema, the description covers return value, requirements, type-specific parameters, delivery options, and limits. It sufficiently prepares the agent for invocation, though some minor details (like the exact format of the returned ID) are omitted.

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?

All parameters are fully described in the schema (100% coverage). The description further enriches by providing type-specific parameter examples for each subscription type, such as 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}', adding meaning beyond the schema.

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

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

The description clearly states the verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions by focusing on creation.

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 requirements (Pipeworx OAuth account, not anonymous/BYO) and provides examples for each subscription type. It implies when to use (to create a subscription) but does not explicitly mention alternative tools for listing or unsubscribing.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it is an onboarding entry point, returns examples with exact tool+argument shape drawn from live catalog, and explains topic filtering. 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 relatively long but front-loaded with key phrases and organized with lists. It could be slightly more concise, but every sentence contributes useful information without redundancy.

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

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

Despite lacking an output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shape). It covers purpose, usage, parameter behavior, and context, making it complete for the tool's role as an onboarding guide.

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 a basic description for the `topic` parameter. The tool description adds meaningful detail: lists example topic values (finance, pharma, etc.) and explains behavior when omitted (full spread) or provided (focus). This adds semantic 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 explicitly states the tool returns category-bucketed example questions for onboarding and discovery. It distinguishes itself from siblings by specifying it should be used first when the agent doesn't know what Pipeworx can do, and mentions meta-tools like ask_pipeworx.

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

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

The description gives clear when-to-use instructions: '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 describes calling with no arguments for full spread or with a topic to focus.

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 important details beyond annotations: ownership enforcement, row deactivation (not deletion), and availability of historical events via recent_alerts. No contradiction with annotations.

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

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

Two sentences, front-loaded with the key action, no unnecessary words.

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

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

Given simple tool with one parameter and no output schema, description fully explains behavior and outcome.

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 with description for the single parameter. Description does not add new meaning beyond the schema.

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

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

Description clearly states the action ('Cancel a subscription by id'), the resource ('subscription'), and distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Describes when to use (cancel subscription) and ownership enforcement. Lacks explicit 'when not to use' or alternative tools, but context with siblings is clear enough.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral details: the two routing paths, verdict semantics including the definitive caveat that 'could_not_verify means the check did not happen' and 'must not be shown as evidence', and the unsupported verdict meaning no source coverage. It also explains error handling via verification_error{stage,detail} and the percent-delta math. 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 well-structured, front-loaded with natural-language trigger phrases. Each section serves a purpose: examples, routing, verdicts, and error warnings. There is minor redundancy (e.g., 'natural-language' appears multiple times) but no wasted sentences. It might be slightly dense but remains focused and scannable.

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

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

With no output schema, the description fully explains the return values: the six verdicts, the actual value with pipeworx:// citation, and reasoning. It also covers failure modes (verification_error) and the difference between could_not_verify and unsupported. This is a complete picture for a tool with two simple parameters and no nested objects, making it easy for an agent to interpret results correctly.

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

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

The input schema already covers both parameters with descriptions and examples, so the baseline is 3. The description adds extra value by explaining that tolerance_pct overrides the tolerance implied by the claim wording and gives a specific use case ('set 1–2 for hallucination detection'). This goes beyond the schema's stated range and default.

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: natural-language claim verification against authoritative sources, with examples of trigger phrases. It distinguishes itself from generic search tools by describing specialized routing (SEC EDGAR fast path for company-financial claims, grounded pipeline for other facts) and a categorized verdict output. This is a specific verb+resource combination, not a tautology.

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 whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrase examples. It also differentiates between claim types (company-financial vs. other) and notes it replaces 4–6 sequential calls. However, it does not name sibling tools or explicit exclusions, so it stops short of a full when-not-to-use list.

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