Dockerhub

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that the tool makes external API calls to LLMs, requires a personal API key for Anthropic, and returns detailed per-model results. No contradictions.

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

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

Description is concise (4 sentences), front-loaded with main purpose, and every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains return structure per-model and combined view. Covers parameter usage and use cases adequately for a 4-param tool with simple semantics.

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. Description adds minor usage context (default model, why context is useful) but does not significantly extend schema documentation.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100, using specific verbs and resources. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general brand visibility rather than competitive 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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to use default model vs. Anthropic with API key. Does not list alternatives or when not to use, but context is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals routing behavior, argument filling, citation URIs, cross-tier availability, and speed ('one fast call'). It also discloses the boundary of not being the best choice for hallucination-resistant single answers or broad multi-part fan-out, adding significant behavioral context.

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

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

Although lengthy, the description is well-structured: it opens with the most critical directive, then explains mechanics, gives examples, and closes with escalation paths. Every sentence conveys useful guidance, though a couple of the example-heavy sections could be tightened without losing 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?

The description fully contextualizes the tool for a general-purpose question-answering agent: it lists supported domains, gives sample queries, explains the routing/citation mechanism, and positions itself against alternatives. It does not discuss failure modes or non-text outputs, but given the simple single-question interface and rich annotations, this is a minor gap.

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

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

Schema coverage is 100% and the six parameters are all documented aliases for 'question', with the main parameter fully described. The description itself does not add parameter-level detail beyond schema, which is acceptable given high coverage; it maintains the baseline rather than elevating it.

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

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

The description clearly states the verb ('routes the question'), the resource (5,529 tools across 1,455 verified sources), and the output shape ('structured answer with stable pipeworx:// citation URIs'). It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance ('START HERE', 'PREFER OVER WEB SEARCH') and when-not-to-use guidance ('Step up only when needed' for grounded answers or broad multi-part questions via deep_research). It also provides a list of example queries, which strongly anchors the expected usage.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool is experimental, may have live routing changes, and currently behaves identically to ask_pipeworx. It explicitly states it does not fall back to another tool and is a fully functional router, adding crucial behavioral context.

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

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

The description is three sentences, each earning its place: the first defines the tool, the second provides current status, the third gives usage and comparison context. It is front-loaded with 'Beta version of ask_pipeworx' and contains no fluff or redundancy.

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

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

Given the tool's complexity as a beta router with no output schema, the description fully covers purpose, current operational state, usage, and relationship to the stable router. It even notes the response shape matches ask_pipeworx, which is sufficient for agents to know what to expect.

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

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

The input schema already covers all six parameters (aliases for 'question') with 100% description coverage. The description only says 'same arguments' without adding additional meaning beyond what the schema provides, so the baseline of 3 is appropriate despite the excellent schema coverage.

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

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

The description clearly states it is a beta version of ask_pipeworx, explicitly naming the tool it mirrors and its role as a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by focusing on candidate routing improvements, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, so it matches ask_pipeworx exactly) and implies it's for experimental evaluation, which helps an agent decide between this and the stable sibling.

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?

Goes far beyond annotations by documenting the exact return shape on success and failure, including refusal_reason enum values. It discloses that the tool fetches from a large source corpus and uses 'ONLY what the tool result contains' (no guessing), and that it costs an extra LLM call. These are behavioral traits not visible in annotations or schema. No contradictions found.

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

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

The description is compact yet information-dense: purpose, routing mechanism, return structure, usage scenarios, and cost tradeoff are each given one well-organized clause or sentence. The use of colons, lists, and a clear alternative keeps it structured without wasted words.

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

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

With no output schema, the description fully specifies the success and failure return formats, including refusal reasons. It covers the tool's scope, limitations (no invention), and cost implications. For a tool of this complexity (routing, extraction, refusal handling), this is a complete and self-sufficient 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?

Schema coverage is 100% and all six parameters are documented as aliases for 'question'. The description adds no new parameter-specific semantics beyond saying 'fills arguments' generically. The schema already explains the aliases and main parameter, so the baseline 3 applies.

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

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

Description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with 'ask_pipeworx' by stating the EXTRACTS-the-answer behavior with verbatim evidence. It clearly names the verb (extract), resource (Pipeworx answer), and unique value (grounded, refusal-aware) that differentiates it from the sibling 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?

States explicitly when to use: 'Use whenever an answer will be quoted, cited, or acted on... must not invent facts' and gives examples (financial verdicts, legal claims, medical lookups). It also provides a direct alternative: 'prefer ask_pipeworx for casual lookups' and the cost tradeoff ('Costs one extra LLM call'). This gives 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?

The description extensively details fan-out logic, response shapes, resolver contracts, news fields, safety checks, and resolution-rule risk, far exceeding the readOnlyHint and idempotentHint annotations. 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 very long and dense, which is justified by the tool's complexity, but it could be more concise. Still, it is well-structured with headings and front-loaded 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 absence of an output schema, the description thoroughly covers return values, edge cases (low-confidence, closed markets), and safety mechanisms, making it 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 coverage is 100%, yet the description adds significant value by explaining the depth parameter (quick vs thorough), market input variations, and include_raw behavior, providing context beyond parameter descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifies input formats (slug, URL, question text), and distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by listing explicit use cases.

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 provides use cases ('should I bet on X', 'what does the data say about Y') and details when the tool short-circuits (low-confidence, closed markets, wide spreads), giving clear contextual 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 read-only, idempotent, and nondestructive behavior. The description adds crucial behavioral context: it pulls from SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, returns sorted results, and provides 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 a single paragraph but well-organized with trigger phrases upfront. It is dense but not overly verbose. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given no output schema, the description explains return data (paired data + citation URIs) and behavior (sorted by primary metric). It covers both entity types, data sources, and edge cases (off-calendar fiscal years). 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 coverage is 100% with descriptions for both parameters. The description enriches semantics by explaining the format (tickers/CIKs for company, drug names), constraints (2–5 items), and how the primary metric is used for sorting. Adds value beyond schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It includes natural language triggers ('compare X and Y', 'X vs Y') and explains the data sources for each type. It distinguishes itself from sequential single-entity lookups (e.g., entity_profile).

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

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

Explicitly states when to use ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides clear context for each entity type (company vs drug). It explains the data pulled and sorting behavior, helping the agent decide when to invoke.

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 (read-only, idempotent, open-world, non-destructive), the description discloses account tiers, latency expectations (15-90s), the exact return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), semantic excerpting, and source limitations (breaking news returns empty gaps). No statement contradicts the annotations; the openWorldHint is consistent with external structured data.

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 critical account requirement and uses clear topic breaks (purpose, comparisons, depth semantics, output structure, limitations). Some sentences repeat schema depth details, but the overall density of new, decision-relevant information is high.

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 define the return contract. It fully specifies the findings packet, gap/contradiction flags, hop fields, citation URI resolvability, excerpting behavior, and latency. It also covers edge cases like breaking-news topics, making the description complete for an agent to invoke and interpret results accurately.

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

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

The input schema already provides descriptive text for both question and depth, covering 100% of parameters. The tool description adds the crucial paid-plan constraint for depth:'thorough' and reinforces that broad natural-language questions are appropriate, which is modest added value beyond the schema.

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

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

The description states the tool's purpose with a specific verb ('research') and resource ('1455 STRUCTURED data sources'), and clarifies it is NOT open-web search. It also distinguishes from siblings like ask_pipeworx by positioning deep_research as the multi-facet, parallel-routing tool for broad/multi-part questions.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: fall back to ask_pipeworx if not signed in, for single lookups, and for breaking/colloquial news; use deep_research for broad/multi-part questions over structured data. It also explains depth selection with trade-offs (quick/standard/thorough) and the paid requirement for thorough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's behavioral add-ons are limited. It adds that the tool returns top-N relevant tools with full schemas ready to call, which is useful but not essential beyond annotations.

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

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

The description is fairly long but well-structured and front-loaded with purpose. Every sentence adds value, though some repetition of aliases could be trimmed. Still efficient for a tool with many siblings.

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

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

For a discovery tool, the description covers what it returns, when to use it, and that schemas are included. Given the large sibling set, this is complete enough to guide an agent 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?

Input schema has 100% coverage, so the description adds minimal value. It mentions aliases but these are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates many domains, making the purpose unmistakable. It also distinguishes from siblings by advising 'Call this FIRST when you have many tools'.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools and want to see the option set.' Lacks explicit when-not-to-use, but provides strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: details the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields (cik, company_name, recent_filings with URIs, fundamentals, patents with soft-fail note, news, LEI), and the patent soft-fail behavior. This goes well beyond annotations.

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

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

The description is front-loaded with examples and a clear one-line summary, followed by detailed but well-structured information. Every sentence provides necessary context (sources, return fields, caveats). No redundant or irrelevant content.

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

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

Given the tool has 2 parameters, 100% schema coverage, no output schema, and moderate complexity (multi-source data aggregation), the description is comprehensive. It explains the full output structure, including specific fields like recent_filings with URIs, fundamentals sorting, news sources, and the patent API sunset. It also covers input constraints and fallback behavior.

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

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

Schema coverage is 100%: both 'type' and 'value' have descriptions. The description adds value by clarifying that 'value' accepts ticker or zero-padded CIK and that names are not supported, reinforcing the schema. While schema already covers basics, the description provides concrete examples ('AAPL', '0000320193') that aid understanding.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') and clearly states the tool's purpose: generating a full cross-source profile of a US public company in one parallel call. It distinguishes itself from chaining single-pack lookups and is specific about the verb ('profile') and resource ('US public company').

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies input constraints: 'Pass ticker ... or zero-padded CIK ... names not supported (use resolve_entity first if you only have a name).' This gives 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 indicate destructiveHint=true and idempotentHint=true. The description uses 'Delete' confirming destruction and adds context about clearing sensitive data, which supplements the annotations 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?

Two concise sentences: first defines the action, second provides usage guidance. No filler, every sentence is value-adding.

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

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

For a simple tool with one parameter, annotations, and no output schema, the description covers purpose, usage, and behavioral notes adequately. Pairing with siblings enhances completeness.

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 'key' with description. The description mentions 'by key' but adds no new semantic detail beyond the schema. Baseline score of 3 applies due to 100% schema coverage.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb+resource. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall', showing awareness of related 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?

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Lacks explicit when-not-to-use or alternatives beyond the paired tools, 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 indicate readOnly and idempotent. The description adds that it fetches the page, extracts title/description/key links, and emits markdown. It does not mention error handling or rate limits, but overall behavior is transparent.

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

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

Three sentences plus a short use case list. No fluff, front-loaded with the main 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?

The description covers purpose, output format, and use cases adequately for a simple tool with 2 parameters and no output schema. Missing error conditions or limitations, but overall sufficient.

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 does not add specific parameter-level detail beyond the schema; it only mentions the extraction process. No additional semantics for 'url' or 'max_links'.

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 generates an llms.txt file for a URL, using specific verbs like 'Generate', 'Fetches', 'extracts', 'emits'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by explicitly focusing on llms.txt file creation.

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

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

The description provides concrete use cases (client indexing, own project, competitor audit) but does not explicitly state when not to use this tool or mention alternatives. The context is clear but lacks 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, and destructiveHint, so the description's role is lighter. It adds value by enumerating the metadata fields returned (description, pull count, stars, etc.), which aids the agent in understanding the tool's output.

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 consists of two concise sentences with no redundant information. It front-loads the purpose and follows with a usage guideline, making it efficient and scannable.

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

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

Given the rich annotations (readOnlyHint, openWorldHint, etc.) and the presence of an output schema, the description covers the necessary context: what the tool does, what data it returns, and when to use it. No additional information is needed 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 clear descriptions for both parameters (name and namespace). The description does not add additional semantic meaning beyond the schema, so 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 retrieves detailed metadata for a Docker Hub repository, listing specific fields. It implicitly distinguishes from search_images by focusing on a single known repository, but does not explicitly differentiate from sibling tools like get_tags or get_tag_details.

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

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

The description explicitly advises using the tool before pulling an image to verify quality and currency. It does not mention when not to use it or explicitly compare to alternatives, but the usage 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral context by detailing the specific return data (per-platform info, multi-arch manifest digest, push date), which is beyond what annotations alone provide. 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?

A single, information-dense sentence listing return fields, followed by a bullet-like list of use cases. No wasted words; every part adds value. The most important info is front-loaded.

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

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

No output schema exists, but the description fully explains what the tool returns (platforms, digests, sizes, push date, manifest digest). With only 3 required parameters all documented, this description is complete for a read-only query 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 description coverage is 100%—each parameter (namespace, name, tag) is well-described in the schema itself. The description adds no new semantic detail about parameters but correctly contextualizes their use (e.g., 'specific image tag'). 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 uses a specific verb ('get full details') and identifies the resource ('specific image tag'), listing exact return fields (os/arch/variant, digests, sizes, push date, manifest digest). It distinguishes itself from siblings like get_tags and get_image with the 'PREFER for' clause.

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 use cases via 'PREFER for' (e.g., checking arm64 build, supported platforms, digest/size). It lacks explicit when-not-to-use or alternative tool names, but the 'PREFER' pattern strongly guides 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds behavioral details beyond annotations: tags are sorted by recency, and the return fields (tag name, digest, size, push date) are specified. This adds value 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?

Two sentences: first states what the tool does and its output, second gives usage guidance. No extraneous words. Front-loaded with the core purpose. Perfectly concise.

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

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

With an output schema present, the description does not need to detail return structure. It covers purpose, output fields, and usage context. Annotations handle behavioral traits. For a straightforward list tool, this is complete.

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

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

Schema coverage is 100%, with each parameter having a description. The description adds minimal extra meaning (e.g., 'Docker image' context and 'sorted by recency'), but the schema already documents the parameters adequately. 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 'List available tags for a Docker image sorted by recency. Returns tag name, digest, size, and push date.' This provides a specific verb (list), resource (tags), and the exact fields returned, making the tool's purpose unmistakable. While it does not explicitly differentiate from siblings like 'get_tag_details' or 'search_images', the specificity is sufficient.

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 includes 'Use to find and select specific versions to pull,' which gives clear context for when to use the tool. However, it does not mention when not to use it or explicitly name alternatives, so it's slightly short of a perfect score.

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 and safe behavior; the description adds return fields but no additional behavioral traits beyond that.

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

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

Two sentences with no waste, clearly front-loaded with purpose and return fields.

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 list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% for the single parameter, so the description does not need to add parameter info; 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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel,' giving clear context for when 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?

With all annotations false, the description carries the full burden and delivers. It discloses claim_token behavior for follow-up, rate-limiting to 5 per identifier per day, that filing is free and doesn't count against quota, and that the team reads digests daily. This is rich behavioral context.

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

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

The text is a single dense paragraph, but every sentence adds distinct information (purpose, scope, claim_token, rate limit, quota). It could be broken into bullets or trimmed slightly, yet remains efficient for the tool's complexity. Score 4 rather than 5 due to 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?

For a 4-param tool with no output schema, the description covers the return token, follow-up mechanics, scope exclusions, and rate limits. It fully compensates for the missing output schema and annotations, leaving no critical knowledge gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts, which clarifies message and context 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?

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' — a specific verb+resource — and immediately lists the feedback categories (bug/feature/data_gap/praise). This clearly distinguishes it from sibling research/query tools like ask_pipeworx or deep_research.

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

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

Explicitly states 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a negative case: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This gives clear when/when-not and an alternative action.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds data source (CF analytics-engine), no PII, caching window (5min-1h). Provides good extra 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?

Concise one-line hook, then bulleted use cases, then data source and caching details. Every sentence adds value; 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?

No output schema, but description explains return types (top tools, top packs, total call volume). Caching and source details sufficient. Could mention sorting but not required for a minimal viable 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?

Schema covers window parameter with enum and description (100%). Description adds value by explaining the trade-off between short and long windows ('surface what's hot' vs 'steady-state demand'), going beyond enum labels.

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?

Describes exactly what it does: returns trending tools, packs, and call volume over recent windows. Distinguishes from sibling 'discover_tools' by focusing on what other agents are calling, not static 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?

Lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case). No explicit when-not-to-use, but the guidance is clear and practical for a simple read-only 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 confirm read-only, open-world, idempotent, non-destructive. Description adds crucial behaviors: fill check, partition filter, semantic anchor, and trade execution caveat. 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?

Very detailed and thorough, but overly long. Contains many technical specifics that could be summarized. Could be more concise while retaining essential information.

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

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

Completely covers all aspects: input modes, parameter semantics, output format (opportunities array with fields), behavior with fill checks and filters. No missing information; no output schema needed.

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%, but description adds significant meaning: explains event slug format and topic as seed question, with examples. Goes far beyond schema with mode explanations and usage recommendations.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes three modes: no args (trending scan), event (specific slug), topic (cross-event scan). Specific verb and resource.

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 specific market, topic for cross-event scanning. Also advises against trading when fill check shows realizable_edge_pp ≤ 0.

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, so the description is not required to repeat those. It adds extensive behavioral detail: caching at KV level keyed on all knobs, response segmentation into by_segment with three model families, diagnostics for empty segments, and 24h-move warnings. 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 earns its place. It is front-loaded with purpose and usage, then systematically explains the three model families, response structure, and knobs. The structure mirrors the response layout (by_segment, diagnostics, knobs), aiding comprehension. Slight deduction for density; some section could be bulletized, but still efficient for the information load.

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 9 parameters, no output schema, and complex response structure, the description fully prepares an agent. It explains all response fields (by_segment, fed_candidates, diagnostics), edge_pp_net, Kelly fractions, liquidity/spread knobs, and caveats like Fed signal unreliability without paid data. Caching behavior and filter skips are documented. No gaps 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 coverage is 100%, but the description adds substantial context beyond the schema. For example, it explains the default slippage rationale (Polymarket zero fees but bid/ask eats 20-50bp), suggests values for max_spread_pp and min_liquidity with specific thresholds, and clarifies how min_partition_leg_kelly works differently from min_kelly for partition opportunities. This extra guidance helps the agent set parameters intelligently.

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 a clear verb-scope pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), action (scan and return), and unique signal (Pipeworx disagreement), distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides guidance on when to adjust knobs like slippage_pp, max_spread_pp, and min_liquidity, and explains tradeable-edge filters. Also clarifies that Fed bets are excluded but surfaced separately under fed_candidates.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes beyond by detailing that data comes from daily snapshots, history is bounded by a 60-day TTL, decay is computed from daily closes, and snapshots are written only on cache misses, adding significant context.

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

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

The description is verbose but well-structured, starting with a clear purpose and then detailing the response format. Every sentence adds value, though some parts could be more concise. It is front-loaded with the core question it answers.

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

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

With no output schema, the description must explain return values, which it does comprehensively: tracked opportunities with time series, trend, decay; expired opportunities with lifespan; snapshot dates; and limitations. This covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context such as default values and the meaning of 'window' as a snapshot family, but does not add substantial new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical persistence rather than current edges or arbitrage opportunities.

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 context: to differentiate fresh edges from old ones that may have a reason for being wide. It does not explicitly state when not to use or offer alternatives, but the contrast between fresh and old edges provides clear guidance for the tool's use case.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds detailed behavioral context: walks the ladder, returns fill metrics, and highlights forced_directional_risk. 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 well-structured with clear sections (SINGLE-MARKET, BASKET) and bold formatting for key terms. Front-loaded with core purpose. While dense, every sentence adds value; could be slightly more concise but still effective.

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 thoroughly explains all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), edge cases (thin_legs, forced_directional_risk), and practical constraints (max_clean_notional_usd). Complete for 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 coverage is 100% so baseline is 3. Description adds meaning beyond schema by explaining side behavior in both modes, clarifying size_usd interpretation (spend vs target proceeds vs settlement notional), and distinguishing event vs market. Slight improvement over baseline.

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

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

Description clearly states 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifies two modes (single-market and basket), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that partial basket fills convert an arb into an unhedged directional position, providing clear when-to-use and when-not-to 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 (readOnlyHint, openWorldHint, idempotentHint) are complemented by detailed behavioral disclosure. The description explains safety fields (compatibility_warning, temporal_alignment), edge cases (non-equivalent bet shapes), and counters for dropped comparisons. No contradiction with annotations.

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

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

The description is well-structured with sections (modes, response, safety fields) and front-loaded with core purpose. However, it is somewhat lengthy; some details like counters could be simplified. Still, every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly explains return values (leg-by-leg prices, matched spreads, safety fields) and error states (compatibility warnings, temporal alignment). Given the tool's complexity, this is comprehensive.

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

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

Schema coverage is 100%, but the description adds meaning beyond enumerated values by explaining modes (topic vs explicit) and the purpose of each parameter (e.g., 'Overrides the topic-mapped side'). This provides context not apparent from 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 description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('compute', 'auto-fetch') and distinguishes itself from siblings by focusing on cross-venue analysis rather than single-venue tools like polymarket_arbitrage.

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 two modes (topic shortcuts and explicit tickers) and provides guidance on when to use each. It warns that most pre-mapped topics return compatibility warnings, implying limited tradeability. However, it does not explicitly mention alternative tools for comparison.

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

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

Annotations declare readOnly and idempotent hints. Description adds context about scoping to user identifier and pairing with other tools, which supplements the annotations 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?

Description is three sentences with no wasted words. It front-loads the core action and efficiently covers behavior, usage, and scoping.

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 simple tool (one optional parameter, no output schema), the description fully covers what the tool does, when to use it, and its scope. 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 describes the parameter well. Description adds minimal extra context (examples of use) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when the argument is omitted. It uses specific verbs and resources, and distinguishes itself from siblings like forget and remember.

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

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

Explicitly says to use for looking up stored context without re-deriving. Describes listing behavior when key is omitted and pairs with remember/forget. Does not explicitly state when not to use it but implies 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral detail: returns most recent alerts, mark_read flags as read to affect next call, polling works fine. 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 front-loaded with purpose, then return fields, filtering, mark_read, polling, alternative. Each sentence adds essential information with no redundancy or fluff.

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

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

Complete for a simple tool with 5 parameters, no required, no output schema. Explains return fields, filtering, mark_read behavior, polling, and alternative access. Annotations cover safety, so description fills remaining 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 description adds meaning: gives example filter type ('sec_8k'), explains mark_read effect ('flag returned events read so the next call only shows newer ones'). Provides context beyond schema properties.

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,' specifying the resource (subscription feed alerts), action (pull/recent), and return fields (source, citation_uri, raw payload). It distinguishes from siblings like list_subscriptions, which lists subscriptions, not alerts.

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

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

Provides clear usage context: filter by type and since, mark_read behavior, polling suitability, and alternative access via URL for scripts. Lacks explicit when-not-to-use compared to other tools, but offers enough guidance for correct invocation.

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

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

Discloses multi-source fan-out, fallback from GDELT to GNews, USPTO soft-fail, output structure (changes grouped by source, total_changes, citation URIs). Complements annotations with behavioral context.

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

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

Description is thorough but verbose; includes extensive examples and fallback details. Front-loaded with user query examples, but could be more concise by moving some details to parameter descriptions or output schema.

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

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

Given no output schema, the description adequately covers return structure and source behavior. Parameter schema coverage is 100%, so description does not need to compensate much. Complete for a multi-source aggregation 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?

Adds meaning beyond schema: explains 'since' accepts ISO or relative with examples, 'value' can be ticker or CIK, 'type' only company. Provides usage guidance for typical monitoring interval.

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+resource: 'change feed for a company'. Distinguishes from sibling 'entity_profile' by contrasting static vs. dynamic profile. Lists multiple sources and query 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?

Explicitly states when to use (e.g., 'What's new', 'latest on Y') and when not to (use entity_profile for static profile). Provides alternative tool name. Could be more detailed on 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?

Adds key behavioral details beyond annotations: key-value pair scoped by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. 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?

72 words, front-loaded with purpose, then usage, then details. Every sentence is necessary and informative.

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

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

Given simple 2-param tool with no output schema, description covers storage behavior, scope, lifetime, and pairing with sibling tools. Fully sufficient.

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

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

Schema coverage is 100%, but description adds value with concrete examples for key (e.g., 'subject_property') and clarifies value as any text. Does not repeat schema.

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

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

Description clearly states verb (save), resource (data), and context (conversations/sessions). It distinguishes from siblings recall and forget by naming them.

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

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

Explicitly says 'Use when you discover something worth carrying forward...' and instructs to pair with recall and forget, providing clear when-to-use guidance and alternatives.

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

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

Beyond the readOnly and idempotent annotations, the description discloses rich behavioral details: cascading through multiple internal endpoints, source-labelled identifiers, explicit `unresolved` reporting, and graceful degradation when GLEIF or OpenFIGI are unavailable. These details go far beyond what the annotations provide, giving agents accurate expectations about execution and output.

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

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

The description is moderately long but well-structured, with SUPPORTED TYPES and explicit notes on degradation. The initial query examples are helpful, though there is some redundancy between the opening purpose and the 'Use FIRST' instruction. Overall, every major section earns its place.

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

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

For a tool with two entity types and multiple identifier sources, the description is remarkably complete. It covers what identifiers are returned for each type, how sources are attributed, how unresolved identifiers are handled, and what happens on external service failure. With no output schema, this level of detail is essential and present.

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

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

The schema already covers both parameters thoroughly with descriptions and examples (e.g., ticker 'AAPL', CIK '0000320193', drug 'ozempic'). The tool description largely repeats this information without adding new semantic detail, so the baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with explicit query examples ('What's the ticker for…' / 'find the CIK for…'). It distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID,' making the purpose and scope unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete trigger examples and explains that it replaces 2-3 manual lookups, effectively communicating when this tool should be preferred over alternative lookup or research tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond that: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and 'Returns ranked list with score, confidence, signal density per entity.' 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 two sentences, front-loaded with the core purpose. Every sentence adds value without redundancy. It is efficiently 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?

The description explains what the tool does, how it works (using ai_visibility_check), and what it returns. For a tool with 4 parameters, no output schema, and no nested objects, this is sufficient. It could mention that the 'models' parameter applies to underlying probes, but overall it is complete.

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

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

Schema description coverage is 100%, but the description adds extra meaning: 'First entry treated as the 'subject' for narrative; rest are competitors.' It also explains that 'context' disambiguates common names and that 'models' and '_apiKey' interact. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb (compare), resource (AI visibility), and scope (multiple entities). The description distinguishes it from sibling tools like 'ai_visibility_check' by mentioning it probes each entity with that tool and returns a ranked 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?

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This gives clear context for when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the relationship to 'ai_visibility_check' is implied.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it fans out across deps.dev and bundlephobia, bundlephobia's first measurement can take 5-30s, and partial failures degrade gracefully with sources_failed listed. 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 every sentence adds value. It front-loads the core purpose and then details services, return structure, and failure modes. Could be slightly more concise but well-structured 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?

Despite no output schema, the description comprehensively describes the return block (summary fields, advisories, links, alternative versions) and handles edge cases like partial failures and timeouts. Complete 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?

Input schema has 100% coverage with descriptions for both parameters. Description adds that scoped packages (e.g. '@types/node') are accepted and version defaults to latest, which is helpful 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 it is a composite check for deciding whether to add an npm package, aggregating license, advisories, version history, and bundle size. It distinguishes from siblings by specifying NPM ecosystem only, contrasting with tools like scan_competitor_ai_presence 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusion guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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 as false, indicating a safe read operation. The description adds details about the return fields and source (Docker Hub), which is helpful but not essential beyond the annotations.

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

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

The description is two sentences, each serving a distinct purpose: stating the action and listing return values. It is front-loaded and contains no unnecessary words.

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

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

The description covers the main purpose and return fields. With an output schema available, it does not need to detail return values. It is complete enough for a straightforward search tool, though it omits ordering or pagination details.

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

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

Schema description coverage is 100%, with both 'query' and 'limit' parameters well-documented. The description mentions 'keyword' but does not add new information beyond the schema, so it meets the baseline of 3.

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

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

The description clearly specifies the verb 'Search', the resource 'Docker Hub for container images', and the return fields (repository name, description, pull count, star count, official status). It distinguishes itself from siblings like 'get_image' by being a general search 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 states 'Use when finding images for deployment', providing a clear use case. While it doesn't mention when not to use or specific alternatives, the context of sibling tools like 'get_image' implies more specific use cases.

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, and non-destructive behavior. The description adds critical behavioral details such as the 200K character limit with truncation flagging, the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, and that returned passages include offsets and scores. This fully discloses behavior 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?

Every sentence serves a purpose. The description is front-loaded with the primary action, followed by usage context, technical details, and pairing information. It is concise yet comprehensive with no wasted words.

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

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

Despite the lack of an output schema, the description sufficiently explains return values (passages with character offsets and similarity scores) and constraints (200K char limit, truncation flagging). It also provides integration context with a sibling tool, covering all necessary information for an AI agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the purpose of 'text' and 'query' but does not add significant new meaning beyond the schema. The examples for 'query' are slightly helpful but not transformative.

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

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

The description explicitly states that the tool performs 'Semantic search INSIDE a fetched record' and clearly distinguishes it from sibling tools by specifying the use case: when a record is too large to include in the prompt. It contrasts with 'ask_pipeworx_grounded' and other search tools, making its unique purpose 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?

The description provides explicit guidance on when to use the tool ('Use when the record is too big to cram into the prompt') and mentions pairing with 'ask_pipeworx_grounded'. It does not explicitly state when not to use it, but the context is sufficiently clear for an AI agent to make an informed 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?

Discloses that a new subscription id is returned, details supported types with examples, and explains delivery channels with constraints (email validation, SMS verification, 10/day cap, webhook signature). No mention of idempotency, though annotations indicate idempotentHint=true; no contradiction.

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

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

The description is dense but well-organized: purpose first, then auth requirement, then supported types with examples, then delivery channels. Every sentence adds value; could be more bulleted but is 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?

Covers auth, types, params, delivery options, and constraints. No output schema exists, so return value is described. Missing potential error conditions or rate limits beyond SMS, but for a complex tool it is thorough.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds concrete examples for each type's params and elaborates on delivery channels (e.g., webhook signing, SMS cap). This exceeds baseline 3 for high 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 begins with 'Create a proactive monitoring subscription to a live-data event stream,' which clearly indicates the tool's action (create) and resource (subscription). It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by specifying creation.

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

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

The description states the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions, providing a clear prerequisite. It does not explicitly mention alternatives or when not to use, but sibling names give 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. Description adds behavioral details: returns category-bucketed example questions with tool+argument shapes, no arguments for full spread, topic for focus.

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 information-dense and well-structured with categories and instructions. Every sentence provides value, though could be slightly tighter.

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

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

Given simple one-parameter tool with no output schema, the description fully covers behavior, input, output, and use case. 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 describes topic as optional string. Description adds meaning by listing example values ('finance', 'pharma', 'betting') and explaining that omission gives full spread.

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 is an onboarding entry point that returns category-bucketed example questions. It distinguishes from siblings by explicitly mentioning meta-tools and advising to use this first when new.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear when-to-use, but doesn't explicitly say 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds crucial behavioral context: ownership enforcement, deactivation instead of deletion, and that historical events remain available via recent_alerts. This fully discloses side effects.

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

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

Two sentences, front-loaded with the core action, every sentence provides unique value. 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 1-parameter tool with no output schema and good annotations, the description covers purpose, usage constraints, side effects, and links to related tool (recent_alerts). It is fully complete.

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

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

Schema coverage is 100% and already describes the 'id' parameter. The description adds no new param-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses 'Cancel a subscription by id', which is a specific verb+resource combination. It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by stating cancellation action.

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

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

It states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. While it doesn't explicitly list alternatives, the context is clear and sufficient for an agent to decide when to use this 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 declare read-only, idempotent, open-world, non-destructive; description adds critical behavior: the meaning of could_not_verify vs unsupported, warns that could_not_verify is not evidence and must not be shown as one, and mentions the exact percent-delta math. This goes beyond annotations and prevents misuse.

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 contributes: trigger phrases, usage rule, routing logic, return value, two important caveats, and efficiency claim. It's front-loaded with the purpose and has no redundancy.

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

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

The tool is complex (two paths, multiple verdicts, error states), and the description covers all essential behaviors: when to use, what it returns, the distinction between unsupported and could_not_verify, citation format. No output schema so this is necessary and sufficient.

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 and already describes claim and tolerance_pct with examples and ranges. The description doesn't add new parameter semantics; it only references the fast path's math. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources. It provides trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and distinguishes from sibling research tools by focusing on returning a verdict (confirmed/refuted/etc.).

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 guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others) and notes it replaces multiple sequential calls, giving clear context for when to choose this tool.

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