imgflip

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 adds context beyond these: the default free model, the BYO-key cost implication for Anthropic, and the return payload structure. It doesn't mention rate limits or non-determinism, but the annotations and description together are sufficient.

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: three substantive sentences covering function, configuration, and return value, plus a short use-case list. All sentences earn their place; there is no fluff or repetitive wording. The key information is front-loaded in the first sentence.

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 explicitly states the per-model return structure ({score, confidence, signals, raw_response}) and the combined view, making the tool's behavior clear. Parameter semantics, usage, and annotations together provide a complete picture for an agent to select and 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 coverage is 100% with each parameter described. The tool description adds extra semantics around `_apiKey` (cost implication, pass-through to Anthropic) and the default model for `models`, which aren't fully captured in the schema. This enhances the parameter understanding beyond the structured fields.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs... score visibility (0-100) per model'), making the tool's function unambiguous. It also lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that differentiate it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

Explicitly states when to use ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model versus the optional Anthropic key, guiding users on configuration. It does not name alternatives or exclusions, but the context is clear enough to distinguish from similar 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 mark it read-only, open-world, and idempotent. The description adds meaningful behavioral context: it routes across 5,344 tools, fills arguments automatically, returns citation URIs, works on every tier, and is a single fast call. No contradictions exist.

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 section serves a purpose and it is front-loaded with the most important 'prefer over web search' directive. The examples and alternative routing are valuable, though slightly verbose for a single tool.

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

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

Despite lacking an output schema, the description explains the return format (structured answer, stable pipeworx:// citation URIs), performance characteristics, coverage domains, and fallback tools. This is complete for the tool's complexity.

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

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

Schema covers 100% of parameters with clear alias descriptions. The description reinforces the intent with concrete question examples and domain guidance, but does not deeply extend the per-parameter semantics beyond the schema. Still, the examples help an agent formulate valid queries.

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 routes questions to a large set of verified data sources and returns structured answers with citations. It names specific sibling alternatives (ask_pipeworx_grounded, deep_research), distinguishing its role as the default general-purpose factual query 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?

Provides explicit guidance to prefer this over web search, lists trigger phrases and examples, and explains when to step up to grounded or deep_research. It also clarifies that breaking-news is covered, making usage boundaries very 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?

With annotations already marking the tool as read-only, idempotent, and non-destructive, the description adds useful behavioral context: it may route differently when a candidate improvement is under test, currently matches ask_pipeworx exactly, and is a complete working router. It stops short of explaining what routing improvements entail or any potential variability in responses, but the annotations cover safety.

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, focused paragraph that front-loads the critical 'beta version' identifier and then explains current behavior, usage, and status. It is slightly verbose with details like the exact retirement date and tool count, but each sentence adds relevant context. It earns a 4 rather than 5 due to minor 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?

Although there is no output schema, the description tells the agent the response shape is identical to ask_pipeworx, fully explains the experimental status, and clarifies that no candidate is currently active. For a tool this complex, it conveys the essential contextual information needed to invoke it correctly, though it could be more explicit about the expected output format.

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 fully documents all six parameters, each alias clearly marked as an alias for 'question', with 100% coverage. The description adds no direct parameter details beyond stating 'same arguments' as ask_pipeworx, which is redundant given the schema. Therefore the baseline of 3 applies.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with a specific scope: a universal router using the same 5,344 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting the experimental routing improvements, giving an unambiguous purpose.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This directly tells the agent when to choose this tool over its sibling 'ask_pipeworx' and clarifies that it is a fully functional alternative, not a fallback stub.

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 already signaling safe read-only behavior, the description discloses the internal mechanism ('picks the right tool... fetches the data... EXTRACTS the answer using ONLY what the tool result contains'), the exact return shape with refusal reasons, and the cost of one extra LLM call. This adds substantial behavioral context that annotations do not cover.

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, front-loading purpose and then layering usage criteria, return contract, and cost trade-off in just three sentences. Every clause adds value with no filler or repetition of schema 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?

For a tool with no output schema and significant behavioral complexity (refusals, evidence, cost), the description covers the full success and failure contract, the use cases, and the relationship to its sibling. It is fully self-contained for an agent to decide when and how to invoke it.

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

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

With 100% schema description coverage and all parameters being aliases for the same question field, the schema already fully documents semantics. The description does not add parameter-specific detail beyond noting the question is in natural language, which is already in the schema, so baseline 3 applies.

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

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

The opening phrase 'Hallucination-resistant answer mode for high-stakes reads' clearly defines the tool's function, and 'Same routing as ask_pipeworx' explicitly distinguishes it from its sibling while noting its unique extraction behavior. It specifies the resource and the core value proposition (grounded answers with evidence).

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?

'Use whenever an answer will be quoted, cited, or acted on' gives explicit adoption criteria, and 'prefer ask_pipeworx for casual lookups' names the alternative and the trade-off (extra LLM call). This is exemplary when-to-use vs when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds extensive behavioral context: resolver contract with confidence levels, parent_event extraction, news fallback details, safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquid spread warnings, and cancellation-rule risk. This far exceeds the annotation baseline and informs the agent of edge cases and blocking behaviors.

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?

Despite being long, the description is exceptionally well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and concrete examples. Every sentence contributes useful operational guidance, and the front-loaded purpose makes it easy to scan. There is minimal 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?

With no output schema, the description carries the full burden of explaining return values. It details result.market, result.analysis, result.evidence, match confidence fields, parent_event, news fields with fallback flags, status codes for low-confidence and closed markets, and cancellation-risk parsing. This is a completely self-contained contract for the agent to trust.

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 all three parameters, and the description repeats the same input format details already in the schema (market slug/URL/question text). It does not add new semantic meaning for the depth or include_raw parameters beyond what the schema provides, 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?

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies actionable verbs (resolve, classify, fan out, return), the resource (Polymarket bet), and even input formats. This uniquely distinguishes it from sibling tools like polymarket_edges or ask_pipeworx by focusing on evidence gathering and 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 gives explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains accepted input forms (slug, URL, question text). However, it does not explicitly mention when not to use the tool or directly name alternative tools, so it stops short of a 5.

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

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

Despite readOnlyHint=true and idempotentHint=true annotations, the description adds substantial behavioral detail: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). 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 dense but every segment serves a purpose: trigger examples, explicit preference statement, per-type data details, and result behavior. It's longer than average but packed with high-value information, so it earns its length.

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

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

With no output schema, the description explicitly covers return values (paired data + citation URIs), sorting behavior, and data sources. For a two-parameter tool with this complexity, the description is comprehensive and leaves no major 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?

Even though the schema already describes both parameters, the description enriches them—explaining what each type returns (10-K metrics vs adverse-event counts) and what the values should represent (tickers/CIKs vs drug names). It also clarifies behavior like 'largest/most/biggest reads off the top', adding meaning well beyond the schema.

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

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

The description clearly identifies 'side-by-side comparison' as the core function with specific trigger phrases ('compare X and Y', 'which is bigger', 'rank these companies'). It distinguishes itself from sequential lookups by highlighting the parallel call behavior and mentions the entity types (companies or drugs), making it unmistakable from sibling tools like 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?

It explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides concrete query examples. It also differentiates usage by type (company vs drug), giving clear context and exclusions, which is textbook usage guidance.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses gap handling ('gaps[] for facets the data couldn't answer (never invented)'), contradictions[], excerpting behavior, hop fields, citation URIs, timing expectations, and depth-specific behaviors. No contradiction with annotations.

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

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

The description is long but information-dense, covering purpose, alternatives, account requirements, depth details, and output format. The main purpose is slightly delayed by the account/login preamble, but overall it is well-organized and each sentence carries meaningful 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?

With no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers limitations, timing, and account tiers, making it complete for a complex research tool.

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

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

Schema covers 100% of parameters, but description adds substantial depth semantics: explains facet counts per depth, gap-recovery hop for standard, lead-chasing for thorough, contradictions scan, and single-hop quick. Also clarifies the 'question' parameter accepts broad/multi-part natural language.

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

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

The description uses specific verbs and resources: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources', 'Decomposes your question into focused facets, routes each to the right one of 5,344 tools IN PARALLEL, and returns a findings packet'. It clearly distinguishes itself from open-web search and sibling tools like ask_pipeworx.

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

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

Explicitly states when to use: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also mentions account requirements and alternative if not signed in.

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

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

Annotations already cover read-only and idempotent behavior. The description adds valuable context beyond that: it discloses that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This gives the agent a clear expectation of the return value without contradicting annotations.

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

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

The description is somewhat wordy due to the long list of data domains, but every sentence adds value. It is front-loaded with the core action ('Find tools'), then covers use cases, return format, and placement in the tool-selection flow. The list could be trimmed, but it is not extraneous.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas.' It also gives usage context. It doesn't mention edge cases like no matches or pagination, but for a discovery tool this is reasonably complete.

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

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

The schema has 100% coverage with clear descriptions for each parameter. The description adds meaning by providing example query topics ('analyze housing market trends', 'look up FDA drug approvals') and by explaining that the query is a 'natural language description of what you want to do.' This goes beyond the schema's bare descriptions and helps the agent formulate a proper query.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' This is a specific verb+resource that distinguishes it from siblings, which perform actual data lookups or research. It also lists concrete domains (SEC filings, FDA drugs, etc.) to illustrate scope.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent not only when to use it but also when it should be the first step, which is strong 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 include readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds rich behavioral context: it fans out in parallel across multiple external data sources, returns specific fields (CIK, filings, fundamentals sorted by period_end, patents, news fallback chain, LEI), notes the soft-fail for the USPTO PatentsView API sunset, and explains the GDELT→GNews fallback. This goes well beyond what annotations convey.

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

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

The description is a single dense paragraph, but it is front-loaded with example user prompts and every sentence carries substantive information about sources, outputs, and fallbacks. It could be slightly better structured (e.g., bullet points), but it remains efficient and readable for an agent.

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

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

Given the tool's complexity—multiple source fan-out, fallbacks, no output schema—the description covers all critical aspects: input format, exact output fields, ordering of fundamentals, source list, sunset/soft-fail behaviour, and fallback chain. It clearly explains the edge case of name-based queries and how to delegate. This makes the tool self-contained for an agent.

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

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

Although the schema description already covers both parameters (type with enum, and value with ticker/CIK examples), the description adds practical examples ('AAPL', '0000320193') and repeats the constraint that names are not supported, reinforcing the expected input format. This is valuable because it clarifies how to resolve user intents to the correct parameter values.

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

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

The description opens with concrete example queries and immediately states the tool's specific function: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact sources and returns fields, and explicitly differentiates from sibling tools by instructing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing name-only queries to resolve_entity.

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

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

The description provides explicit when-to-use guidance: prefer for holistic company views, and also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' It also states the parallel fan-out strategy and context for using a ticker vs. CIK, which helps the agent decide when to invoke 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 already declare destructiveHint=true and readOnlyHint=false, and the description repeats the deletion intent without adding new behavioral details like permanence, authorization requirements, or effects on related data. It adds some context about the memory type and key-based deletion, but no significant new transparency.

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 action, and every sentence adds value—no filler or repetition. It includes use cases and complementary tools without waste.

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

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

For a simple one-parameter delete tool with strong annotations and schema coverage, the description adequately covers purpose, usage, and the parameter. It does not describe return values, but that is not essential for this operation. Slightly more detail on expected results could push it to a 5.

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

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

Schema description coverage is 100%, and the description does not add any extra meaning beyond the schema's 'key' parameter description. This meets the baseline for high coverage but does not enhance understanding of the parameter beyond what the schema provides.

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

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

The description states a specific verb ('Delete') and resource ('previously stored memory by key'), making the tool's function immediately clear. It also distinguishes from siblings like 'remember' and 'recall' by focusing on the deletion 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?

The description provides explicit use cases ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with 'remember' and 'recall,' but it does not explicitly state when not to use the tool or contrast with 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?

The description explains the tool's behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. It also clarifies that the output is 'a single text blob', which goes beyond the annotations. While annotations already declare readOnlyHint and idempotentHint, the description adds process-level detail without contradicting them.

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

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

The description is compact and well-structured, leading with the main purpose, then the process, then the output, and finally use cases. Every sentence adds value, and there is no redundant or filler content. It is front-loaded with the 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?

The tool has only two parameters and no output schema, but the description covers the key aspects: what it does, how it works, what it returns, and when to use it. Minor gaps exist, such as error handling or limits of max_links, but overall it provides sufficient context for an agent to use the tool correctly.

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

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

The input schema provides full descriptions for both parameters (url and max_links), and the description does not add extra meaning beyond what the schema already states. The only slight addition is the mention of 'standard llms.txt markdown format', but it does not explain parameter behavior further. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It specifies the resource (llms.txt), the action (generate), and the target audience (AI crawlers like ChatGPT, Claude, Perplexity). It also distinguishes itself from sibling tools by focusing specifically on generating the llms.txt file rather than broader visibility checks.

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 'Useful for:' section provides concrete use cases: indexing a client's site, drafting for personal projects, or auditing a competitor. This gives clear context on when to use the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full exclusion/alternative 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 cover the read-only, idempotent, and non-destructive nature. The description adds useful behavioral context: it returns only the 100 most popular templates (a bounded set), and implies that template IDs are included in the output (by mentioning their use with caption_image). This enriches the agent's understanding beyond the static annotations.

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

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

The description is three sentences, each contributing critical information: the action (browse templates), the return data, and the downstream workflow (use IDs with caption_image). It is front-loaded and concise with zero 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?

As a simple, parameterless read-only tool with an output schema available, the description covers all essential aspects: what it does, what it returns, and how the results are meant to be used. There is no missing information that would prevent an agent from correctly invoking or interpreting the tool.

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

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

There are zero parameters, so the schema inherently covers everything (100% coverage). The description correctly implies no input is required, and the baseline for zero parameters is 4. It does not need to explain parameter meaning as there are none.

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

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

The description clearly states the tool lists the 100 most popular meme templates, which is a specific verb+resource combination. It also enumerates the exact return fields (template name, image URL, dimensions, text box coordinates), distinguishing it from any sibling tool that might handle templates or memes.

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

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

The description provides clear usage context by instructing users to use template IDs with caption_image after browsing templates. This inherently explains when this tool is useful (as a precursor to meme creation). No explicit exclusions or alternatives are mentioned, but given no sibling tool appears to serve the same purpose, this guidance is sufficient.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by disclosing the scope (caller's subscriptions only), default filter (active), and the specific return fields. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core action and resource, followed by return fields and usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

For a simple list tool with one optional parameter, no output schema, and comprehensive annotations, the description is complete. It covers purpose, usage, return values, and default behavior. The sibling context (subscribe/unsubscribe) makes the use case clear.

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

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

The only parameter, include_inactive, is fully documented in the input schema (100% coverage). The description's mention of 'active subscriptions' implies the default behavior, but it does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing this from sibling tools like subscribe and unsubscribe. It also specifies the returned fields, making the 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 explicitly states when to use it: 'before adding more' subscriptions (i.e., before subscribe) and 'to find an id to cancel' (before unsubscribe). It also implies the default behavior of showing only active subscriptions, with an optional include_inactive parameter for cancelled ones.

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 are all false, providing no hints. The description adds meaningful behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads digests daily. It does not describe any side effects or response behavior, but the disclosed traits go well beyond the annotations.

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

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

Five sentences, each earning its place. The first sentence states purpose, the second gives usage scenarios, the third provides content rules, the fourth mentions roadmap impact, and the fifth covers rate limits and cost. No wasted words and logically ordered.

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

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

Covers purpose, usage, content guidelines, rate limits, and cost. The schema fully documents the nested context object and the required strings. No output schema exists, so return values need not be explained. Minor gap: doesn't state what happens after submission (e.g., confirmation), but this is non-critical for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs—don't paste the end-user's prompt') and explains the type enum in plain language ('broken, missing, or needs to exist'). This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also enumerates specific feedback categories (bug, feature/data_gap, praise), which distinguishes it from sibling research tools. The verb 'tell' plus resource 'Pipeworx team' makes it immediately obvious what this tool does.

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 when-to-use guidance is provided: '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 gives content rules ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and operational notes (rate-limited, free, no quota). This is textbook usage 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond this, including caching ('Cached 5min-1h depending on window') and data provenance ('derived from CF analytics-engine, no PII'), which are not present in 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 well-structured: a lead-in sentence, a returns sentence, a bulleted use-case list, and a metadata note. Each sentence earns its place, with no filler or redundancy, and the key purpose 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?

Despite having no output schema, the description sufficiently explains the return value structure ('pack, tool, count'), caching behavior, and use cases. For a simple tool with one optional parameter and strong annotations, no significant gaps remain.

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

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

The input schema already provides a rich description for 'window' including enum values and semantic guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description merely echoes the window options without adding substantial meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume' over a specified window. The opening sentence frames it as aggregate agent usage, making it distinct from sibling tools like discover_tools, which focus on capability 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?

The 'Useful for' section provides three concrete use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to decide appropriately.

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

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

The description adds substantial behavioral detail beyond the annotations: the partition filter with placeholder detection and null return, the fill check that prices against live CLOB depth and warns not to trade when realizable_edge_pp ≤ 0, and the semantic similarity threshold of ≥0.30 Jaccard. It also discloses the exact response fields. This goes far beyond what the readOnly/openWorld/idempotent hints convey.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then uses clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure the dense but essential information. 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?

No output schema exists, yet the description fully documents the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the partition_check object. It also explains edge cases like placeholder filtering and the fill check's realizable edge, making the tool's behavior predictable.

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

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

Although schema coverage is 100%, the description enriches both parameters significantly. For 'event' it explains the mode, provides example slugs, and describes the checks performed. For 'topic' it explains cross-event scanning, gives seed examples, and notes what patterns it catches. It also clarifies the default no-args behavior, which the schema doesn't mention.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and explains what each does, setting it apart from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and even recommends 'event (recommended for a specific market)'. It also references an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This provides clear context and exclusions.

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

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

The description goes far beyond the annotations, which only indicate read-only, idempotent, and non-destructive behavior. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), the response envelope (by_segment, fed_candidates, _diagnostics), the 24h-move warning, and detailed internal logic (e.g., partition placeholder filtering, Kelly caps, per-sport α values). This level of detail helps an agent understand what to expect and why segments might be empty, adding significant value beyond the structured annotations.

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

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

The description is long and dense, but it is well-structured with clear uppercase section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose. While every section is informative, some details like 'gates relaxed Run 8 from prior 85%/5%/50:1' may be extraneous for an agent selecting the tool, making it slightly less concise than ideal.

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 and the absence of an output schema, the description thoroughly explains the return structure, including the three primary segments, fed_candidates/fed_note, and the diagnostics object. It also covers edge-case behavior (e.g., empty segments, placeholder filters, 24h-move warnings) and caching. This provides a complete picture of the tool's behavior and outputs, leaving minimal ambiguity for an agent.

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

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

Schema coverage is 100% with each parameter already well-described, so the baseline is 3. The tool description adds extra semantic context, such as the distinction between min_kelly and min_partition_leg_kelly ('Partition arbs always return kelly_fraction_half=0 at the parent level by design... min_kelly never filters them'), and explains the tradeable-edge knobs collectively. This supplements the schema with nuanced behavioral details, though the schema itself is already strong.

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

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

The opening sentence explicitly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the resource (Polymarket markets), the action (scan and return opportunities), and the outcome (edges based on Pipeworx data vs market price). The description further differentiates from sibling tools like polymarket_arbitrage by focusing on Pipeworx-driven signals and providing a discovery-oriented use case ('what should I bet on today').

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 clearly states when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the purpose of knobs (min_liquidity, max_spread_pp) and the output structure, giving context for usage. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusionary guidance.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses significant behavioral traits: the 60-day snapshot TTL, snapshot creation on cache-miss, gaps meaning no scan happened, and decay computed from daily closes of edge_pp_net (net of default slippage) rather than intraday. It also details the response structure (tracked, expired, snapshot_dates) and the signed nature of edge values. This adds substantial context beyond the annotations and is not contradictory.

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 structured into clear sections: purpose, args, response, and limits. It is sophisticated and packs dense information (TTL, slippage, response fields, gap semantics) without wasted words. Every sentence adds value, and the bolded response field names make the structure scannable.

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

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

With no output schema, the description takes on full responsibility for explaining return values, and it does so thoroughly: tracked[] with trend and decay_pp_per_day, expired[] with lifespan_days, and snapshot_dates[]. It also covers data limitations (TTL, snapshot enablement, gaps, daily closes) and ties the semantics to trading decisions. This is complete for a read-only query tool with two simple parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description's Args line restates the parameter names, defaults, and a max (days: default 14, max 30; window: default '1wk') already present in the schema. It adds the phrase 'snapshot family' and 'lookback' which provide minor conceptual framing but do not materially improve on 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 opens with a specific verb+resource pair: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the targeted question 'how long has this edge existed and is it shrinking?' and explicitly distinguishes itself from siblings by noting a fresh wide edge and a 3-week-old wide edge are different trades. This clearly separates it from related tools like polymarket_edges.

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

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

The description gives clear context for when to use the tool: when you need edge persistence/decay history rather than just current edge values. It explains why this matters ('the latter is wide for a reason nobody is willing to take') and notes data gaps from cache-miss behavior. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

The description discloses substantial behavioral nuance beyond the annotations: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), interprets size_usd differently by mode, identifies thin_legs and forced_directional_risk, and warns about partial fill dangers. Even though readOnlyHint/openWorldHint/idempotentHint already establish a safe read-only profile, the description adds rich operational detail that materially helps an agent anticipate outcomes and risks. No contradiction with annotations exists.

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

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

Though lengthy, the description is exceptionally well-structured: it front-loads the core purpose, then separates SINGLE-MARKET and BASKET modes in uppercase, lists return fields in a flow, and closes with a clear 'USE THIS' directive. Every sentence carries distinct operational information, and the density is justified by the tool's complexity. 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 tool with no output schema, the description provides a thorough account of expected returns, edge cases (thin books, partial fills, forced directional risk), and real-world consequences. It covers all four parameters, both usage modes, security/prerequisite context (only use before arb/edge trades), and the tool's limitations. An agent has sufficient information to decide when and how 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?

The input schema already provides 100% coverage with solid per-parameter descriptions, so the baseline is 3. The description, however, adds meaningful cross-parameter semantics: it clarifies that exactly one of market or event must be passed, explains how 'side' defaults differ between modes, and elaborates the size_usd semantics in basket mode (settlement notional, shares per leg). This goes beyond what the schema states individually, earning a 4.

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

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

The description opens with a crisp, specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly articulates the tool's function, distinguishes between single-market and basket modes, and explicitly ties its role to sibling tools (polymarket_arbitrage, polymarket_edges) by stating when it should be used. This goes far beyond a vague or tautological summary.

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 delivers explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' — directly stating when to use the tool. It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), providing clear context and exclusions. The two-mode explanation further guides selection between market and event inputs.

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

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

The description goes far beyond the readOnly/idempotent/openWorld annotations by explaining the matching algorithm's behavior, the meaning of compatibility_warning for non-equivalent bet shapes, and the skip counters. It also sets expectations that most pre-mapped topics return warnings, giving a honest preview of the tool's real-world performance.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every section earns its place, though there is some redundancy in warnings (e.g., 'pre-mapped ≠ tradeable' emphasized twice) and the density of inner fields makes it heavier than strictly necessary.

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 compensates by explaining the response shape: leg-by-leg raw probabilities, matched spread[].top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skip counters. It also provides the critical caveat about spread tradeability, making the tool's outputs interpretable even in edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable interaction semantics - the two modes and that explicit parameters override the topic-mapped side - which goes beyond the per-parameter schema descriptions. However, it doesn't add much about parameter formats or constraints, so a 4 is appropriate.

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

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

The description opens with a clear statement of function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then elaborates two modes and response details, making the tool's purpose unmistakable and distinct from generic arbitrage tools by naming the specific venues and the compatibility logic.

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 and when-not-to-use guidance: it details the two invocation modes (topic shortcuts vs explicit tickers), explains that compatibility_warning and temporal_alignment:false make spreads meaningless, and warns that 'pre-mapped ≠ tradeable.' This is actionable usage guidance even without naming sibling alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the omit-key-to-list-all behavior, which goes beyond what annotations convey.

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

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

Three sentences, each earning its place: the first states the core action, the second explains the use case, and the third gives scoping and companion tools. No fluff or redundancy.

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

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

For a simple one-parameter tool with strong annotations and full schema coverage, the description is complete. It explains what the tool does, when to use it, scoping, and relationships to sibling tools. No output schema is needed for a straightforward lookup.

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

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

Schema description coverage is 100% and already documents the key parameter and its optional behavior. The description restates this ('omit the key argument') and gives examples, but adds little meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Retrieve') and clearly identifies the resource (values saved via remember) plus a distinct behavior (list all saved keys). It also distinguishes itself from sibling tools remember and forget by naming them explicitly.

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

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

Provides explicit guidance: use it to look up context the agent stored earlier without re-deriving it, and pairs it with remember to save and forget to delete. This clearly communicates when to use this tool versus alternatives.

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

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

The description mentions the mark_read:true parameter that flags events as read and affects future calls, which is a state mutation. This contradicts the readOnlyHint annotation (which claims the tool is read-only). Other details like return fields and endpoint are helpful, but the contradiction is significant.

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 at four sentences, front-loaded with the core purpose, and each sentence provides useful information (return fields, filtering, mark_read behavior, alternative access). It is not overly verbose given the tool's complexity.

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

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

With no output schema, the description explains return fields and covers filtering, mark_read, and polling behavior. It omits details on limit and unread_only, but these are fully described in the schema. The external endpoint adds extra context, making it largely complete.

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

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

The schema already documents all 5 parameters, and the description supplements this with valuable semantics: it explains the side-effect of mark_read, provides a concrete example filter ('sec_8k'), and clarifies the since parameter as ISO timestamp, adding meaning beyond the schema.

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

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

The description clearly states that the tool pulls fired events from the subscription feed, specifying the action (pull) and resource (fired events from your subscription feed). It also names return fields (source, citation_uri, raw payload) and distinguishes it from sibling tools like list_subscriptions and recent_changes.

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 usage context by explaining filtering options (type, since) and notes that polling works fine, with an alternative HTTP endpoint for scripts/dashboards. It does not explicitly exclude sibling tools but gives enough context to understand 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?

Beyond the annotations (readOnly, idempotent), the description explains the fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO soft-fail status, and return structure (grouped changes[], total_changes, citation URIs). This adds substantial behavioral context that annotations alone do not convey.

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

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

The description is dense but well-organized: it front-loads user-intent phrases, then states the core function, then details backends and output. A few extra paraphrases ('news on Tesla recently') could be trimmed, but every sentence contributes to mapping user questions to tool capabilities, so it's appropriately sized for the tool's complexity.

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

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

For a tool with three parameters and no output schema, the description covers all essential context: what sources are hit, fallback and failure behavior, output shape, and the alternative tool. The presence of strong annotations (read-only, idempotent) and detailed parameter descriptions means the description can focus on behavioral nuance, which it does thoroughly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving examples for `since` ('7d', '30d', '1y') and a recommendation ('Use "30d" or "1m" for typical monitoring'), plus clarifying that `value` can be a ticker or CIK. This goes beyond the schema's stated types.

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

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

The description opens with sample queries ('What's new with X' etc.) then clearly defines the tool: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also distinguishes itself from entity_profile, making the purpose specific and unambiguous.

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

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

Provides explicit usage guidance: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also communicates the tool's scope via example queries and notes fallback behavior (GDELT->GNews), giving the agent strong direction on when to invoke it.

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

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

Adds valuable context beyond annotations: persistence duration (24 hours for anonymous, persistent for authenticated users) and scoping by identifier. The description does not contradict annotations (readOnlyHint=false, idempotentHint=true), though it could mention overwrite behavior or size limits. Still, it discloses key behavioral traits not present in structured fields.

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

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

Five concise sentences that front-load the primary purpose, then explain when to use, storage mechanics, retention behavior, and related tools. No filler or redundant information; every sentence serves a distinct function.

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 two-parameter tool with no output schema, the description is fully complete. It covers purpose, usage triggers, storage scoping, retention periods, and links to sibling operations. There are no significant informational gaps for an agent to invoke this tool effectively.

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

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

Schema already provides 100% coverage with clear descriptions and examples for both key and value. The description's examples ('a resolved ticker', 'target address') reinforce usage but do not add new parameter-level semantics beyond what the schema offers. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states a specific action ('Save data the agent will need to reuse later') with a concrete resource (key-value store scoped by identifier). It distinguishes itself from sibling tools by explicitly mentioning recall and forget for retrieval and deletion, making the 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?

Provides explicit 'when to use' guidance with concrete examples (resolved ticker, target address, user preference, research subject) and states the benefit ('so you don't have to look it up again'). It also names complementary tools (recall, forget) for related operations, offering clear situational 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 cover readOnly, idempotent, and non-destructive, so the description adds value by revealing that each call cascades through multiple lookup endpoints and replaces 2-3 manual lookups. It also mentions citation URIs returned, providing context beyond structured annotations.

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

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

The description is long but every sentence earns its place: examples, use-first directive, supported types, return details, and internal cascade behavior. It is front-loaded and densely informative with no redundancy.

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

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

With no output schema, the description must explain return values; it does so by listing fields and citation URIs per entity type. Combined with thorough schema coverage and annotations, an agent has complete information to select and invoke correctly.

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

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

Schema coverage is 100%, but the description goes further by detailing exactly what each type returns (e.g., company returns ticker + CIK + company_name) and that input values are auto-disambiguated. This enriches parameter meaning well beyond the schema.

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

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

The description states a specific action—resolving a user-spoken NAME to a canonical/official identifier—and distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID lookup. It includes concrete query examples that make the purpose immediately recognizable.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives clear when-to-use guidance. However, it does not explicitly name alternative tools or state when not to use it, though the directive implies priority for this 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 declare readOnlyHint=true and destructiveHint=false, and the description adds methodology context: it probes each entity via ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the return shape ('ranked list with score, confidence, signal density per entity'), which adds value 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 front-loaded with the core purpose, then adds methodology, use case, and return details. It is four sentences with no fluff; the example quote earns its place by making the intent tangible. It is appropriately sized for a moderately complex tool.

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

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

Despite no output schema, the description explicitly states the return fields (score, confidence, signal density). It explains the probing mechanism and the subject/competitor structure, giving the agent enough context to invoke the tool correctly and interpret results. All required constraints (e.g., entity count 2-8) are already in the schema.

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

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

With 100% schema coverage including the 'First entry treated as the subject' nuance, the description does not need to add much. It does restate 'your brand + N competitors' but adds no new meaning beyond the schema. Baseline 3 is appropriate since the schema already documents all parameters fully.

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

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

The description opens with a specific verb+resource combination: 'Compare AI visibility across multiple entities side-by-side,' clearly distinguishing this from the single-entity sibling ai_visibility_check. It further specifies the ranking behavior and the example query ('does Claude know about us as well as our competitors?') makes the 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 states it is 'Useful for competitive AI-marketing audits' and gives a concrete use case. It also notes that it probes each entity with ai_visibility_check, implying the alternative for single-entity checks, but it does not explicitly state 'use this when comparing multiple entities instead of ai_visibility_check' or list when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: bundlephobia's first measurement may take 5-30 seconds, partial failures degrade gracefully, and the sources_failed field will indicate timeouts. This helps the agent anticipate latency and incomplete results.

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 information-dense yet well-structured: it opens with the core purpose, then usage, return value summary, ecosystem scope, and failure behavior. Every sentence adds value, and the length is justified given the tool's composite nature. It is front-loaded and logically organized.

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

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

With no output schema, the description fully enumerates what is returned (summary block fields, per-advisory details, links, alternative versions). It also covers ecosystem constraints and timeouts, giving the agent a complete picture of tool behavior. This is exceptionally thorough for a complex 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%—both package and version have clear descriptions. The description adds no significant new parameter semantics beyond what the schema already states (e.g., default version, scoped packages). Per the rubric, a baseline of 3 is appropriate when 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 identifies the tool as a composite 'should I add this npm package' check, with specific verb ('check'), resource ('npm package'), and outcome. It distinguishes from sibling research tools by referencing concrete data sources (deps.dev and bundlephobia) and the exact scope of the evaluation.

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

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

Explicit usage triggers are given with example questions: 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides a clear when-not case: non-npm ecosystems (PyPI, Maven, Cargo, Go) should go to deps.dev:version directly, effectively naming the alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial context beyond them: the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, a 200K character truncation cap that is 'truncated and flagged,' and output details (character offsets and similarity scores). No contradictions with annotations.

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

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

The description is three sentences, front-loaded with purpose, then usage, then technical constraints. No filler; each sentence earns its place. It covers what, when, and the key limitations 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?

With no output schema, the description effectively communicates the return format (passages with offsets and similarity scores). It also covers input limits, the reason to use the tool (context saving), and the relationship with a sibling tool. This is a complete and self-contained explanation for an agent.

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

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

The schema already covers all three parameters with descriptions (100% coverage), but the description enriches them: it clarifies that 'text' is 'already pulled' content, gives query examples ('supply-chain risk', 'fiscal year 2024 revenue'), and mentions the 'top-N' behavior tied to limit. This goes beyond the schema's bare descriptions.

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

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

The description opens with a clear verb+resource: 'Semantic search INSIDE a fetched record.' It specifies the operation, input, and output (top-N passages with offsets and similarity scores). It also distinguishes itself from sibling ask_pipeworx_grounded by explaining the division of labor: fetch first, then search within.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative approach by pairing with ask_pipeworx_grounded, telling the agent to 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear, actionable 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 discloses authentication needs, SMS delivery caps, and the always-on feed behavior, adding context beyond the annotations. No contradiction with readOnlyHint=false or idempotentHint=true.

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

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

The description is front-loaded with purpose and well-organized, but somewhat verbose and repeats some schema details. It remains efficient for the tool's complexity.

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

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

The description covers purpose, account requirements, supported types, and delivery channels. It omits webhook specifics, but those are fully documented in the input schema, so overall completeness is adequate.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds minor examples like 'items:["5.02"] = officer change' but is largely redundant with 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 'Create a proactive monitoring subscription to a live-data event stream' and mentions returning the subscription id. It enumerates supported types, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies a prerequisite ('Requires a Pipeworx OAuth account') and describes delivery channels, but does not explicitly reference alternatives or when-not-to-use cases. This provides clear context without formal 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 the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds context beyond annotations by explaining the return format (category-bucketed example questions with exact tool and argument shapes), the live-catalog source, and the optional topic focusing behavior. There is 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 a single paragraph but well-structured with example queries, purpose, output, parameter behavior, and usage timing. Every sentence provides useful information; while somewhat long, it is not verbose or redundant, and it is appropriate for an onboarding tool. A slightly tighter structure could earn a 5, but this is still highly 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?

For a relatively simple tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, input semantics, return content, and when to use. It even references related meta-tools, giving contextual completeness that far exceeds minimum requirements. The agent can confidently invoke this tool.

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

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

The schema already documents the `topic` parameter with 100% coverage, so baseline is 3. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and clarifying the effect of omission (full spread) versus focusing. This enriches the parameter semantics beyond the schema's enum-like list.

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 what the tool does: it provides category-bucketed example questions to help an agent know what to ask Pipeworx. It uses specific verbs like 'returns' and positions it as the onboarding entry point, distinguishing it from sibling tools like ask_pipeworx and entity_profile, which are instead about obtaining actual data.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to call with no arguments vs. with a topic, and mentions alternatives (meta-tools) for subsequent actions. This clarifies both when and when-not to use the tool.

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

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

Annotations already indicate non-destructive behavior (destructiveHint=false) and non-read-only (readOnlyHint=false), but the description adds crucial context: ownership is enforced, and the row is deactivated rather than deleted, preserving history via recent_alerts. This exceeds the annotation baseline and fully explains 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?

The description is two sentences, both informative and directly relevant. It front-loads the core action ('Cancel a subscription by id') and immediately follows with essential behavioral notes. No unnecessary words or filler.

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

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

Given the tool's simplicity (one parameter, no output schema) and the rich annotations, the description is complete. It covers purpose, ownership restrictions, and the non-destructive deactivation side effect, which is sufficient for an agent to invoke the tool correctly. Nothing critical is missing.

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

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

The input schema already documents the single 'id' parameter fully (UUID returned by subscribe), achieving 100% schema description coverage. The description merely repeats 'by id' without adding new meaning or syntax details beyond what the schema provides, 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 states 'Cancel a subscription by id', which is a specific verb+resource pair. It also clarifies that the subscription is deactivated rather than deleted, distinguishing it from related sibling tools like subscribe and list_subscriptions. The purpose is 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 clearly implies when to use this tool (to cancel a subscription) and adds ownership enforcement ('you can only cancel your own subscriptions'). However, it does not explicitly name alternatives or exclusions, leaving the when-not-to-use guidance implicit rather than explicit.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds significant behavioral context: it returns a specific set of verdicts, includes grounded citations and reasoning, uses a structured SEC EDGAR fast path for financial claims, and automatically falls through to a grounded pipeline. No contradiction with annotations.

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

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

The description is long but information-dense, with every clause serving a purpose. Trigger phrases are front-loaded, followed by routing logic, return semantics, and the efficiency benefit. It could be slightly reorganized for scannability, but there is no filler.

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

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

For a tool with only 2 parameters and no output schema, the description thoroughly covers what the tool does, when to use it, how it handles different claim types, what it returns, and how it compares to a naive multi-step approach. No critical piece of information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the claim's implied tolerance, is capped at 5 by default, and suggests using 1–2 for hallucination detection. This goes beyond the schema's bare field description.

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 trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and names the specific action: natural-language claim verification against authoritative sources. It clearly distinguishes this tool from generic query tools by describing its dedicated role and the multi-step pipeline it replaces.

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 the agent needs to check whether something a user said is factually correct' and provides routing rules for company-financial vs. other claims. It doesn't explicitly name alternative sibling tools or state when NOT to use it, but the usage context is clear enough.

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