Poetrydb

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

Description adds significant behavioral context beyond annotations: explains default model, API key handling (passed through to Anthropic), cost implications, and return structure. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; description confirms and enriches without contradiction.

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

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

Three sentences clearly convey purpose, parameters, and use cases. No redundant information. Front-loaded with the main action and result.

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, description explains return format (per-model fields + combined view). Covers authentication, free vs paid, and typical use cases. All parameter behaviors are fully described.

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 4 parameters have schema descriptions (100% coverage). Description adds value by explaining default model, supported models list, API key passthrough behavior, and context disambiguation. It goes beyond schema with usage examples and clarifications.

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 probes LLMs for brand visibility and scores it (0-100). It specifies the default free model and the optional Anthropic model with API key. It distinguishes from siblings by focusing on multi-model visibility scoring for marketing audits.

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

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

Description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly exclude other uses or compare to sibling tools like ask_pipeworx, but the 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: it routes dynamically to 5,798 tools, fills arguments automatically, returns structured answers with pipeworx:// citation URIs, and can reach live news. No contradiction with annotations.

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

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

The description is long but front-loaded with the most important guidance: PREFER OVER WEB SEARCH, followed by supported domains, examples, and explicit upgrade/alternative paths. There is slight redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it', but the length is justified for a complex router tool.

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

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

The description covers what questions to ask, what triggers to use, how the tool behaves internally, what the response includes, and when to use sibling tools instead. Given no output schema, mentioning structured answers with stable citation URIs is sufficient for an agent to interpret the result. Nothing critical is missing.

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

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

Schema description coverage is 100%: every parameter, including aliases, is documented in the input schema. The description adds useful examples and trigger phrases but does not add new parameter-level semantics beyond what the schema already provides. 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 that the tool routes natural-language questions to the right one of 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It differentiates itself from web search and sibling tools by specifying domains, trigger phrases, and concrete examples.

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 prefer this over web search for authoritative factual data, gives trigger phrases such as 'what is', 'look up', 'get the latest', and 'how much', and names alternatives: ask_pipeworx_grounded for tightly grounded answers, deep_research for broad multi-part questions, and notes that breaking-news queries are already handled. This gives an agent clear selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds genuinely valuable context beyond those: beta status with candidate improvements enabled live, the current inactive state (last candidate retired 2026-07-26, so it currently matches ask_pipeworx exactly), and the 'Falls back to nothing — this IS a full working router' clarification. Consistent with annotations; 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?

Four sentences, each earning its place: beta identity, current candidate state, usage guidance, and fallback clarification. Key information is front-loaded with the beta distinction first; the embedded retirement date may eventually go stale but does not undermine current 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?

For a router tool with no output schema, the description adequately covers what it is, how to use it, its current behavior, and the expected response shape ('same response shape' as ask_pipeworx). Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with all six parameters (question plus five aliases q, text, input, query, prompt) fully documented in the schema itself. The description adds no parameter detail, which is acceptable since the schema carries the full burden; the baseline 3 applies.

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

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

The description states a precise purpose: an experimental universal router identical to ask_pipeworx (same 5,798 tools, same arguments, same response shape) with candidate routing improvements. It clearly distinguishes itself from the stable ask_pipeworx sibling by its beta/experimental nature and from ask_pipeworx_grounded by virtue of being the same router as ask_pipeworx.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' The stable ask_pipeworx is implicitly the alternative for production needs, though no explicit exclusion like 'do not use when you need stable behavior' is stated.

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

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

The description adds rich behavioral detail beyond the annotations: it discloses exact return fields, explicit refusal reasons, evidence extraction using only tool results, and the extra LLM call cost. Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description does not contradict them.

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

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

The description is dense but every sentence adds value: purpose, behavior, return format, use cases, and cost trade-off. The return-format listing is somewhat long but is justified because there is no output schema to carry that 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?

Given no output schema, the description fully explains the success response shape, failure/refusal modes, evidence behavior, and cost trade-off. An agent has enough information to decide when to invoke this tool and what to expect from it.

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

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

Schema coverage is 100%, and all parameters are aliases for the same natural-language question field, so the schema already fully documents the inputs. The description adds context about how the question is routed and grounded but does not provide new parameter-level semantics.

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 purpose: hallucination-resistant grounded answering for high-stakes reads, and explicitly contrasts with ask_pipeworx by noting the same routing but grounded evidence extraction. This clearly distinguishes it from sibling tools and tells an agent what the tool is for.

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

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

It gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on...') and explicit when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'), even naming the alternative. This is 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?

Annotations already indicate safe, read-only, idempotent behavior. The description adds extensive context: fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution-rule risk. 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?

Description is long but every sentence earns its place given the tool's complexity. Information is front-loaded with purpose and usage, then details. Could benefit from section breaks but overall well-structured.

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

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

Given no output schema, the description thoroughly covers response shapes, edge cases (closed markets, low confidence, wide spreads), and interpretation guidance. It prepares the agent for all common scenarios.

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. The description adds significant value by explaining how `market` accepts multiple formats, `depth` controls fan-out extent, and `include_raw` affects response size and use cases.

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

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

Clearly states the tool researches Polymarket bets by pulling Pipeworx data. Specifies inputs (slug, URL, question text) and distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on evidence 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?

Explicitly says 'Use for "should I bet on X"' and provides example queries. Though it doesn't directly exclude alternatives, the context of sibling tools and the detailed use cases make the tool's niche 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 rich behavioral context: data source (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and return of citation URIs. 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 front-loaded with trigger phrases and is well-structured. While slightly verbose, every sentence adds value by explaining data sources, sorting, and efficiency gains. Minor redundancy could be trimmed, but overall earns its length.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the presence of a good schema with annotations, the description covers all necessary aspects: use cases, data retrieval specifics, result formatting, and efficiency justification. No output schema, but return format is described.

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

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

Schema coverage is 100% with both parameters described. Description significantly adds meaning: explains what each enum value retrieves (company vs drug data), provides example values (tickers/CIKs for company, names for drug), and specifies constraints (2-5 items). This goes well 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 uses specific trigger phrases ('Compare X and Y', 'X vs Y') and clearly states the verb+resource: side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools like 'entity_profile' and explicitly contrasts with sequential single-pack lookups.

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

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

Provides explicit directive to prefer this tool over sequential lookups when comparing entities. Includes example queries that indicate when to use. Lacks explicit when-not scenarios, but the context is clear enough for correct selection.

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

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

Annotations already provide read-only/idempotent/open-world hints, but the description adds substantial behavior: account and paid-tier prerequisites, facet decomposition, parallel routing, findings packet structure, explicit gaps instead of fabrication, resolvable citation URIs, semantic excerpting, contradictions for certain depths, and latency ranges.

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 every clause contributes, but it is a long single paragraph with heavy semicolon use, which harms scannability. It front-loads important prerequisites and alternatives, so the structure is reasonable overall.

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

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

There is no output schema, so the description must explain return behavior, and it does: verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers prerequisites, alternatives, depth behavior, and expected latency, leaving little ambiguity for an agent.

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

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

Schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds meaning beyond the schema by noting that 'thorough' requires a paid plan and that the question may be broad/multi-part. This is useful but not overwhelming beyond schema coverage.

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

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

The description states a specific action and resource: grounded multi-source research across 1517 structured data sources in one call, with decomposition and parallel routing. It clearly distinguishes itself from open-web search and from ask_pipeworx for single lookups.

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

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

Explicitly says when to use it: broad/multi-part questions over structured data. It also says when not to: single lookups should use ask_pipeworx, and unsigned-in users should use ask_pipeworx instead.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds valuable behavior: returns top-N most relevant tools with full schemas and curated examples, ready to call directly. This goes beyond annotations by detailing the output structure and usage pattern. 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?

Four sentences, each serving a purpose: purpose, domain list, output description, usage advice. Front-loaded with the verb. No wasted words. Structurally clear.

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 6 parameters, 33 siblings, and no output schema, the description covers the tool's role fully: it is a discovery tool that returns ready-to-use tool definitions. It tells the agent when to call it (FIRST) and what to expect. 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% and schema descriptions are good. The description adds context: it explains that the top-N tools are returned, that results include schemas, and mentions aliases like 'task', 'q', 'search', 'description'. This helps the agent understand how parameters affect output.

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 starts with 'Find tools by describing the data or task' which is a clear verb+resource. It then lists numerous domains (SEC filings, financials, etc.), making the scope explicit. It distinguishes from sibling tools which are specific data functions, e.g., search_poems, by focusing on discovery.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear usage context but does not explicitly state when not to use it or list alternatives, though the sibling list implies it's the discovery entry point.

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 richly discloses behavior: it fans out across specific sources, returns sources_used/sources_failed, treats empty sections as real no-data rather than bugs, falls back GDELT→GNews, soft-fails USPTO, and explains expected empty results for FDA products. This is far more than the annotations alone provide.

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

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

The description is long but densely informative, with the core purpose and examples front-loaded before the detailed source/edge-case breakdown. Some phrasing is run-on, but nearly every clause carries distinct useful information and there is no filler.

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

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

For a multi-source, high-complexity tool with no output schema, the description is remarkably complete: it lists all data sections, URI formats, expected edge cases, fallback behavior, and the resolved:false path. An agent has enough context to invoke it correctly and interpret unusual 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%, so the parameters are already documented. The description adds meaningful semantics: type values are interchangeable, value can be ticker/CIK/name, and names resolve via SEC EDGAR's company-name match. This goes beyond the schema's basic field descriptions.

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

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

The description states a specific action and resource: producing a full cross-source profile of a US public company in one parallel call. It opens with concrete user phrasings and explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making the scope and differentiation clear.

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 guidance: ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view. It also clarifies acceptable inputs (ticker, CIK, company name), how private companies are handled, and that person/place support is coming, so an agent knows when this tool is the right choice.

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 idempotentHint=true. The description aligns with these but adds no new behavioral context beyond stating it deletes. Given annotations cover the safety profile, a 3 is appropriate.

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

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

The description is two sentences: first states purpose, second gives usage guidance and pairing. Every sentence adds value with no fluff.

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

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

For a simple destructive tool with one parameter and no output schema, the description alongside annotations and schema covers what, when, and pairing. It could mention return value behavior but is generally complete.

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

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

The input schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete.' The description does not add extra meaning like key format or constraints, so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), and distinguishes from siblings like 'remember' and 'recall' which are for storing and retrieving.

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 explicit use cases: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with remember and recall. However, it does not explicitly mention when not to use the 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 indicate read-only, idempotent, non-destructive behavior. The description adds process details (fetching, extracting, emitting) that align with annotations. It could be more explicit about lack of side effects, but overall good.

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 appropriately sized with three sentences that front-load the core purpose, then provide process and use cases. Each sentence is informative, though minor wordiness is present.

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

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

For a simple read-only tool with two parameters and no output schema, the description covers purpose, process, and use cases. It does not address error handling or fetch failures, but that is acceptable for its simplicity.

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

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

Schema coverage is 100% with parameter descriptions already present. The tool description does not add new meaning beyond restating the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the resource and output format. It distinguishes itself from siblings as no other tool generates llms.txt files.

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 lists specific use cases (client indexing, personal projects, competitor auditing) and provides clear context. However, it does not explicitly mention when not to use the tool or suggest 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?

Adds behavior beyond annotations: 'Returns full poem text (capped)' indicates truncation, and 'Keyless' indicates no auth required. No contradictions with annotations (readOnlyHint, etc.). Could mention pagination or rate limits but not critical given simplicity.

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, no unnecessary words, front-loads key information: full-text search, capped results, keyless. Highly concise and well-structured.

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

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

Adequate for a simple 2-parameter tool with no output schema. Explains core functionality and cap behavior. Could include error handling or timeouts but not essential. Annotations fill gaps on idempotency and read-only nature.

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 parameters are well-documented in schema. Description adds minimal extra (e.g., 'Keyless' not param-related). Baseline score of 3 appropriate as description does not significantly enhance 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?

Clearly states it performs full-text search within poem lines on PoetryDB, identifying the specific verb (search), resource (poem lines), and scope (contains phrase). Distinguishes from sibling tools like 'search_poems' which likely search whole poems or 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?

Mentions 'Keyless' indicating no authentication needed. Implicitly guides usage for line-level search vs broader search. Does not explicitly state when not to use but provides adequate context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds 'Keyless', clarifying no authentication is needed, which is useful 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?

Two succinct sentences with no wasted words, front-loading the core purpose and a key behavioral trait.

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, parameterless listing tool with comprehensive annotations, the description fully covers what an agent needs: purpose and authentication status.

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

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

With zero parameters and 100% schema coverage, no parameter details are needed. The description's 'Keyless' adds slight extra context, fitting the baseline of 4 for no-parameter tools.

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

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

The description clearly states the tool lists all authors from PoetryDB with a specific verb 'List', making it distinct from other query tools like 'search_poems' or 'random_poems'.

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

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

The description implies usage for retrieving all authors without a key but does not explicitly state when to use this versus alternatives or provide exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns specific fields but does not contradict annotations. No additional behavioral context needed.

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: purpose, return fields, usage guidance. Front-loaded, no wasted words.

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

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

For a simple tool with 1 optional param and no output schema, description covers purpose, return fields, and usage. 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 100% with parameter description. Description does not add parameter details beyond schema, but 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?

Clear verb 'List' and specific resource 'subscriptions'. Specifies it returns caller's active subscriptions and lists returned fields. Distinguishes 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 states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This guides agent to use before subscribe/unsubscribe.

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

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

Annotations provide no useful hints (all false), so the description carries the burden. It discloses the claim_token flow (returns token without account, can be passed back to read status), daily rate limit, and that it's free/doesn't count against quota. No contradiction with annotations.

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

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

The description is dense but each sentence earns its place, covering purpose, usage, exclusions, token flow, and rate limits. It's front-loaded with the core purpose, but could be slightly more scannable with paragraph breaks; still, nothing is 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?

Despite no output schema, the description fully explains the response behavior (claim_token retrieval). It covers all necessary context: what counts as valid feedback, filtering by scope, token mechanics, rate limits, and cost. Complete for a tool with only 4 optional params.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: clarifies claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs to describe issues in terms of Pipeworx tools/packs, which enriches the message parameter 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from siblings like ask_pipeworx (querying) and subscribe (alerts), even scoping to 'tools served by this Pipeworx connection'.

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

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

The description explicitly enumerates when to use (bug, feature/data_gap, praise) and when not to use (different MCP server, telling the user to file elsewhere). It also provides practical guidance like 'Describe the issue in terms of Pipeworx tools/packs' and mentions rate limits, giving clear contextual triggers.

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

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

Adds context beyond annotations: describes data source (CF analytics-engine), no PII, caching behavior (5min-1h), and return content (pack, tool, count). 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?

Efficient single paragraph with clear front-loading of purpose, followed by structured use cases and technical details. No superfluous content.

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

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

Despite no output schema, description specifies return fields (top tools, packs, volume) and explains data source, caching, and parameter. Complete for a simple one-parameter 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 the single parameter fully; description adds minimal extra value with window selection guidance. Baseline 3 due to 100% coverage, raised to 4 for the additional context.

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 'Returns the top tools, top packs, and total call volume' with a specific verb and resource, and differentiates from siblings by focusing on trending usage of Pipeworx 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?

Lists three explicit use cases and explains window trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), but does not explicitly exclude 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 read-only, open-world, idempotent, non-destructive behavior. The description adds deep context: explains internal checks (Jaccard similarity >0.30, partition filter for placeholders, fill check against CLOB depth) and warns when not to trade. No contradiction with annotations.

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

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

Description is lengthy but well-structured with clear paragraphs per mode. Some technical details could be tightened, but the complexity of the tool justifies the length. No wasted sentences, though some repetition of 'partition_check' concept.

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 explains the response structure (opportunities[], partition_check) and the fill check logic. It covers modes, edge cases (low similarity, placeholders), and references a sibling tool for custom sizing. Missing full details of every returned field, but sufficient for a complex arbitrage 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 both parameters with descriptions. The description adds substantial meaning beyond schema: explains format of event slug, what topic expects, how each mode works, and includes concrete examples. Despite 100% schema coverage, the added detail significantly aids agent 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?

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes multiple modes (no args, event, topic) and provides examples, making the purpose specific and distinct from sibling tools like polymarket_edges or 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?

Explicitly tells when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Provides recommendations and even points to alternative tool ('For custom sizing use polymarket_fill_risk'). Clear when-not 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 extensively explains internal logic, including the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation with slippage, Kelly fraction caps, and caching. It goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing the response structure, diagnostics, and constraints like 'placeholder-slug filter'. 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 long but every sentence serves a purpose. It is front-loaded with the core purpose, then organized into logical segments (model families, knobs, response structure). The use of bullet points and clear sectioning makes it scannable. No filler or redundancy.

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

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

Given the tool's complexity (9 parameters, no output schema, nested objects), the description is remarkably complete. It explains the output structure (by_segment, fed_candidates, diagnostics), the meaning of each field like edge_pp_net, and how knobs affect results. The absence of an output schema is fully compensated by the description.

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 9 parameters are documented in the input schema with descriptions (100% coverage), so the baseline is high. The description adds meaningful context beyond the schema, such as clarifying 'min_liquidity' as a tradeable-edge filter and explaining why 'min_partition_leg_kelly' is needed. This extra context justifies a score 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 states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb ('Scan') and resource ('Polymarket markets'). It explicitly targets the use case 'what should I bet on today', distinguishing it from generic market data tools. The purpose is specific and actionable.

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

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

The description provides clear context for when to use the tool ('what should I bet on today') and explains that Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage. The guidance is strong but lacks explicit exclusions.

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

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

The description adds significant detail beyond annotations: explains data source (daily snapshots), output structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, daily closes, not intraday), and computation of decay metrics. 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?

Description is densely informative but well-structured, front-loading purpose. Some verbosity in examples ('the median lifespan is your competition clock'), but overall efficient for the 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 no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and computation details. Covers limitations and edge cases (gaps in data). Fully meets the needs for a complex analytical 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?

Parameters are fully described in schema (100% coverage). Description adds defaults and constraints (e.g., 'default 14, max 30' for days, 'default 1wk' for window), providing additional clarity beyond schema alone.

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

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

The description clearly states 'Edge persistence and decay telemetry' answering a specific question about edge duration and decay. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description implies when to use this tool by contrasting fresh vs. old edges, but it does not explicitly exclude alternatives or state when not to use it. Provides clear context without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds detailed return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains the check behavior for both modes, and highlights forced directional risk. 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 well-structured with clear sections for modes and return fields, but it is somewhat verbose. However, the complexity of the tool justifies the length, and every sentence serves a purpose.

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

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

Given the 4 parameters, no output schema, and no nested objects, the description thoroughly covers input semantics, return fields, and usage warnings for both modes. The verdict field gives error indication, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: clarifies size_usd semantics for single-market vs basket, explains side defaults, and describes how the tool walks the ladder. This adds actionable context for the agent.

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 ('realizable-vs-theoretical edge check against live CLOB order-book depth'). It clearly distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by directing when to use this tool.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns against partial fills converting an arb into unhedged direction and mentions that theoretical overround on thin books is not capturable, providing clear when-to-use and 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 cover read-only/idempotent safety, but the description adds substantial behavioral context: fee modeling limitations, compatibility warning semantics, token-overlap matching, unclassified-leg exclusion, and skipped-comparison counters. It also explicitly warns that returned pairs may still be incompatible, which goes beyond the structured annotations.

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

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

The description is long and dense, but it is organized with clear labeled sections covering modes, response, safety fields, codes, and skipped comparisons. There is some repetition of the temporal_alignment_unknown caveat, and the length could strain attention, but most sentences add necessary operational detail.

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

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

Even without an output schema, the description comprehensively documents return values, spread direction, compatibility codes, fees, skipped legs, and alignment semantics. It leaves an agent with enough information to call the tool correctly and interpret ambiguous results, which is exceptional for a cross-venue comparison 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 per-parameter descriptions, and the description enriches this by explaining how topic vs explicit parameters interact (explicit overrides the topic-mapped side) and that both modes run the identical matcher. It also explains what each parameter selects, making the call semantics much clearer than the schema alone.

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

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

The opening sentence states a specific purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes further to distinguish its two modes (topic shortcuts vs explicit pairings) and clearly differentiates from sibling spread/arbitrage tools by emphasizing same-question cross-venue comparison.

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

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

It provides clear direction on when to use pre-mapped topic shortcuts versus explicit kalshi_event_ticker/polymarket_event_slug, and it cautions that pre-mapped topics are not automatically tradeable. It does not name sibling alternatives for exclusion, but for a single-tool call the when-to-use guidance is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds beyond by noting 'capped' poem text and 'Keyless' (no authentication needed), which provides useful behavioral context 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?

The description is extremely concise, using two short sentences that immediately convey purpose and key traits. No filler or redundant 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?

Given the tool's simplicity (1 parameter, rich annotations, no output schema), the description adequately covers the return type (full poem text capped) and key trait (keyless). Could mention return structure or typical usage examples, but sufficient for its complexity.

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

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

Schema description coverage is 100% (count parameter fully described). The description does not add additional meaning about the parameter beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action (Fetch), the resource (random public-domain poems from PoetryDB), and the return (full poem text, capped). It distinguishes from siblings like search_poems or get_poem_lines by specifying randomness and public-domain.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. Siblings like search_poems and get_poem_lines exist, but no comparisons or exclusions are given. 'Keyless' hints at no auth, but lacks explicit context.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds behavioral detail: scoping per identifier, listing capability, and pairing with remember/forget, which is useful 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?

Two sentences, no wasted words. Front-loaded with the primary action. 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?

For a simple retrieval tool with one optional parameter and no output schema, the description is fully complete: what, when, scoping, pairing, and behavior of omitting key.

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 the key parameter fully. Description adds extra meaning: omitting key lists all, explains purpose of keys, and ties to memory system. Baseline 3, extra context justifies 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?

Clearly states it retrieves a saved value or lists all keys. Verb (retrieve/list) and resource (memory key) are specific. Distinguishes from sibling tools 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?

Explicitly says when to use: to look up context stored earlier without re-deriving. Implies when not to use by mentioning paired tools. Provides scoping context.

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

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

The description discloses that setting mark_read:true modifies state (flags events as read), which contradicts the annotation readOnlyHint=true (declaring no side effects). This contradiction is a serious inconsistency, warranting a score of 1.

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 well-structured sentences, each serving a purpose: primary action, parameter guidance, and alternative access. No wasted words.

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

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

For a read tool with 5 optional parameters and no output schema, the description covers return content, filtering, side effects, polling suitability, and alternative access. It is fully 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?

The input schema covers all 5 parameters with descriptions. The description adds behavioral context for mark_read (affecting subsequent calls) and clarifies filtering semantics, going slightly 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 'Pull fired events from your subscription feed' with specific details on return fields (source, citation_uri, payload) and filtering options (type, since). This distinguishes it from sibling tools that handle other tasks.

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 (polling) and provides an alternative ('GET registry.pipeworx.io/alerts.json for scripts and dashboards'). It also clarifies how to use parameters (e.g., mark_read for progressive fetching). However, it does not explicitly exclude specific scenarios or compare with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description goes beyond by detailing the tool fans out to SEC EDGAR, GDELT/GNews (with fallback logic), and USPTO (soft-fail). It also outlines return structure (grouped changes, total count, citation URIs). No contradiction with annotations.

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

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

The description is dense and front-loaded with query examples, then efficiently covers sources, fallbacks, and return format. A few sentences could be slightly more terse, but overall 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 complexity of multiple sources (SEC, GDELT/GNews, USPTO) and lack of output schema, the description is remarkably complete. It covers input formats, source behavior, fallback logic, soft-fail for patents, and return structure (changes grouped by source, total count, citation URIs).

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. The description adds value by explaining the 'since' parameter accepts relative shorthand with examples (e.g., '30d', '3m'), noting that 'type' is constrained to 'company', and clarifying that 'value' can be a ticker or CIK. Provides guidance on typical usage ('30d' or '1m' for monitoring).

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 provides a change feed for a company (SEC filings, news, patents) in a time window. It distinguishes from sibling 'entity_profile' by specifying that this tool is for dynamic updates, not static profiles.

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 gives example queries ('What's new with X'), explains input formats (ISO date or relative shorthand), and advises when to use the sibling 'entity_profile' instead. Also describes fallback behavior between news sources.

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 idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: storage scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with purpose. It is clear and efficient, though slightly longer than strictly necessary. No redundant 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?

Given two simple parameters, no output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, usage, scope, persistence, and pairing with siblings. No notable 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 description coverage is 100%, so baseline is 3. The description gives examples of keys and values but does not add significant meaning beyond the schema's descriptions. 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 uses the specific verb 'save' and resource 'data', and explicitly distinguishes from siblings 'recall' and 'forget' by stating to pair with them. It also specifies the scope (across conversations or sessions), which differentiates it clearly.

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 discover something worth carrying forward... so you don't have to look it up again.' It provides concrete examples (resolved ticker, target address, etc.) and mentions complementary tools (recall/forget), giving clear usage context.

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

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

Despite already having readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, the description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting instead of silent omission, ambiguous bond matches returning `figi_candidates`, and internal cascading across multiple lookup endpoints. These behaviors are not inferable from annotations alone.

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

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

The description is long but highly structured and dense with information: examples up front, then supported types, then caveats and degradation behavior. Every sentence adds operational value, and the semicolon-separated lists keep related facts together 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?

For a two-parameter tool with no output schema, the description covers inputs, return values, ambiguity handling, failure modes, and integration with downstream use ('other tools require as input'). An agent has enough context to decide when and how to call it correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by clarifying accepted input forms (ticker, CIK, ISIN, name), giving concrete examples like 'CH0038863350' and 'ozempic', and warning against including full noun phrases for bond issues. This materially improves correct invocation.

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

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

The description states a very specific verb-resource pair: resolve a user-spoken NAME to the canonical/official identifiers other tools require. It supports this with concrete user utterances and enumerates exactly which identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), making the purpose unmistakable and distinct from siblings like entity_profile or validate_claim.

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

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

It gives an explicit directive, 'Use FIRST whenever you have a name but need an ID,' and includes numerous trigger examples. It does not explicitly name sibling tools or state when NOT to use it, but the 'Use FIRST' instruction and the detailed scenarios provide strong situational guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific metrics (score, confidence, signal density). It also clarifies the subject/competitor distinction.

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 remarkably concise at three sentences, with the core purpose front-loaded. Every sentence adds value: purpose, mechanism, and use case. No redundant or extraneous content.

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

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

Given no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density). It explains the process and context. It could mention potential external API calls or timeouts, but overall it's sufficient for a comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema's descriptions of parameters. It reinforces the role of 'entities' but doesn't provide additional guidance on 'models', '_apiKey', or 'context'.

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 action: 'Compare AI visibility across multiple entities side-by-side' using a specific verb and resource. It distinguishes itself from the sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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 context: 'Useful for competitive AI-marketing audits' with a concrete example. While it doesn't state when not to use or directly name alternatives, the purpose strongly implies when this tool is appropriate over single-entity checks.

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 readOnlyHint, etc., but the description adds behavioral traits beyond: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists if it times out. This gives useful behavioral expectations beyond what annotations convey.

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

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

The description is dense but front-loaded with the main purpose and then details. Every sentence adds value, though it could be slightly more concise. It wastes no words and is well-structured.

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

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

There is no output schema, but the description explicitly lists the return fields: summary block (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers partial failure behavior. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the description adds minimal meaning beyond the schema. Both parameters (package, version) are fully described in the schema; the description only reiterates that scoped packages are accepted and version defaults to latest. Thus 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 is a composite check for adding npm packages, fanning out to deps.dev and bundlephobia for license, advisories, and bundle size. It specifies the exact resource (npm package) and scope. Among siblings (poems, polymarket, etc.), it is distinct and unambiguous.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This provides clear guidance on when to use and when to use alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it returns full text, author, line count, and notes the limitation 'searches titles only, not poem body text.' 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?

Two sentences, immediately stating action and scope. No filler. Front-loaded with the verb 'Search' and resource 'PoetryDB'. 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 no output schema, description partially compensates by listing return fields. However, it omits default limit, pagination, and how the author parameter combines with title. These gaps reduce completeness for a search 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 all 3 parameters with descriptions, so baseline is 3. The description provides a usage example ('The Road Not Taken') but does not add new parameter info beyond the schema. The interplay between title and author is not explained.

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 searches poems by title or partial title and returns specific fields. It distinguishes from sibling tools like get_poem_lines and list_authors, but does not explicitly mention the author parameter, which could cause confusion.

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

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

The description implies usage when searching by title but does not explicitly state when to prefer this tool over alternatives like get_poem_lines or when not to use it (e.g., for full-text search). No exclusions are given.

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, openWorldHint, and destructiveHint as false. The description adds critical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and that passages carry offsets for verification.

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

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

The description is concise, consisting of three sentences: the first states the core function, the second explains when to use it and its benefits, and the third provides technical details. Every sentence is essential and well-organized.

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 fully explains the return format (top-N passages with character offsets and similarity scores), the truncation behavior, and the pairing with ask_pipeworx_grounded. This covers all needed context for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing example queries for the query parameter (e.g., 'supply-chain risk') and clarifying that text is 'the document text to search inside', which matches schema but adds context. This slight additional guidance warrants 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 performs semantic search inside a fetched record, specifying the verb 'search', the resource 'inside a record', and the scope 'top-N passages with character offsets and similarity scores'. It distinguishes itself from the sibling ask_pipeworx_grounded by explaining how they pair.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context and returns only relevant passages. It also mentions pairing with ask_pipeworx_grounded, providing a clear alternative for grounded answers.

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 non-read, open-world, idempotent, non-destructive. Description adds OAuth requirement, return value, delivery channel behaviors (SMS cap, webhook auto-disable, HMAC signing), all beyond annotations. 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?

Dense single paragraph with good front-loading of purpose and type list. Could benefit from bullet points or clearer structure, but no wasted sentences.

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?

Covers purpose, parameters, delivery channels, constraints, prerequisites, and return value. No output schema needed since description mentions 'returns the new subscription id'.

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% (baseline 3). Description adds extensive details: enum explanations for 'type', type-specific examples for 'params', and full delivery channel semantics including constraints and verification steps.

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

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

Clearly states the verb 'create' and resource 'subscription' to a live-data event stream, returns new subscription id. Distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Specifies when to use (creating subscriptions), lists prerequisites (OAuth account, phone verification for SMS), and details supported types with examples. Lacks explicit exclusions or comparisons with alternatives like 'recent_alerts'.

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 the tool is read-only, idempotent, and non-destructive. The description adds that it returns category-bucketed example questions with exact tool argument shapes, and explains the behavior difference between no arguments and a topic filter. No contradictions with annotations.

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

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

The description is a single paragraph but efficiently conveys aliases, purpose, output, and usage. Every sentence adds value, though bullet points could improve scannability. Still, it is well-structured and not verbose.

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 only one optional parameter and no output schema, the description is remarkably complete. It covers when to use, what it returns, how to customize, and how it fits into the overall onboarding flow.

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 one optional parameter. The description provides a full list of valid topic values (e.g., finance, pharma, economics) and explains that omitting it yields a cross-category spread, significantly enriching the schema's 'string' type.

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 specifies the tool is for onboarding new users, providing example questions categorized by topic. It distinguishes itself from siblings by positioning as the first tool to use when unfamiliar with Pipeworx's capabilities.

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 to use this tool FIRST when the user doesn't know what Pipeworx can do, and explains how to call with no arguments vs. a specific topic. Could mention alternatives like discover_tools more directly, but the guidance is clear and context-rich.

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 adds key context beyond annotations: row is deactivated (not deleted), historical events remain, and ownership is enforced. Aligns with annotations.

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

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

Three short, focused sentences. Front-loaded with action and target. 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?

Simple 1-param tool with no output schema; description fully covers purpose, effect, ownership, and relation to sibling tools (recent_alerts).

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 the single parameter with description (100% coverage). Description adds no extra detail beyond referencing the id.

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 uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing 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?

States ownership enforcement and that only own subscriptions can be canceled, implicitly guiding usage. Could be more explicit about when not to use.

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?

Rich behavioral detail beyond annotations: the two-path execution model, the distinction between could_not_verify and unsupported, the presence of verification_error{stage,detail}, and the return of verbatim evidence with pipeworx:// citations. It also clarifies that could_not_verify is not evidence for/against, which is critical for correct agent usage. No contradiction with readOnlyHint=true.

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

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

Dense but efficient: trigger phrases, use case, dual-path logic, return value summary, critical caller warning, and efficiency justification. Every sentence adds value; 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?

Even without an output schema, the description explains required return fields (verdict, actual value, citation, reasoning), distinguishes error vs. unsupported states, and specifies the two processing paths. This is a complete mental model for an agent to decide and invoke correctly.

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

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

Schema already covers 100% of parameters with detailed descriptions and examples. The description adds the context of 'exact percent-delta math' and mentions tolerance override, but these are also captured in the schema. Description does not significantly enhance parameter understanding beyond the schema.

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

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

The description opens with explicit trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It immediately distinguishes itself from siblings by stating it replaces 4–6 sequential calls and by detailing the specialized SEC EDGAR fast path for financial claims.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides clear routing guidance (financial vs. other claims) and warns about misinterpreting could_not_verify. It doesn't name alternative tools for non-claim tasks, but given the sibling list includes other research tools, the usage context is clear enough.

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