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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it routes across 5,695 tools, fills arguments automatically, returns stable citation URIs, works on every tier in one fast call, and explicitly disclaims grounding (deferred to a sibling). It does not mention failure modes or rate limits, but with the annotation burden already met, the added context is solid.

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

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

The description is long but every sentence earns its place for a flagship entry-point tool: preference rule, domain list, routing behavior, trigger phrases, examples, tier/performance note, and escalation paths. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'). Minor redundancy ('even if web search could also answer it' partially echoes the opening) keeps it from a 5.

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

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

There is no output schema, yet the description discloses the return shape: a structured answer with stable pipeworx:// citation URIs. It covers scope (which domains and question types), when not to use it (grounded, deep_research), how to escalate, and realistic usage examples. For a tool with a single required parameter and high routing complexity, nothing essential is missing.

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

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

Schema coverage is 100% — every parameter (question plus five aliases) is documented in the schema, so the baseline is 3. The description's examples and trigger phrases ('what is', 'look up', 'find') are about when to call the tool, not about parameter meaning, so it adds no semantic value beyond the schema. This is acceptable because the schema already does the heavy lifting.

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

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

The description states a specific verb and resource: it routes a question to the relevant one of 5,695 tools and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings by naming ask_pipeworx_grounded (hallucination-resistant, verbatim evidence) and deep_research (fan-out), so an agent can tell them apart without opening schemas.

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

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

The description opens with an explicit preference rule ('PREFER OVER WEB SEARCH'), declares itself the default entry point ('START HERE for most questions'), and gives concrete step-up conditions: use ask_pipeworx_grounded for a hallucination-resistant single answer, deep_research for broad/multi-part questions. It even handles the breaking-news edge case by pointing to built-in live-news routing. Nothing is left to inference.

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

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

The description reveals a critical behavioral trait that annotations cannot capture: this tool's behavior changes over time as routing candidates are enabled and retired live. It discloses the current state (no active candidate as of a specific date, so it currently matches ask_pipeworx exactly) and clarifies the fallback semantics ('Falls back to nothing — this IS a full working router'). This is substantial value beyond the readOnly/idempotent annotations, which are consistent with the 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?

Four sentences, each earning its place: identity and scope, current operational state, usage guidance, and fallback behavior. The most decision-relevant fact (this is the experimental beta) is front-loaded, and the specific tool count and retirement date add credible precision rather than fluff.

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

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

For a beta-twin tool with annotations covering the safety profile and 100% schema coverage, the description closes all the meaningful gaps: it explains the experimental nature, the current no-op state relative to the stable router, how to invoke it, and the fallback guarantee. The response shape is delegated to ask_pipeworx ('same response shape'), which is a valid reference given the tool is explicitly a twin.

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% — every parameter (question, q, text, input, prompt, query) is documented in the schema, with the aliases clearly explained. The description adds only 'same arguments' as ask_pipeworx, which redirects the agent to the sibling for deeper semantics rather than adding new meaning. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb-resource pair ('Beta version of ask_pipeworx') and precisely scopes what it is: an identical universal router with candidate routing improvements. It explicitly distinguishes itself from the stable ask_pipeworx and the grounded variant by detailing the relationship ('identical... with candidate routing improvements enabled live'). An agent can tell exactly what this tool is and how it relates to its siblings.

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

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

The description gives an explicit trigger condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the operational consequence (results compared against the stable router to decide what merges), which helps the agent understand the stakes of choosing this variant. It does not explicitly state 'when NOT to use it' or name the stable alternative by name, but the experimental-vs-stable framing makes the exclusion reasonably clear.

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

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

Annotations already declare readOnly/openWorld/idempotent; description adds a valuable behavioral contract: return shape, refusal_reason enum, extra LLM call cost, and the constraint that evidence comes from tool output. No contradiction with annotations.

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

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

Five dense sentences, each earning its place: purpose, routing behavior, return contract, usage criteria, and cost trade-off. Front-loaded and structured without fluff.

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

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

No output schema exists, so the detailed success/refusal return contract in the description is essential and provided. Routing scope, refusal reasons, cost, and usage threshold are all covered. Nothing an agent needs to decide whether to invoke it is missing.

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

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

Schema description coverage is 100%, with all aliases for 'question' documented in the schema. The description does not add param-specific meaning beyond restating that the tool fills arguments internally, so the baseline 3 applies.

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

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

States a specific behavior: hallucination-resistant grounded answering for high-stakes reads, using only tool results. Clearly distinguishes from ask_pipeworx by emphasizing extraction and explicit refusal. Verb and resource are concrete.

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 (quoted, cited, or acted-on answers) and when not to (casual lookups, prefer ask_pipeworx). Names the sibling alternative and the cost trade-off. Strong routing guidance.

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

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

The description 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?

Beyond the readOnly/idempotent/openWorld annotations, it discloses account and paid-plan requirements, 15-60s latency (up to ~90s), parallel decomposition across 5,695 tools, gaps[] rather than invented answers, contradictions[] for standard/thorough, semantic excerpting, and the guarantee that citation_uri is only present when fetchable. This is unusually complete behavioral disclosure.

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

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

Though long, it is front-loaded with the most decision-critical facts (account required, fallback tool) and every subsequent sentence adds distinct behavioral or usage information. No filler or restatement of the schema.

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

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

With no output schema, the description carries the burden of explaining the return packet, and it does so concretely: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], and contradictions[]. It also covers duration, auth, and the fallback path, so an agent has everything needed to invoke and interpret the call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: depth's behavior is fleshed out (quick=3 facets, standard adds gap recovery + contradictions, thorough is paid and chases leads) and question's broad/multi-part nature is affirmed. It also warns that topics outside the structured catalog return mostly empty gaps[], which is materially useful for parameter choice.

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

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

The description opens with a precise verb and resource: 'Grounded multi-source research across Pipeworx's 1491 STRUCTURED data sources' in one call, and explicitly distances it from open-web search. It distinguishes itself from ask_pipeworx by naming when each is appropriate, so an agent can identify it among the sibling list 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?

It gives explicit selection rules: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups or breaking/current-news topics, and use ask_pipeworx if not signed in. It also maps depth values to use cases ('standard' gap recovery, 'thorough' lead chasing), leaving no ambiguity about when this tool wins over alternatives.

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

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

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 readOnlyHint=true and destructiveHint=false. Description adds behavioral details such as 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' and notes soft-fail for patents and fallback for news. No contradictions, but could mention rate limits or performance characteristics.

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 every sentence adds value, including example queries and detailed return structure. It front-loads the most important usage patterns.

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?

Considering the tool's complexity (multiple data sources, optional fields, fallbacks), the description covers most aspects. No output schema, but return fields are listed. Could mention pagination or limits on returned items, but overall 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%, but description adds meaning: explains that type is only 'company' and value can be ticker or zero-padded CIK, and that names are not supported. This clarifies usage 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: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific examples of queries and explicitly differentiates from sibling tools like resolve_entity.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use it: 'names not supported (use resolve_entity first if you only have a name).'

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the caveat about structural mismatches making spreads meaningless. 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 each sentence adds unique value. Front-loaded with purpose, then modes, response, safety. Could be slightly more concise, but 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?

Given complexity (3-param, no output schema), the description covers purpose, dual modes, return structure, safety warnings, and temporal alignment. Agents can understand when to use and how to interpret results.

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 3 parameters. Description enriches them by explaining topic list, explicit override behavior, and response fields (leg prices, spread, safety fields). Adds substantial meaning 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 the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on two venues and explicitly mentioning structural mismatches.

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 explains two modes (topic shortcuts and explicit tickers) with clear examples. Warns that most pre-mapped topics currently return compatibility_warning, guiding the agent to not expect actionable spreads. Lacks explicit 'when not to use' but overall strong.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds crucial behavioral context: identifier source labeling, explicit reporting of unresolved identifiers, graceful degradation of LEI/FIGI enrichment, and internal cascading through multiple endpoints. This goes well beyond the annotations' safety profile.

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 contains many parenthetical details, making it somewhat long and hard to parse. However, it is well-organized conceptually, front-loads the purpose with examples, and every sentence adds substantive information. It is not rambling, but could be formatted with clearer section breaks.

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 provides a remarkably complete picture: it covers all supported entity types, input variations, the nature of returned identifiers (CIK, LEI, FIGI, RxCUI), source labeling, unresolved handling, and fallback behavior. It also explains why the tool is useful ('replaces 2-3 manual lookups'), making it self-contained for an agent.

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

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

Even though schema coverage is 100%, the description enriches both parameters significantly. It explains that 'type' supports company/drug with different resolution behaviors, and for 'value' it gives concrete examples, explains ISIN-to-LEI mapping, and notes that brand or generic names are accepted for drugs. This far exceeds the schema's minimal parameter descriptions.

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

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

The description clearly states a specific action: resolving user-spoken names to canonical/official identifiers. It explicitly distinguishes the tool's scope ('other tools require as input') and provides concrete examples ('ticker for...', 'CIK for...'), making it distinct from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and input formats. However, it does not explicitly state when NOT to use the tool or name alternative tools, so it falls slightly short of a 5.

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

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

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.