fda

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

Given the annotations already declare read-only and idempotent behavior, the description adds valuable context: default model is free, passing `_apiKey` enables Anthropic with direct payment, and the response includes per-model fields. This goes beyond the annotations, though it does not disclose potential errors or rate limits.

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

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

The description is compact and front-loaded with the primary action and output, followed by key details (default model, API key entry, return format) and use cases. Every sentence earns its place, with no redundancy or fluff.

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

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

The description provides a good overview of the return shape (per-model {score, confidence, signals, raw_response} + combined view) and practical use cases, compensating for the lack of an output schema. It does not explain what 'signals' or 'confidence' entail, but for a read-only probe tool this is adequate and mostly complete.

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

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

The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description reinforces the default for `models` and the purpose of `_apiKey`, but adds no additional parameter semantics beyond what the schema already explains.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource combination, and the scoring output distinguishes it from general-purpose query tools like ask_pipeworx.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context on when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond that: it reveals the tool's routing behavior across 5,566 tools, argument-filling mechanism, source count, and the pipeworx:// citation URI output. No contradiction with annotations; it only lacks explicit limits or failure 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 front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and uses focused examples. It is lengthy but every section adds actionable guidance—coverage scope, usage triggers, examples, alternatives, and tier availability. It stops just short of maximum elegance because some phrasing 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 general-purpose router with no output schema, this description is complete: it defines the coverage, how to ask, what it returns, how citations work, when to escalate to siblings, and that it works on every tier. This is sufficient for an agent to both select and invoke the tool correctly.

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

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

The input schema covers 100% of parameters, including aliases and a natural-language description of the required 'question' parameter. The description adds that the question is handled in natural language and that the tool fills arguments internally, but it doesn't go deeper than the schema already does. Baseline 3 is appropriate because no parameter-level burden remains.

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: route a natural-language question to 5,566 tools across verified sources and return a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from ask_pipeworx_grounded and deep_research, making its niche 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?

It gives explicit when-to-use guidance: prefer over web search for factual/current questions, use for 'what is', 'look up', 'find', 'get the latest', and other fact-finding phrasings. It also names the alternatives ask_pipeworx_grounded and deep_research for grounded or multi-part questions, and says 'START HERE' on every tier.

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 convey read-only/idempotent/non-destructive. The description adds genuine value by disclosing the experimental state ('no candidate is active right now... currently matches ask_pipeworx exactly'), the background comparison behavior, and the fact that results feed into merge decisions. It gives complete transparency about side effects (non-destructive, read-only). Loses a point only because the core read-only guarantees are already in the annotations, and it could have added a bit more color on response-shape edge 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?

Every sentence serves a distinct purpose: identity, current state, usage context, and call-to-action. The information is front-loaded with the most critical fact ('Beta version of ask_pipeworx... identical universal router') first. It is word-heavy for a tool description and could theoretically be trimmed, but each clause earns its place—especially the explicit note that no candidate is currently active.

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

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

For a beta tool with experimental routing logic, the description is remarkably complete: it covers state (no candidate active, last retired date), identity (matches ask_pipeworx), usage (use exactly like stable), and lifecycle (results compared to stable to decide merges). An output schema wasn't provided, but the description clarifies the response shape is identical to the sibling tool. The only minor gap is a hint on what the agent should observe in the response if a routing experiment is active, though this is a minor nicety.

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

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

Input-schema description coverage is 100%: the 'question' parameter and all five aliases (q, text, input, query, prompt) are documented in the schema itself, so the description doesn't need to re-explain them. The description complements this by pointing to the sibling tool ('same arguments'), which reinforces semantics. Given full schema coverage, the baseline of 3 is appropriate; the description correctly avoids redundancy.

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 construct ('Beta version of ask_pipeworx: identical universal router') and clearly distinguishes itself from siblings by defining its experimental role ('candidate routing improvements enabled live'), its response shape, and its current functional equivalence to ask_pipeworx. It is entirely clear what this tool does: it routes a natural-language question to one of 5,566 tools, with an experimental routing edge.

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

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

Explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' directly names the stable sibling as the alternative and contrasts its purpose ('results are compared against the stable router to decide what merges'). It also clarifies it's not a fallback/'just a stub' but a full working router, preempting misuse. This explicitly answers when to use this tool vs. the stable sibling.

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

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

Annotations already establish readOnly/idempotent safety, and the description adds valuable behavioral detail: refusal_reason vocabulary, evidence as verbatim quote, source/fetched_at fields, data truncation handling, and the extra LLM-call cost. It also explains that refusals happen when the data doesn't directly answer the question.

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 opening sentence front-loads the core purpose, and each subsequent sentence earns its place: routing behavior, extraction guarantee, success/refusal outputs, concrete use cases, and the cost tradeoff. It is information-dense without being bloated.

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

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

The description is self-sufficient despite the absence of an output schema, because it defines both the success payload and refusal payload. It also contextualizes the tool against ask_pipeworx and provides explicit high-stakes scenarios, making the tool fully actionable.

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

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

Schema description coverage is 100%, with all six properties documenting the same natural-language question via aliases. The description does not add parameter-level meaning beyond the schema, but the schema already handles semantics fully, so 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 is specific and immediately distinguishes this tool: it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts itself with ask_pipeworx by extracting answers using only the tool result. This gives the agent a clear, differentiated 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 this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of an extra LLM call. This is ideal alternative-selection 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?

Despite annotations already declaring readOnly/idempotent/destructive traits, the description adds substantial behavioral depth: low-confidence short-circuiting with status fields, closed/dead market handling, illiquid wide-spread tagging, cancellation-rule parsing, news fallback fields (_fallback_attempted, retry_after_sec), and the 24h-move warning. This is exactly the kind of context that annotations cannot 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 meticulously structured with bolded section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), front-loaded with the core one-liner, and every section conveys actionable operational detail. The length is justified by the tool's complexity; there is zero filler or repetition.

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 compensates thoroughly by documenting response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extractor, news fallback fields, safety statuses, and cancellation-rule semantics. It covers input, output, edge cases, and risk warnings, making it fully self-contained 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?

Even though schema description coverage is 100%, the description enriches each parameter meaningfully: market input normalization (slug/URL/question), depth enum semantics ('quick = 2-3 evidence sources, thorough = full fan-out'), and include_raw size consequences (~20KB vs 50-500KB). This goes far beyond the schema's field descriptions, adding real operational insight.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet...'), clearly enumerates accepted input formats (slug, URL, question text), and explains the full transformation pipeline (resolve, classify, fan out, compare). This distinctly positions it against siblings like validate_claim or polymarket_arbitrage by focusing on evidence-gathering for a single market.

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

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

The description provides explicit use cases ('Use for should I bet on X, what does the data say about Y, or is there edge in Z') and detailed fan-out examples per category, which gives strong contextual guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of the 'when-not/alternatives' bar for a 5.

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

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

Annotations include readOnlyHint and idempotentHint, and the description goes further by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations; openWorldHint aligns with the dynamic data pulls.

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

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

The description is longer than a few sentences but every clause earns its place—trigger phrases, type-specific data, sorting, and the 'replaces sequential lookups' benefit. The structure with quoted examples and type sections keeps it scannable despite its length.

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

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

With no output schema, the description clearly states what is returned (paired data + citation URIs), explains sorting behavior, covers data sources, and gives explicit comparison intent. This is sufficient for a tool of this complexity and parameter count.

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 covers both parameters fully (type enum, values array constraints), so the baseline is 3. The description mostly adds behavioral context (what data each type fetches) rather than new semantic detail about the parameters themselves, so a 3 is appropriate.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single call, with explicit trigger phrases like 'compare X and Y' and 'rank these companies'. It distinguishes itself from sibling single-entity lookups and entity_profile by emphasizing the comparative, parallel nature.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also enumerates concrete user intents and differentiates behavior by type (company vs. drug), providing clear context for when this tool should be invoked over alternatives.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds rich operational context: account requirements, latency ('15-60s... up to ~90s'), the never-invented guarantee for gaps[], fetchable pipeworx:// citation_uris, semantic (non-head-truncated) excerpting, and hop semantics. No contradiction with annotations exists; the description enhances an already well-annotated tool.

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

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

The text is information-dense with no fluff, but it's a single unbroken ~400-word paragraph that duplicates some depth-parameter details already in the schema (facets, hops, contradiction scans). While the high-priority gating info (account required) is front-loaded, the wall-of-text structure and redundancy with the schema undermine what could otherwise be a more digestible description.

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

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

Despite having no output schema, the description thoroughly specifies the return contract: findings packet fields (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps[] behavior, contradictions[] for standard/thorough, and the failure mode for out-of-catalog topics. It also covers auth, latency, pagination-of-research-behavior, and second-hop iteration, leaving little for an agent to guess at.

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 detailed `depth` enum already documenting facets, hops, and contradictions, so the baseline is 3. The description adds incremental value by tying each depth level to operational meaning — latency expectations and the paid-account gate on 'thorough' — plus clarifying that multi-part questions are welcome ('decomposition is the point').

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

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

The description states the purpose with a specific verb and resource: "Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call." It explicitly differentiates from siblings via 'this is NOT open-web search' and positions itself for 'broad/multi-part questions over structured data,' which clearly distinguishes it from the ask_pipeworx family.

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/when-not guidance with named alternatives: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also warns that the tool 'returns mostly empty gaps[] when the topic isn't in the structured catalog,' which directly prevents misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by detailing the return payload: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'ready to call directly, no second schema lookup needed.' 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, with the first sentence front-loading the purpose. The second sentence is a long enumeration of domains, but every item adds context for query formulation. The final sentence explains the return format and workflow advantage. No filler or redundancy—it earns its length.

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

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

The tool is simple (one required param, no output schema) but the description explains its purpose, when to use it, and exactly what it returns, including that results are directly callable. This is sufficient for an agent to select and invoke it correctly. It does not cover edge cases like pagination or errors, but those are not critical for a discovery 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% (6/6 params documented with aliases). The description adds semantic value by giving concrete examples of query domains ('analyze housing market trends', 'look up FDA drug approvals' in the schema) and a broad list of supported data areas, helping the agent form effective queries. This exceeds the baseline of 3 for well-covered schemas.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It immediately distinguishes discover_tools from siblings by framing it as a discovery/meta-tool, reinforced by 'Call this FIRST when you have many tools available.' The extensive list of data domains (SEC filings, FDA drugs, etc.) further clarifies scope.

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

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

It provides clear when-to-use context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use it via 'not just one answer' (i.e., when you need a specific answer), but it does not name explicit alternatives, so it stops short of a full when/when-not/alternatives specification.

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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds significant behavioral context: it fans out across multiple sources, returns up to 5 filings with URIs, sorts fundamentals by period_end DESC, discloses the USPTO API sunset soft-fail, and mentions the GDELT→GNews fallback. This goes well beyond basic safety and explains operational 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?

Though longer than two sentences, every clause earns its place: user intents, preference guidance, source fan-out, detailed return fields, and parameter constraints. The structure is front-loaded with purpose and flows logically to usage constraints, with no filler.

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

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

With no output schema and no existing return documentation, the description fully explains the response scope: CIK, company name, recent filings with URIs, fundamentals, patents, news, and LEI. It also covers edge cases (patent API sunset, name input unsupported, fallback mechanisms) and references resolve_entity, making it complete for this complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats parameter information already in the schema (ticker/CIK, names not supported, use resolve_entity first) but adds no new semantics or syntax details beyond what the schema provides.

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

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

Description clearly states it generates a 'full cross-source profile of a US public company' with specific output fields, distinguishing it from sibling tools like resolve_entity (names not supported) and single-pack lookups. The verb 'profile' plus resource 'US public company' is specific, and the 'ALWAYS PREFER' note further clarifies its unique role.

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 this tool ('Tell me about X', 'research Acme', 'holistic view') and provides a direct alternative: 'use resolve_entity first if you only have a name'. It also instructs to prefer this over chaining single-pack lookups, giving clear context and exclusions.

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

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

The annotations already declare destructiveHint: true and idempotentHint: true. The description adds context that the memory was 'previously stored' and that it is cleared by key, which helps the agent understand exactly what will be removed. It also suggests use for 'sensitive data,' adding a privacy rationale.

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 long, front-loads the core action, and provides usage guidance without verbosity. Every sentence adds value.

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

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

For a simple one-parameter destructive tool with annotations covering destructiveness and idempotence, the description sufficiently covers what, when, and how. It does not detail return values or error behavior, but no output schema exists and the simplicity of the operation makes this acceptable.

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

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

The input schema has 100% coverage, with a single 'key' parameter described as 'Memory key to delete.' The description restates 'by key' but adds no new semantic detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Delete a previously stored memory by key,' which clearly specifies the verb (delete), the resource (memory), and the mechanism (by key). It distinguishes itself from sibling tools remember and recall by explicitly stating the deletion operation.

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 conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools: 'Pair with remember and recall,' which gives the agent clear guidance on when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds behavioral details: it fetches the page, extracts title/description/key links, and emits a single text blob. This explains the tool's operational behavior and output format 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 four sentences, front-loaded with the primary purpose, and every sentence provides useful info (behavior, output format, use cases). No fluff or redundancy.

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

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

Given the tool's simplicity (1 required param, no output schema), the description fully covers functionality, return format ('single text blob ready to drop at site-root/llms.txt'), and use cases. Nothing important is missing.

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

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

The schema already provides full descriptions for both parameters (url, max_links) with 100% coverage. The description does not add significant parameter semantics beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' and details the process of fetching, extracting, and emitting the standard llms.txt markdown format. This specific verb+resource+output distinguishes it from sibling 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?

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This offers clear context for when to use the tool, though it doesn't mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this by specifying the scope ('caller's active subscriptions') and listing exact return fields, which clarifies that only active subscriptions are returned and what data will be present. This exceeds the baseline set 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 two sentences with no filler. The first sentence names the action and output fields; the second provides actionable usage guidance. Every sentence earns its place, and the key information is front-loaded.

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

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

This is a simple read-only list tool with one optional, well-documented parameter. The description lists the return fields, compensating for the lack of an output schema. It also covers purpose and usage, making it sufficiently complete for an agent to select and invoke correctly.

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

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

The input schema has one optional parameter (include_inactive) with a clear description, providing 100% schema coverage. The tool description itself does not add semantic detail about the parameter beyond what the schema already states, so it stays at the baseline 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 the verb ('List') and resource ('the caller's active subscriptions'), and it specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It also differentiates this read tool from siblings by noting its use for reviewing current monitoring and finding an ID to cancel, distinguishing it from subscribe/unsubscribe.

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

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

The description explicitly gives usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call this tool (before subscribe/unsubscribe actions) and implies the relevant alternatives, aligning with sibling tools like subscribe and unsubscribe.

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

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

Annotations are all false, so they declare nothing specific; the description adds substantial behavioral context: filing returns a claim_token, passing the token later reads resolution status, rate limit (5/day), and quota-free status. It doesn't go into detail on what the feedback submission does server-side, but the added operational traits go beyond annotations.

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

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

The description is long but dense, front-loaded with purpose and followed by actionable sections. Every sentence earns its place: usage triggers, scope boundary, content guidance, token mechanics, and rate limits. It could be tightened but the structure makes it scannable and the length is justified by the tool's nuanced behavior.

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, the description covers what the tool does, when to use it, how to use the token to retrieve resolution, what content to include/exclude, and rate limits. No output schema exists, but the description explains the key return artifact (claim_token) and how to use it, making the tool's contract sufficiently 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 each parameter is already well-described. The description adds meaning by explaining the claim_token workflow (filing without an account returns a token; passing it later with no other args reads the outcome), and gives content guidance like 'don't paste the end-user's prompt' and 'describe in terms of Pipeworx tools/packs', 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 opens with a specific verb phrase ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx tools served by this connection). It distinguishes itself from siblings like ask_pipeworx by focusing on feedback about tool behavior and catalog gaps, not on answering questions.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise), explicit when-not-to-use (feedback for other MCP servers should be filed elsewhere), and even guidance on uncertainty ('Pipeworx tool names are the ones this connection lists'). It names the alternative behavior clearly, satisfying the when/not/alternatives requirement.

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 beyond the annotations by disclosing cache behavior ('Cached 5min-1h depending on window'), data origin ('derived from CF analytics-engine'), privacy ('no PII'), and the response shape ('just (pack, tool, count)'). This adds significant behavioral context not present in the readOnlyHint/idempotentHint 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 concise yet informative, front-loading the core function, then providing numbered use cases, and finishing with transparency details. Each sentence adds value; no filler or redundancy.

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

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

Despite lacking an output schema, the description clearly explains what is returned (top tools, top packs, call volume, and the (pack, tool, count) tuple). It also covers caching, privacy, and the meaning of windows. For a simple read-only tool with one optional parameter, this is fully complete.

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

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

Schema coverage is 100% and the parameter 'window' already includes a thorough description ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now...'). The tool description repeats this information without adding new syntax or additional meaning, so it meets the baseline for high schema coverage but does not exceed it.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource ('Pipeworx trending data') and distinguishes itself from siblings by focusing on aggregate agent call signals. The use cases further clarify its unique value.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. It also explains window selection (shorter for hot right now, longer for steady-state). However, it does not mention alternative tools or explicitly state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds rich operational context: it details what happens in fill checks, how thin legs are reported, that placeholders are filtered, that skipped_low_similarity surfaces rejected pair counts, and warns against trading last-trade-only edges. It even explains why realizable edge can be lower than theoretical edge. No contradictions.

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

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

The description is long but every sentence justifies its presence given the tool's complexity. It is not a wall of filler; it front-loads purpose and modes, then layers on filters, response fields, and fill-check caveats in a logical order. Slightly dense, but earned length.

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

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

With no output schema, the description must explain return values—it does: opportunities[] fields, partition_check object, fill_check behavior. It covers edge cases (placeholder slugs, low similarity, thin legs), mode differences, and refers to an alternative tool for sizing. Given the domain complexity, this is remarkably 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 both event and topic have their own descriptions, but the tool description goes far beyond by explaining mode semantics, providing concrete slug/seed examples, and clarifying nuanced behaviors like event mode walking child markets versus topic mode flattening related events. This substantially enriches parameter 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by naming distinct modes (trending_scan, event, topic) and explicitly pointing to polymarket_fill_risk for custom sizing, so it is unambiguous.

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

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

Usage guidance is explicit and well-structured: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)', and 'For custom sizing use polymarket_fill_risk.' It also tells when not to trade (realizable_edge_pp <= 0), providing both when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses extensive behavioral traits: caching at KV level keyed on knobs, model family gates, segment-specific filters, diagnostics for empty segments, and the 24h-move warning. It explains why Fed bets are excluded and how tradeable-edge knobs affect results. 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?

Though lengthy, the description is densely informative and well-structured: purpose, model families, response structure, knobs, diagnostics, caching. Every section adds value with no fluff. It front-loads the core purpose and then logically organizes the technical details, making the size appropriate for the tool's complexity.

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

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

Without an output schema, the description fully explains the return structure: by_segment with three model families, per-opportunity fields (edge_pp_net, kelly_fraction, etc.), top-level diagnostics (fed_candidates, _diagnostics), and the meaning of empty segments. It covers response shape, filters, and niche behaviors, making it complete for an agent to call and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant context beyond the schema by explaining the interplay of knobs (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and how min_partition_leg_kelly applies to per-leg Kelly inside top_legs. This enriches parameter understanding, earning a 4.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes the tool's purpose from siblings by stating it's built for 'what should I bet on today' and discovering opportunities without paging hundreds of markets, which differentiates it from other Polymarket tools like arbitrage or edge tracking.

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 context: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also hints at when not to rely on certain segments (Fed bets unreliable, concentrated longshot rare-by-design) but does not explicitly name alternative tools or when-not-to-use scenarios. Thus it is clear context but lacks explicit exclusions/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 goes beyond the readOnlyHint/idempotentHint annotations by disclosing the 60-day snapshot TTL, snapshot gaps on cache-miss, and that decay is computed from daily closes rather than intraday data. This provides realistic expectations about data limitations and quirks.

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

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

The description is longer than typical, but it's structured with Args, RESPONSE, and LIMITS sections, and every detail (response shape, TTL, gap semantics) is relevant for a tool with no output schema. It's front-loaded with purpose, and the length is justified by complexity.

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

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

It fully explains the return object even without an output schema, including tracked[], expired[], and snapshot_dates[], plus the meaning of trend and decay. It also covers history limits and the snapshot-writing mechanism, making it a self-contained and complete description.

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

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

The schema already thoroughly describes both parameters (lookback days with clamp, window family with enum). The description repeats defaults and the 'snapshot family' concept but doesn't add meaningful new semantic detail. Schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, and frames it as answering whether an edge is new or shrinking. This is distinct from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage, so the purpose is unambiguous.

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

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

It gives strong context: it emphasizes the difference between a fresh wide edge and an old one, implying usage for assessing edge durability before trading. It doesn't explicitly name alternatives, but the distinction from current-edge tools is evident, making it a clear 4 rather than a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive hints, but the description adds valuable behavioral context: it walks the CLOB ladder, interprets size_usd differently for buys vs sells, and warns that partial basket fills convert an arb into an unhedged directional position (the dominant loss mode). This goes far beyond the structured annotations.

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

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

The description is lengthy (nearly 200 words), but it is information-dense and well-structured, starting with the core purpose and then logically branching into single-market vs basket modes, return values, and usage guidance. Every sentence adds operational value, though a slight trim would improve scannability; the length is justified by tool complexity.

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

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

Given no output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers prerequisites (requires market or event), parameter defaults, and risk warnings, making it self-contained for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but the description enriches parameters significantly: explains 'market' vs 'event' modes, details side defaults (including auto-detect in basket mode), and elaborates on size_usd semantics (max spend on buys, target proceeds on sells, settlement notional in baskets). This adds meaning well beyond the schema descriptions.

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

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

The description states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges and specifying 'USE THIS before acting on' their signals, which sets it apart as the execution-risk validation tool.

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

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

Explicitly states when to use: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also defines two modes (single-market vs basket) and provides clear context for when each applies, plus notes the danger of partial fills, effectively guiding tool selection via exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it explains the exact conditions for compatibility_warning, the meaning of temporal_alignment, and the nuance that pre-mapped topics often return warnings. This exceeds annotation coverage and is very transparent.

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

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

The description is dense and lengthy, with many embedded caveats, examples, and safety-field explanations. While each piece adds some value, it could be restructured with bullet points or shorter sentences for easier machine parsing. It is front-loaded with the core purpose but is somewhat overlong for a quick selection task.

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

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

There is no output schema, so the description must explain return values. It does so by detailing leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and skip counters. It also covers all parameter combinations and override behavior. The only ambiguity is whether at least one mode is required, but examples make typical usage clear enough.

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% (all three parameters have descriptions), so the baseline is 3. The description adds semantic value by explaining the two modes and how explicit parameters override topic-mapped sides. It also clarifies that topic shortcuts may not yield matches, which is not fully evident from the schema alone.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly explains two modes (topic shortcuts vs explicit pairings), and the level of detail distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description clearly explains when to use topic shortcuts vs explicit pairings, and warns that pre-mapped topics are often not tradeable. It doesn't explicitly name alternatives or state conditions to avoid the tool, but it gives clear context for correct usage and sets expectations about compatibility_warning.

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, and destructiveHint=false, covering safety. The description adds useful behavioral context beyond annotations: it notes the scoping to an identifier and that omitting the key returns all keys. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: the first sentence defines behavior, the second gives usage examples, the third covers scope and companion tools. 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?

For a single-optional-parameter read-only tool with strong annotations and no output schema, the description is complete: it explains both use cases (retrieve by key, list all), scope, and relationships to related tools. The agent has enough context to invoke it correctly without further elaboration.

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 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this and adds practical context by giving examples of what keys might contain (user's target ticker, address, research notes), which helps the agent generate appropriate keys. This adds 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 function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies a distinct resource (the agent's saved memory store) and differentiates from siblings by explicitly mentioning the pairing with 'remember' and 'forget'.

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

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

The description provides explicit usage guidance: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also clarifies the scope (anonymous IP, BYO key hash, or account ID) and how to list all keys, effectively distinguishing it from other operations.

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 important behavioral traits beyond the annotations: mark_read changes read state, return payload shape (source, citation_uri, raw payload), and polling suitability. It also notes the external feed location. Since annotations already declare readOnlyHint true, the description adds valuable nuance about the read-flag side-effect without contradicting the hint.

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 primary action and is about five sentences long, with every sentence contributing meaningful information: purpose, return payload, filtering, mark_read side-effect, and alternative endpoint. No fluff or redundancy.

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

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

Given no output schema, the description adequately explains return values, filters, side-effects, and even provides an alternative access method. It is complete enough for an agent to understand the tool's behavior, polling implications, and integration points. Minor details like pagination or error handling are not essential for this level of complexity.

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

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

Schema coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds extra meaning by giving a concrete type example ('sec_8k'), explaining since as an ISO timestamp, and detailing how mark_read affects subsequent calls. It doesn't cover limit or unread_only, but those are well-described 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 opens with a specific verb-resource pairing: 'Pull fired events from your subscription feed.' It clearly identifies the tool's scope and distinguishes it from sibling tools like list_subscriptions or recent_changes by focusing on alerts from the subscription feed.

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

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

The description provides clear context for use: retrieving recent alerts, polling, and filtering. It also offers an explicit alternative (the registry URL for scripts/dashboards), but it does not explicitly compare to other sibling tools or state when not to use this tool, so it stops short of full explicitness.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals material behaviors: fan-out to multiple sources, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to PatentsView API sunset, and the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). This significantly exceeds the annotation-provided safety profile.

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

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

The description is a single dense paragraph, front-loaded with user-facing query examples, followed by technical details. Every clause earns its place: source enumeration, fallback logic, parameter format, return shape, and sibling tool contrast. No filler or redundancy.

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

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

Given the tool's complexity (multi-source fan-out, fallbacks, soft-fail, no output schema), the description is thorough. It covers input formats, source behavior, failure modes, and the output structure (changes[] grouped by source + total_changes + citation URIs). The explicit contrast with entity_profile provides cross-tool context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: `since` accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. `value` is clarified as ticker or zero-padded CIK with examples. This enriches the schema 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's function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It enumerates specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling tool entity_profile with explicit guidance. This is a specific verb+resource+scope construction.

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 natural language trigger examples ('What's new with X', 'latest on Y') and explicitly states when to use an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives clear usage context and an exclusion.

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, the description discloses significant behavioral details: memory is scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. This is valuable contextual information not present in the annotations or schema.

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

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

The description is concise, front-loaded with the core action, and every sentence earns its place. It avoids redundancy and is appropriately sized for the tool's simplicity.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage timing, persistence behavior, and related tools. It is complete and gives the agent all necessary context to invoke it correctly.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description reinforces the key-value nature and offers examples of values, but does not add meaning beyond the schema. It meets the baseline for well-covered schema.

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

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

The description explicitly states the tool's action ('Save data the agent will need to reuse later') with specific resource (key-value store) and distinguishes it from sibling tools like recall and forget. It also provides concrete examples of what to store, 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 provides clear usage context ('Use when you discover something worth carrying forward') and explicitly mentions companion tools recall and forget. It lacks explicit when-not-to-use guidance, but the context is sufficiently clear for an agent to decide when to use this tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: it cascades through multiple lookup endpoints, replaces 2-3 manual lookups, degrades gracefully (LEI/FIGI enrichment may fail but EDGAR identifiers still return), and explicitly states that unresolved identifiers are listed under 'unresolved' rather than omitted. 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 thorough but somewhat lengthy. It is front-loaded with example queries and the key usage statement ('Use FIRST'), which is good. However, it could be trimmed slightly without losing essential details. The structure is logical (examples, supported types, behavioral notes), earning a high-but-not-perfect score.

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 return values. It does so comprehensively: for each entity type, it specifies the identifiers returned, their sources, and the explicit 'unresolved' field. It also covers edge cases like ISIN-to-LEI mapping and graceful degradation. Given the tool's complexity, the description is remarkably 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 the description adds substantial meaning beyond the schema. For 'type', it explains the entity types and what identifiers each resolves to (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand). For 'value', it gives concrete input examples (ticker, CIK, ISIN, name, brand/generic) and explains how inputs like ISIN resolve. This makes parameter usage very clear.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers. It gives concrete example queries like 'What's the ticker for…' and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools (e.g., compare_entities, entity_profile) which operate on already-resolved entities.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It details the two supported types ('company' and 'drug') and what identifiers they return. It also implicitly advises not to use this tool when you already have the required ID, as other tools would be more appropriate. The coverage of when/why to use is thorough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the bar for additional disclosure is lower. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, and returns a ranked list with score, confidence, and signal density. No contradictions found; the description complements annotations.

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

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

The description is three sentences, front-loads the core action, and every sentence earns its place: purpose, mechanism/usage context, and output shape. No filler or redundancy. It is highly scannable 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?

With no output schema, the description compensates by specifying the return value: 'ranked list with score, confidence, signal density per entity.' Combined with the 100% parameter schema coverage and clear annotations, this covers the essential context. It lacks minor caveats like rate limits or failure modes, but for a non-destructive read tool of this complexity, 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?

The schema already provides 100% coverage with meaningful descriptions for all four parameters, including the special role of the first entity and the optional nature of models/_apiKey/context. The description reiterates that entities include brand + competitors but doesn't add new parameter-level semantics beyond what the schema states. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly states a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It explicitly distinguishes itself from the sibling ai_visibility_check by describing multi-entity comparison and ranking, and references the underlying probe method. The competitive-audit use case further clarifies its unique 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 gives a clear usage context: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies this tool is for comparing multiple entities rather than checking a single one, but it does not explicitly contrast with alternatives like compare_entities. The mention of ai_visibility_check as the underlying probe provides a hint of when to use this aggregate wrapper.

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 the description adds valuable behavioral context: composite fan-out, graceful degradation, partial failure reporting, and a 5-30s first-measurement timeout for bundlephobia. This goes well beyond the annotations and helps the agent anticipate delayed responses.

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

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

The description is information-dense but every sentence earns its place: purpose, usage, return fields, limitations, performance, and failure behavior. It's slightly long but well-structured with dashes and semicolons, front-loaded with the main purpose. Not a perfect 5 because it could be tightened slightly, but very efficient.

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

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

Despite no output schema, the description enumerates all return fields (summary block, per-advisory detail, links, recent alternative versions), explains limitations (NPM-only, partial failures), and clarifies performance expectations. This provides enough context for an agent to invoke the tool and interpret results confidently.

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% for both parameters. The description adds only marginal detail (e.g., 'scoped packages accepted' is in schema, version defaults are in schema). The description does not provide additional parameter semantics beyond what the schema already covers, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: a composite npm package evaluation check that fans out to deps.dev and bundlephobia. It uses a specific verb ('check') and resource ('npm package'), and the phrase 'should I add this npm package to my project' uniquely defines its niche among siblings.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions, noting NPM ecosystem only in v1 and redirects other ecosystems to deps.dev:version directly.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial context beyond that: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-character overlapping windows, and enforces a 200K character cap with truncation flag. No contradiction with annotations.

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

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

Five dense sentences, each earning its place: what the tool does, when to use it, how it pairs with a sibling, and key technical details. Front-loaded with the core action and no filler or redundancy.

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

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

The description covers the complete workflow: inputs, output format, usage trigger, integration with ask_pipeworx_grounded, and technical constraints. Despite the absence of an output schema, the return structure (passages with offsets and scores) is described well enough for an agent to invoke the tool and interpret results.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds valuable context for 'text' (e.g., 'text you already pulled') and provides query examples, but these are enhancements rather than new parameter semantics. It earns a 4 for practical framing that helps agents understand how to populate the parameters 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 description opens with 'Semantic search INSIDE a fetched record,' immediately conveying the tool's core function with a specific verb and resource. It clearly states inputs (text plus natural-language query) and outputs (top-N passages with character offsets and similarity scores), and distinguishes itself from siblings like ask_pipeworx_grounded by focusing on searching within already-fetched content.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a complementary sibling, ask_pipeworx_grounded, and explains the pairing: fetch with the gateway, then ground over relevant passages. This gives clear guidance on both when and how it fits into a broader workflow.

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 operational behaviors not covered by annotations: OAuth requirement for persistence, SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 failing runs. This goes well beyond the basic readOnly/destructive hints.

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

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

The description is dense but well-organized, leading with the core purpose and then detailing types and delivery. While long, it is a single paragraph that packs in necessary examples and constraints without unnecessary 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 the tool has 3 params with nested objects and no output schema, the description is remarkably complete. It covers all subscription types, delivery channels, auth prerequisites, return value, and operational limits, leaving no critical gaps for an agent to invoke it correctly.

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

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

The schema already covers all parameters with 100% coverage, but the description adds semantic value by explaining examples like items:['5.02'] = officer change and topic:'fed' for polymarket edges, enriching the schema's 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 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource. It also mentions the returned subscription id, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context on who can use it (requires OAuth account) and the exact subscription types and delivery options. It doesn't explicitly say 'use this instead of list or unsubscribe,' but the creation role is obvious from the name and description.

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 readOnly/idempotent safety, so the description adds value by disclosing it draws from the live catalog, returns category-bucketed examples, and supports optional topic focusing. No contradictions.

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

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

The description is long but every segment contributes—examples, usage guidance, and parameter semantics. It front-loads trigger phrases and ends with actionable 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?

The tool is simple with no output schema, yet the description fully explains when to use it, how to call it, and what to expect, making it self-contained for an onboarding tool.

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

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

Schema covers the topic parameter fully, but the description enriches it with example values and clarifies the omission behavior for a cross-category spread. This goes beyond the baseline for full schema coverage.

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

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

The description clearly states it returns category-bucketed example questions with exact tool+argument shape, and positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx by specifying it is for discovering what to ask, not answering directly.

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 instructs to use FIRST when unaware of Pipeworx's capabilities, and explains the two invocation modes (no args vs topic). It also orients the agent to learn how to call meta-tools, though it doesn't enumerate exclusions.

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

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

Annotations already declare the tool is not read-only, not destructive, and idempotent. The description adds valuable behavioral context beyond this: ownership enforcement, row deactivation instead of deletion, and the impact on historical events in recent_alerts. This exceeds what the 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 two sentences, front-loaded with the primary action. Every sentence adds substantive information: ownership enforcement and the deactivation behavior. There is no filler or redundant content.

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

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

For a simple one-parameter tool with no output schema, the description fully covers what the agent needs to know: what it does, who can use it, and what happens to the data. It explains the relation to recent_alerts and the deactivation semantics, making it complete in context.

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

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

Schema coverage is 100% and the parameter description already states 'Subscription id (uuid) returned by subscribe.' The tool description reiterates 'by id' but also clarifies the id's origin via 'returned by subscribe' in the schema. The description adds marginal but useful context about the parameter's provenance, so it earns a 4.

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

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

The description opens with a specific verb+resource: 'Cancel a subscription by id.' It clearly distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation. The added detail about ownership enforcement and deactivation further clarifies its unique scope.

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

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

The description provides clear context for when to use the tool: to cancel a subscription you own. It explicitly states the ownership constraint and how it differs from deletion via recent_alerts mention. However, it doesn't explicitly say 'use this instead of subscribe/list_subscriptions' or provide exclusions, so it's not 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 readOnly/openWorld/idempotent, but the description adds essential behavioral nuance beyond those flags. It explains the meaning of each verdict, especially the critical caveat that 'could_not_verify means the check did not happen … it is NOT evidence for or against the claim'. This prevents the agent from misusing failure states as evidence. It also discloses the verification_error structure and the distinction between could_not_verify and unsupported, which are not derivable from annotations alone.

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

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

The description is dense and information-packed, but it is not bloated. Every sentence contributes: trigger phrases, routing, return verdicts, caller warnings, and efficiency claims. The structure uses semicolons and dashes effectively to keep related ideas together. It is longer than average, but the complexity of the tool (multiple routing paths, nuanced verdict semantics) justifies the length. It earns a 4, not a 5, because a bit of trimming could remove redundancy (e.g., 'natural-language claim verification' appears twice).

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

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

Despite having no output schema, the description fully covers the return envelope: list of possible verdicts, the actual value with citation, reasoning, and error handling. It also explains when the tool falls back to a different source pipeline, which is essential for the agent to understand its behavior. Given the tool's complexity and absence of an output schema, the description is complete enough for an agent to invoke it 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% and both parameters already have descriptions, so the baseline is 3. The description adds extra value for tolerance_pct by explaining how to override the implied tolerance for specific use cases ('set 1–2 for hallucination detection'), which goes beyond the schema's basic 'Max percent deviation' definition. The claim parameter example is also helpful, but the schema already provides a solid example.

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

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

The description opens with a specific verb+resource pairing: 'natural-language claim verification against authoritative sources'. It lists exact trigger phrases ('is it true that…', 'fact check', 'verify the claim'), which distinguishes it from sibling tools like deep_research or ask_pipeworx. It also clarifies the routing behavior (SEC EDGAR fast path vs. grounded pipeline), making the tool's purpose unambiguous.

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

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

The description explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal fallback logic for different claim types. However, it does not explicitly name alternatives or state when not to use this tool (e.g., 'for open-ended research use deep_research instead'), so it stops short of a fully explicit when-not/alternatives guidance.

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