Askdata Xk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: default model is free, Anthropic requires a BYO key with direct payment, and it describes the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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, each earning its place: first sentence covers the core action and return type, second sentence gives parameter details and cost implication, third sentence lists use cases. No filler, front-loaded with key information.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description adequately explains the return format (per-model object + combined view), covers all parameters, and provides usage scenarios. No gaps given the annotations and schema richness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it explains the default model for the 'models' parameter, states that _apiKey is passed through to Anthropic and entails direct payment, and clarifies that 'context' helps disambiguate. This provides useful operational guidance.

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 explicitly that the tool probes LLMs and scores visibility (0-100) per model, using specific verbs like 'probe' and 'score'. It distinguishes from siblings (e.g., ask_pipeworx, entity_profile) by its unique focus on visibility scoring across multiple models.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains when to use the default model vs. Anthropic with _apiKey. However, it does not explicitly list when not to use this tool or mention alternatives among siblings.

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

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

Annotations already cover read-only, open-world, and idempotent behavior. The description adds meaningful context: it routes to 5,908 tools, auto-fills arguments, and returns stable pipeworx:// citation URIs. There is no contradiction with 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 verbose and poorly structured: the first paragraph repeats the 'even if web search could also answer it' caveat twice, and it is followed by a nonsensical second paragraph about deep_research and dignity. This is not concise and the irrelevant tail undermines the structure.

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 essential invocation details are present: one natural-language question, routing behavior, and citation-bearing structured output, even without an output schema. However, the garbled tail could mislead an agent toward deep_research and introduces ambiguity about the tool's exact scope, so completeness is only moderate.

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 question parameter and its aliases with 100% coverage. The description goes further by providing numerous example queries and clarifying that the input is a factual request in natural language, which helps an agent frame the parameter correctly.

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 first paragraph clearly identifies the tool as a router that takes a natural-language question and returns structured answers with citations from 5,908 tools across many domains. However, it does not explicitly differentiate from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, and a garbled second paragraph mentioning deep_research introduces noise.

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 prefers this tool over web search, lists trigger phrases ('what is', 'look up', 'find', etc.), gives concrete examples, and says to start here for most questions. It does not, however, specify when to choose sibling tools such as ask_pipeworx_beta, ask_pipeworx_grounded, or deep_research instead.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses valuable behavioral context: it is experimental, no candidate is currently active so it matches ask_pipeworx exactly as of a specific date, and it falls back to nothing — it is a full working router. This dispels the misconception that 'beta' implies non-functional and explains the evaluation mechanism. 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?

Four sentences, each earning its place: identity, current state, usage guidance, and a functional reassurance. The key facts are front-loaded, and the length is justified by the need to convey experimental status and parity with the stable router.

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

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

Complete for a single-question routing tool: one required parameter with documented aliases, strong annotation coverage, and a pointer that the response shape matches ask_pipeworx since there is no output schema. The only gap is that the response shape reference requires the agent to consult a sibling 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%, with the question parameter and all five aliases fully documented in the schema itself. The description only adds a marginal confirmation that arguments are identical to ask_pipeworx, but doesn't contribute new semantic meaning beyond the schema. Baseline 3 for high schema coverage 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router over 5,908 tools with the same arguments and response shape. This tells the agent what it does (routes a question to a large tool landscape) and distinguishes it from the stable ask_pipeworx and the grounded variant. It leans on the reader knowing what ask_pipeworx is, so it isn't fully self-contained.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains the results-comparison process against the stable router. It names the primary alternative but doesn't give exclusion criteria such as when to prefer ask_pipeworx_grounded or the stable router instead.

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

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

This goes well beyond the annotations. It discloses the exact success return shape, the refusal envelope with specific refusal_reason values, and the condition under which refusals occur. It also transparently notes the extra LLM call cost. These are meaningful behavioral traits that annotations alone do not provide.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return/refusal formats, usage guidance, and cost tradeoff. Key differentiators are front-loaded, and the structure makes the tool's behavior easy to parse.

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 fully explains what the tool returns on success and failure, including refusal reasons. It also provides enough context for invoking the tool with a single required question parameter and correctly choosing it over siblings. Nothing essential for safe and correct use is missing.

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

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

Schema coverage is 100%, and the schema clearly documents the single meaningful parameter 'question' along with all aliases. The description itself adds little about parameter semantics, but because the schema already carries that burden, the 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 opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the resource (Pipeworx tool routing) and the distinguishing behavior (extracts answers using ONLY tool result content). It also contrasts with the sibling ask_pipeworx, so an agent can distinguish them immediately.

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 guidance with 'Use whenever an answer will be quoted, cited, or acted on' and names concrete domains where hallucination avoidance matters. It also provides an explicit alternative: 'prefer ask_pipeworx for casual lookups,' including the cost tradeoff of one extra LLM call. This fully covers when, when-not, and alternatives.

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

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

The description adds extensive behavioral context beyond the annotations, including how it resolves markets, classifies bets, fans out to data sources, handles errors (low-confidence, closed markets, wide spreads), and returns response shapes. It is consistent with the readOnlyHint annotation and provides rich detail about internal behavior.

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

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

The description is thorough but verbose, spanning over 500 words. It is well-structured with sections and examples, and the first sentence provides the core purpose. However, some details could be condensed without losing value, making it slightly less concise than optimal.

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 classifiers, fan-out, resolution, evidence) and absence of an output schema, the description is remarkably complete. It covers input formats, resolution logic, response structure, error conditions, cancellation rules, and safety mechanisms. An agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra beyond the schema's parameter descriptions. For example, the market parameter's ability to accept slug, URL, or question text is already in the schema. The depth parameter's defaults and include_raw's summary behavior are also in the schema. The description does not add significant new semantic information.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and provides concrete use cases. It distinguishes itself from sibling tools by its comprehensive single-call research approach, though it doesn't explicitly name alternatives.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides guidance on when to use but does not explicitly say when not to use alternatives. The detailed safety conditions and edge cases also help guide usage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: for companies, it pulls latest 10-K data from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drugs, it pulls FAERS adverse event counts, FDA approval counts, and active trial counts. It also mentions sorted output and citation URIs.

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

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

The description is comprehensive but slightly lengthy. It is well front-loaded with example triggers and immediately states the core functionality. Every sentence adds value, though a minor redundancy could be trimmed.

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

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

Given the simplicity (2 parameters, no output schema), the description is remarkably complete. It covers data sources, edge cases (off-calendar fiscal years), sorting, and the number of sequential lookups it replaces. No 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?

Schema coverage is 100% with both parameters described. The description adds valuable context: explains that 'values' for company type are tickers/CIKs (with examples like AAPL, MSFT) and for drug type are names (with examples like ozempic, mounjaro). It clarifies the format and constraints.

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

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

The description starts with example queries ('Compare X and Y', 'X vs Y', etc.) and explicitly states it does side-by-side comparison of 2–5 companies or drugs. It clearly distinguishes from sequential single-pack lookups, making the purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides criteria for when to use (comparing companies or drugs). It also explains how results are sorted (by primary metric) for queries like 'largest'/'most'.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses grounding behavior (verbatim evidence, confidence, source, fetched_at), the explicit gaps[] anti-hallucination guarantee, hop/citation_uri semantics, contradictions[] on standard/thorough, semantic excerpting, latency, and account/plan requirements. This is rich, non-contradictory behavioral context.

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

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

The description is long, but nearly every clause carries operational value (auth, alternatives, return format, citations, gaps, depth behavior, latency). It is not perfectly front-loaded because account/signup instructions precede the core purpose, and some sections are dense, but nothing is redundant.

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

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

For a two-parameter tool with no output schema, the description is thorough: it covers prerequisites, alternatives, how the tool behaves, what the findings packet contains, how gaps are reported, depth semantics, and expected latency. No needed invocation detail 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 meaning beyond the schema by specifying that depth:'standard' includes a gap-recovery hop and contradictions scan, depth:'thorough' adds a lead-chasing hop and requires a paid plan, and that 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 states a precise verb+resource: performs grounded multi-source research across Pipeworx's structured data sources in one call, decomposing questions and returning citations/gaps. It explicitly contrasts with open-web search and names ask_pipeworx as the single-lookup sibling, so an agent can discriminate them.

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

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

Usage is explicitly conditioned: sign-in status selects between deep_research and ask_pipeworx, and question breadth selects deep_research over single-lookup alternatives. It also maps depth values to behavior, so the agent can choose quick/standard/thorough and knows the latency tradeoff.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states that 'each result is ready to call directly, no second schema lookup needed.' This fully discloses the behavior and output format.

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

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

The description is fairly long but well-structured: it starts with the core purpose, lists domains, describes output, and ends with usage advice. Every sentence adds value; however, it could be slightly more compact without losing information. Overall, it is appropriately sized for a complex meta-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?

Given the tool's complexity (6 parameters, many aliases, no output schema), the description covers purpose, usage, output format, parameter semantics, and examples. It compensates for the lack of output schema by describing the return value in detail. It is fully complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining that the 'query' parameter accepts natural language descriptions and provides aliases (task, q, description, search). It includes concrete examples like 'analyze housing market trends' and 'look up FDA drug approvals,' which go beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a broad list of domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by advising to call it 'FIRST when you have many tools available and want to see the option set.' This makes the purpose specific and differentiated.

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

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

The description includes explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implicitly tells when not to use (when you already know the tool) but does not list alternative tools for specific domains. The usage advice is clear and helpful.

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

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

Annotations already signal readOnly/openWorld/idempotent/non-destructive, and the description goes far beyond them by detailing soft-fail behavior (USPTO sunset), the meaning of empty sections ('an empty section is a real "no data", not a bug'), resolution behavior (resolved_from/resolved_to), source fallbacks (GDELT→GNews), and explicit sources_used/sources_failed reporting. This is rich, honest behavioral disclosure.

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

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

The description is a dense, unstructured wall of text with heavy semicolon use and several redundancies: the source list appears twice, the input-shape explanation repeats the schema, and the 'person/place coming soon' aside adds clutter. While the tool is complex and some length is justified, the lack of formatting and repetition hurts scanability and parsing efficiency.

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 there is no output schema, this description carries the full burden of explaining return values, and it does so thoroughly: it enumerates every output section (filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI), explains failure modes (resolved:false, soft-fail, empty sections), and notes expected edge cases (small-molecule drug companies showing no FDA products). An agent has enough context to invoke the tool and interpret its result 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 of both parameters, including accepted values and resolution behavior. The description adds concrete examples ('AAPL', '0000320193', 'Moderna') and clarifies that the type field values are interchangeable, but this is mostly reiteration of the schema rather than new meaning. Baseline 3 is appropriate for 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 that this tool creates a 'full cross-source profile of a US public company in ONE parallel call', enumerates the exact input shapes (ticker, CIK, company name), and lists the output sections in detail. It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, so an agent can understand exactly what it does and how it differs from the generic alternative.

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 trigger phrases ('Tell me about X', 'research Acme', 'brief me on Tesla') and an explicit preference instruction: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It does not explicitly name a sibling tool to prefer instead for non-holistic or private-company cases, but it does explain the resolved:false behavior for private companies. This is clear context with a minor gap in named 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 specify destructiveHint=true and idempotentHint=true. Description adds no additional behavioral context beyond 'Delete'.

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

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

Two concise sentences that front-load the action and include usage rationale. No unnecessary words.

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

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

Sufficient for a simple tool with one param, no output schema. Covers purpose, usage, and sibling relationship.

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 key parameter with description. No extra semantic value added by description beyond what 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?

Description explicitly states 'Delete a previously stored memory by key' - clear verb+resource. Distinguishes from siblings 'remember' and 'recall' by action type.

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

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

Provides explicit when-to-use scenarios: 'stale context, task done, clear sensitive data'. Also advises pairing with remember and recall.

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, idempotent, read-only behavior. Description adds process details (fetches page, extracts title/description/key links, emits standard markdown) and output format, providing full transparency without contradiction.

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

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

Two well-structured sentences: first sentence states purpose and outcome, second sentence elaborates on process, output, and use cases. Every sentence is 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?

Despite no output schema, the description fully explains return value (llms.txt markdown text) and optional parameter. With rich annotations and clear process, it provides complete contextual information for the agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining the output ('single text blob') and the process (extraction from URL), going beyond the schema's basic definitions.

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

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

Description clearly states the tool generates a production-ready llms.txt file from any URL, specifying the verb, resource, and scope. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

Explicitly lists three use cases (indexing client site, drafting own project, auditing competitor), helping the agent understand when to use. Lacks explicit when-not-to-use or alternative tools, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Beyond that, the description adds that only active subscriptions are returned by default and lists return fields, which is useful behavioral context.

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

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

Two sentences, no wasted words. Purpose and usage guidance are 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?

Given no output schema, the description lists return fields. Annotations cover safety. The simple parameter is explained. Sufficient for an agent to use 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% (parameter include_inactive is described). The tool description reinforces the default of active only but adds no new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by listing rather than modifying. The return fields are also specified.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and suggests alternatives (subscribing/unsubscribing).

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

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

The description discloses behavioral traits beyond the annotations: it explains that filing returns a claim_token, that passing it back later retrieves resolution status, and that it is rate-limited to 5 per identifier per day and free (doesn't count against quota). It also advises not to paste the end-user's prompt. These details add significant context not captured by 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 a single paragraph, but every sentence serves a purpose—covering purpose, usage cases, exclusions, message guidance, claim_token semantics, rate limits, and follow-up. It is front-loaded with the core action and flows logically from main purpose to supporting details.

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 no required parameters and a non-trivial dual mode (submit vs. check token), and the description explains both modes clearly. It covers the full workflow, constraints, and expected behavior, making it fully self-contained for an agent to 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?

Although schema coverage is 100%, the description enhances parameter understanding by showing how claim_token should be used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This goes beyond the raw parameter descriptions.

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

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

The description uses a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates itself from sibling tools like ask_pipeworx and discover_tools by focusing on feedback submission rather than research or search. The title 'Send Pipeworx Feedback' reinforces the 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 states when to use the tool ('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)') and provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' — directing users to file with other MCP servers instead. This is model 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 safe, read-only, idempotent. Description adds caching (5min-1h), data source (CF analytics-engine, no PII), and self-aggregating nature, going beyond annotations.

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

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

Two sentences with bullet-like use cases, front-loaded with main result. Every sentence adds value with no wasted words.

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

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

Tool has only one optional parameter and no output schema, but description specifies return values (top tools, top packs, total call volume) and caching. For a simple tool, it's fairly complete.

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

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

Schema coverage is 100% with enum. Description adds interpretation: shorter windows show hot items, longer windows show steady-state demand, adding meaning beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. Uses specific verbs and resources, and is distinct from sibling tools like discover_tools.

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

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

Lists three explicit use cases and describes window parameter behavior for different timeframes. Lacks explicit when-not-to-use or alternatives, but provides solid contextual guidance.

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

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

Annotations indicate readonly, open-world, idempotent, and non-destructive. The description adds rich behavioral context: partition checks, semantic anchors (Jaccard similarity), partition filters (placeholder slugs), fill checks against CLOB depth, and warnings about unrealizable edges. 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 lengthy but well-structured: it starts with the general purpose, then details each mode, and adds technical aspects like semantic anchors and fill checks. Every sentence provides necessary information, though some redundancy could be trimmed for perfect conciseness.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check in event mode). It covers all modes, edge cases (placeholder filtering, low similarity skipping), and actionable advice (do not trade if realizable_edge_pp <= 0). The tool's complexity is fully addressed.

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

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

Schema description coverage is 100% with good descriptions for both optional parameters. The description goes beyond the schema by adding usage context, examples, and detailed explanations of what each mode returns. It clarifies that event mode is recommended for specific markets and topic for cross-event scanning.

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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic), each with a specific use case, and the tool stands out from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use no arguments (trending_scan), event (single event slug), or topic (cross-event scan). It explains trade-offs, such as cross-event mode catching patterns single-event misses, and provides a warning about not trading when realizable_edge_pp <= 0. It also references a sibling tool (polymarket_fill_risk) for custom sizing.

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

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

Beyond annotations (readOnlyHint=true, etc.), the description details model families, edge metrics, slippage assumptions, caching ('Cached 1h at the KV level'), and diagnostic fields. This provides comprehensive behavioral context without contradicting annotations.

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

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

The description is front-loaded with the core purpose in the first sentence. It is lengthy but well-structured, covering output segments, response fields, knobs, and diagnostics in a logical order. Every part adds necessary detail.

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

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

With no output schema, the description fully explains return values (by_segment, diagnostics, edge fields) and model behaviors. It covers all essential aspects for using the tool, including parameter interactions and segment logic.

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

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

Schema coverage is 100% with parameter descriptions in the schema. The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their role, but most parameter meaning is already captured in 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return) and resource (Polymarket markets), and distinguishes it from siblings by focusing on model-driven and structural arbitrage opportunities.

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

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

The description sets context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' indicating ideal use cases. However, it does not explicitly specify when not to use the tool or mention alternatives such as polymarket_arbitrage.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavioral details: data source (daily snapshots), limitations (60-day TTL, snapshot gaps), and computational details (decay from daily closes). 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 and informative, but somewhat verbose with response details and limits. The first sentence effectively states purpose. While not overly long, it could be slightly more structured without losing clarity.

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

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

The description thoroughly explains the complex response format (tracked, expired, snapshot_dates) and limitations (60-day TTL, snapshot gaps). Given the lack of output schema, the description compensates fully, making the tool's behavior and output 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?

Schema coverage is 100%, so baseline is 3. The description adds context for 'days' (default 14, max 30) and 'window' (default 1wk), but does not significantly expand on the schema descriptions. It matches the schema closely, providing minimal additional value.

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

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

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

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

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

The description provides strong context for when to use the tool, explaining the importance of edge age in trading decisions. However, it does not explicitly mention alternatives or when not to use it, missing a small opportunity for clarity.

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, open-world, idempotent, and non-destructive. The description adds rich behavioral details: ladder walking, return fields like slippage_pp, thin_legs, forced_directional_risk, and the warning about basket partial fills. 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 front-loaded with the core purpose and uses clear structuring (SINGLE-MARKET, BASKET). While somewhat lengthy, the complexity of two modes and risk warnings justifies the detail. Every sentence adds value.

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

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

Given no output schema, the description fully explains return values for both modes, including verdicts, thin legs, and forced_directional_risk. It also covers edge cases (cannot_fill verdict) and risk warnings, making it complete 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?

The input schema has 100% coverage, but the description adds significant meaning: explains mode selection via market vs event, default side logic in basket mode, and interpretation of size_usd (spend vs target proceeds vs settlement notional). This goes well beyond the schema.

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

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

The description states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage by positioning itself as a prerequisite check.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of not using it, such as partial baskets creating unhedged directional positions.

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, so no contradiction. The description adds exceptional behavioral detail: Kalshi fees are not modeled and spreads are gross, pairing is always unverified, compatibility warnings can be non-empty even when matches exist, temporal_alignment null means unknown not aligned, and 'unknown'-type legs are never paired. This goes far 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 long, but the tool is genuinely complex and there is no output schema to carry the burden. It is structurally organized by MODES, RESPONSE, SAFETY FIELDS, and counters. The density is justified, though section breaks or bullets would improve scannability.

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 document return shape and caveats itself, and it does comprehensively: leg-by-leg prices, top_spreads_pp with per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped-category counters. An agent has enough context to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between parameters: `topic` selects a pre-mapped pair, while explicit tickers override each side, and both modes run the identical matcher. It also clarifies the `topic` enum values with practical examples, going beyond the schema's flat string 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 opens with a precise verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It details what is measured (Kalshi minus Polymarket spread in percentage points) and explicitly names the two modes. This clearly differentiates it from the sibling tools focused on single-venue edges or fill risk.

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

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

The description gives strong mode-selection guidance: use the 10 pre-mapped `topic` shortcuts for fast lookups, or supply explicit `kalshi_event_ticker` and `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics are not automatically tradeable. It does not name sibling tools as alternatives, so the 'vs alternatives' aspect is weaker.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the HTTP method (POST), the response format, and the size limitation (10,000 cells). No contradictions with annotations are present.

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

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

Two concise, information-dense sentences. The first sentence front-loads the purpose, and the second provides essential format and constraint details. No extraneous content.

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

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

While the description mentions the response format 'json-stat2' and the size cap, it does not detail the response structure, error states, or the expected behavior for edge cases. For a tool with no output schema and nested parameters, more completeness could be beneficial.

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 detailed example and descriptions for both parameters. The description reiterates the body format and adds the limitation hint, but does not significantly augment the schema's meaning given 100% schema coverage.

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

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

The description clearly states the action: 'POST a PxWeb query to a Kosovo ASKdata table' and specifies the output format 'json-stat2'. It is specific about the resource and verb, and subtly differentiates from sibling 'table_meta' by suggesting its use for narrowing selections.

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 instructions on the required body format and the cap of 10,000 cells are given. It references 'use codes from table_meta' to narrow selections, providing clear context on how to use the tool effectively. However, it does not explicitly state when not to use this tool versus alternatives like 'search_within'.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds transparency about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains behavior when key is omitted (list all keys). 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 of three sentences, front-loaded with the main action. Each sentence adds value: the action, use case, and scoping. No wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers main usage, scoping, and pairing with siblings. It is fully adequate given the tool's complexity and available annotations.

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

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

Schema coverage is 100% with a single 'key' parameter fully described. The description only restates that omitting the key lists all keys, which the schema already conveys. No additional semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' The verb 'retrieve' and resource 'saved values' are specific, and it distinguishes itself from sibling tools like 'remember' and 'forget' by explaining its complementarity.

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 usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget. While it doesn't explicitly state when not to use it, the sibling list includes alternatives, and the description implies its appropriate 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 mark readOnlyHint=true, but description discloses that setting mark_read:true flags events as read, a side-effect. This adds behavioral context beyond annotations, though it may slightly contradict readOnlyHint.

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

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

Four sentences, no fluff, front-loaded with purpose. Efficiently conveys key 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?

Covers return fields, filtering, read state management, and alternative access. No output schema, but description gives enough structure for agent usage. Lacks explicit mention of default limit.

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. Description adds an example for type ('sec_8k') but largely restates schema. Adequate but not significantly additive.

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 pulls fired events from a subscription feed, specifying the verb 'pull' and resource 'fired events'. It distinguishes this from sibling tools like list_subscriptions by focusing on event retrieval.

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 usage context: filtering by type and since, using mark_read to manage read state, and mentions an alternative GET endpoint for scripts/dashboards. Does not explicitly exclude use cases but gives sufficient guidance for typical usage.

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

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

The description goes well beyond annotations by revealing the fan-out to multiple APIs (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews on rate-limit or 5xx), and soft-failure conditions (USPTO API sunset May 2025). It also mentions the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). Annotations already mark it read-only and idempotent, so there is no contradiction.

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

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

The description is a single, well-organized paragraph that front-loads user intent examples and key behavior. It is not overly verbose; every sentence adds meaning. While it could benefit from bullet points for the source fan-out, it remains efficient and readable. The structure is effective for an AI 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 complexity (multiple data sources, fallback logic, window handling, and no output schema), the description comprehensively covers all necessary aspects: what the tool does, its parameters, source behavior, return format, and when to use an alternative. No gaps are apparent, and it fully equips an agent to invoke the tool correctly.

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

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

The input schema already provides 100% description coverage for all 3 parameters. The description adds value by clarifying that 'since' accepts both ISO dates and relative shorthand (with examples like '7d', '30d', '3m', '1y'), and that 'value' can be a ticker or zero-padded CIK. This enriches the schema without redundancy, earning a score above 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 begins with a list of user-intent examples ('What's new with X', 'latest on Y'), precisely stating the tool returns a change feed for a company in a recent window via one parallel call. It explicitly distinguishes from the sibling tool 'entity_profile', which is for static profiles. The verb 'fans out' and the resource 'change feed for a company' are specific and clear.

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

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

The description provides explicit usage guidance: it lists example queries, explains when to use this tool (for recent changes) and when to use the alternative 'entity_profile' (for static profiles regardless of window). It also details the internal sources and fallback behavior, helping the agent decide contextually.

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 (idempotentHint=true, destructiveHint=false), the description adds key behavioral traits: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words, efficient and clear.

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

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

Given no output schema, the description could mention return behavior (e.g., success confirmation), but it adequately covers usage, persistence, and integration with sibling tools. For a simple write operation, it is sufficiently complete.

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

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

Schema coverage is 100% with both parameters described. The description reinforces the key-value pair concept and gives practical examples. It adds value by explaining scope ('scoped by your identifier') and suggesting use cases, going beyond the schema's type definitions.

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 saves data for later reuse, providing specific examples like 'resolved ticker, target address, user preference, research subject'. It distinguishes from sibling tools recall and forget by explicitly mentioning pairing.

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

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

The description explicitly advises when to use (when discovering something worth carrying forward) and mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. This provides clear guidance on tool selection.

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

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

The annotations already mark this as read-only, idempotent, and open-world, and the description adds substantial behavior beyond that: it cascades through multiple lookup endpoints, degrades gracefully when enrichment sources are unavailable, returns candidates instead of asserting when ambiguous, and explicitly reports unresolved identifiers. This is exactly the kind of context annotations cannot capture.

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 most sentences earn their place given the two supported entity types and the many resolution edge cases. It front-loads the core purpose and the 'use FIRST' directive before diving into per-type detail. It could be tightened with bullets, but it is structured and not redundant overall.

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

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

Without an output schema, the description still tells the agent what to expect back: CIK, ticker, company name, LEI, FIGI, RxCUI, ingredient, brand, candidates, and unresolved identifiers. It also covers failure conditions (unavailable enrichment, ambiguous matches) and input requirements. This is sufficient for confident selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the ticker-vs-name lookup behavior, the ISIN-to-LEI path for non-US issuers, and the crucial 'entity name only, not full noun phrase' rule for bonds. This materially reduces the chance of an agent passing a malformed 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 names a specific behavior — resolving a user-spoken name to canonical/official identifiers — and names the concrete resources involved (CIK, ticker, LEI, FIGI, RxCUI). It also distinguishes itself from sibling context (

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

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

It gives a clear trigger: 'Use FIRST whenever you have a name but need an ID.' It also gives usage guidance per entity type and explains when not to assert a single FIGI (when multiple instruments match). However, it never names alternative tools explicitly or gives a 'when NOT to use' condition, so it is short of a full 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it probes multiple entities, uses ai_visibility_check, returns ranked list with score/confidence/signal density, and treats first entity as subject. No contradictions.

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

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

The description is two sentences with a parenthetical, each sentence earning its place. It is front-loaded with purpose, then details the process and use case. No wasted words.

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

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

With 4 parameters, 100% schema coverage, and no output schema, the description adequately explains the return (ranked list with score/confidence/signal density) and special behavior (first entity as subject). Could mention caching or costs, but overall sufficient.

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

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

Schema description coverage is 100%, setting baseline at 3. The description adds meaning by explaining the first entity is 'subject' for narrative and that context disambiguates common names. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using specific verb 'compare' and resource 'AI visibility across entities'. It distinguishes from siblings like ai_visibility_check and compare_entities by stating it probes multiple entities and ranks them.

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use this tool over single-entity checks, though it does not explicitly state when not to use or list 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?

Discloses important behaviors: bundlephobia first measurement may take 5-30s, partial failures degrade gracefully with a 'sources_failed' list. Annotations already declare readOnly, openWorld, idempotent; no contradiction.

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

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

The description is efficient and front-loaded, but slightly dense. Could be split into shorter sentences for easier scanning, but still very 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?

Comprehensively covers input (package name, optional version), behavior (data sources, potential delays, graceful degradation), and output (summary block with specific fields, per-advisory detail, links, alternative versions). No output schema, but return structure is adequately described.

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

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

Schema coverage is 100% for both parameters (package, version). The description adds context beyond schema: mentions scoped packages are accepted and version defaults to latest. This enriches parameter understanding.

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

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

The description explicitly states the tool's composite purpose: 'should I add this npm package to my project' check, covering license, advisories, version history, and bundle statistics. It clearly distinguishes itself from other tools by being a one-call aggregate.

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 ('when an agent asks is X safe / popular / small') and when-not-to-use ('NPM ecosystem only; other ecosystems fall under deps.dev:version directly'). This helps the agent choose correctly among siblings.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds rich implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character limit with truncation flagging. No contradictions.

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

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

The description is a single, well-structured paragraph of about 5 sentences. It front-loads the main purpose and every sentence adds distinct value. 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?

Given three parameters and no output schema, the description covers the algorithm, limits, pairing, and return details (offsets, similarity scores). It is fully self-contained for an agent to decide when and how to use the tool.

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

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

Schema coverage is 100%, providing baseline of 3. The description adds value beyond schema with examples for query, explains the text cap, and details the embedding method and windowing, which are not in the schema.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record' and specifies the use case: when a record is too large for the prompt. It distinguishes from siblings by explicitly mentioning how it pairs with ask_pipeworx_grounded.

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 advises when to use: 'Use when the record is too big to cram into the prompt.' It also describes the output and pairing with another tool. While it doesn't list exact when-not-to-use scenarios, the context is clear.

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds value by detailing return types ('l' and 't' folders/tables) and path behavior, going beyond structured metadata.

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

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

Two sentences, each carrying essential information. No redundant phrasing. Front-loaded with purpose followed by usage instructions.

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 a single parameter, thorough annotations, and no output schema, the description adequately explains input behavior and expected output types. It could elaborate on the exact structure of returned items, but the provided details are sufficient for a browse tool.

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

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

Schema coverage is 100% with a clear description. The description adds context by explaining the default value and providing real-world path examples, which enhances the schema's documentation.

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

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

The description clearly states the tool browses the ASKdata subject tree, specifies default path behavior, and demonstrates drill-down capability. It distinguishes itself from sibling tools by its focus on hierarchical subject navigation.

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

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

Provides clear usage examples (default and deeper paths) but does not explicitly mention when to avoid this tool or suggest alternatives. It gives enough context for appropriate use.

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

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

The description discloses key behaviors beyond annotations: returns new subscription id, requires OAuth, documents delivery constraints (SMS cap, webhook auto-disable, phone verification), and notes that webhook secret is returned once. 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 substantive paragraph that front-loads the purpose. It covers all necessary aspects without redundancy, though it could benefit from bullet points for the type-specific parameters to improve readability.

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 (nested objects, multiple types, delivery options) and absence of an output schema, the description covers the return value, side effects, constraints, and even webhook verification steps. It is highly comprehensive.

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

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

With 100% schema coverage, the description adds significant meaning: explains each subscription type with concrete examples, details delivery channel formats and constraints (phone must be verified, SMS cap, webhook signing secret). This enriches the schema's properties.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream', specifying the verb and resource. It enumerates supported subscription types and delivery channels, and the name 'subscribe' differentiates it from sibling tools like 'list_subscriptions' or 'unsubscribe'.

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

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

The description provides context on when to use each subscription type (e.g., 'sec_8k' for 8-K filings) and prerequisites (Pipeworx OAuth account). It implicitly sets expectations but does not explicitly contrast with alternatives like 'unsubscribe' or 'list_subscriptions'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds detail that it returns example questions with exact tool+argument shapes from the live catalog, which is useful 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 relatively long but well-structured: starts with common user phrasings, then defines purpose, output, and usage options. Every sentence adds value for the agent, though it could be slightly more concise.

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

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

Given the tool's role as an onboarding entry point, the description fully covers when to use it, what it returns (category-bucketed examples with tool/argument details), and how to focus it. No output schema is needed as the description explains the output nature.

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

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

Schema coverage is 100% with one parameter. The description explains the topic parameter's possible values (finance, pharma, etc.) and the behavior when omitted (full cross-category spread), 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 it is the onboarding entry point for a new agent, returns category-bucketed example questions, and can be focused by topic. It distinguishes itself from siblings by instructing to use this tool first when unsure what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternative phrasings for what users might type. It also explains the effect of the optional topic parameter and omitting 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 indicate read-only, idempotent, non-destructive behavior. The description adds that it returns dimensions and value lists, providing output context beyond annotations. No contradiction.

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

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

Two concise sentences: the first states the core function, the second specifies path format and output purpose. No unnecessary words.

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

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

Given a single parameter and no output schema, the description sufficiently explains what the tool does, what it returns, and how to use the parameter. It is complete for the agent to understand and invoke the tool.

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

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

Schema coverage is high (100%), but the schema description only gives an example. The tool description adds the crucial constraint that the path must end in '.px' and be the full path, which the schema lacks, thus adding meaning.

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 fetches dimension definitions and valid coded values for a specific type of table (Kosovo ASKdata PxWeb), using a specific verb and resource. It distinguishes itself from sibling tool 'query_table' by focusing on metadata retrieval.

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

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

The description provides explicit guidance on when to use the tool: before building a query_table body, as it returns required data. It also specifies path format requirements, helping the agent avoid errors.

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 idempotent and non-destructive. Description adds ownership enforcement and deactivation semantics, providing value beyond annotations.

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

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

Two concise sentences with no wasted words. The action and key constraints are front-loaded.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership, side effects (deactivation), and data retention, making it complete.

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

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

Schema coverage is 100% and parameter 'id' is described in schema. Description does not add further meaning beyond the schema, meeting baseline.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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?

Ownership enforcement ('you can only cancel your own subscriptions') and behavioral outcome (deactivation vs deletion) are explained. Missing explicit when-not-to-use, but context is sufficient.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description adds highly important behavioral detail: the meaning and non-evidentiary nature of 'could_not_verify' (with an explicit warning not to treat it as evidence), the 'unsupported' outcome, the return of a verdict with citation, and the automatic routing to structured vs. grounded pipelines. It also warns about a specific failure mode (verification_error), which is exactly the kind of context an agent needs.

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 long, but it is well-structured: trigger phrases first, then purpose, usage, routing, return values, critical caveats, and finally the efficiency gain. Each sentence adds value, and the 'IMPORTANT for callers' section is necessary. It could be slightly more concise (e.g., trimming the seven trigger phrases), but it remains focused and front-loaded.

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

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

There is no output schema, so the description carries the full burden of explaining what the tool returns. It lists all verdict types, the citation mechanism, the 'could_not_verify' error structure, and the 'unsupported' meaning. Combined with the rich annotations, this gives an agent everything needed to interpret results correctly, including edge cases. The description is exceptionally 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?

The schema already describes both parameters ('claim' and 'tolerance_pct') with 100% coverage, which sets a baseline of 3. The description adds meaningful context beyond the schema by mentioning 'exact percent-delta math', the default tolerance cap of 5, and the use of tolerance for hallucination detection (set 1–2). This enriches an agent's understanding of how to set the parameters.

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

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

The description opens with multiple natural-language trigger phrases ('fact check', 'verify the claim', 'confirm or refute') and immediately states the core function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by specifying the two internal pathways (structured SEC EDGAR for company-financial claims, grounded pipeline for all else) and notes it replaces several sequential steps. This is a specific verb+resource+scope with strong differentiation.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also explains the two routing branches based on claim type. However, it does not explicitly name sibling tools as alternatives or state when NOT to use this tool (e.g., when the user just wants general information rather than a verdict), leaving some ambiguity against tools like ask_pipeworx_grounded or deep_research.

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