Jsonschema

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: the default free model (Workers AI Llama-3.3-70b), the need for an Anthropic API key for anthropic calls, and direct billing implications. It also discloses the return structure. 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?

Three sentences, front-loaded with the main function, then model details, then use cases. Every sentence contributes without 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?

With no output schema, the description compensates by listing per-model fields and combined view. It covers purpose, model selection, cost, and use cases. Minor gaps like error handling or rate limits do not detract significantly given the tool's read-only nature.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the default model, emphasizing the API key trade-off (BYO key and direct billing), and tying context to disambiguation. This pushes the score to 4.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model, which is a specific verb+resource+output combination. It does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, though the per-model scoring and combined view are distinguishing features.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use the tool but does not state when not to use it or explicitly compare with alternatives, which prevents 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, so the description's job is lighter. It adds meaningful behavioral context: the tool routes to 5,529 tools, returns citations, and handles a wide array of data domains. It could further disclose rate limits or error behavior, but the safety profile is already covered.

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 key instruction 'PREFER OVER WEB SEARCH' and is well-structured with examples and alternative tools. At five sentences, it's longer than minimal but every part adds value—domains, examples, and differentiation. Still, it could be tightened without losing substance.

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

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

No output schema exists, so the description must cover return behavior; it does: 'returns the structured answer with stable pipeworx:// citation URIs.' It also covers all critical aspects: what it does, when to prefer it, when to step up to alternatives, and what kinds of questions work. For a complex router tool, this is exemplary.

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 provides 100% coverage with descriptions for the 'question' parameter and its aliases (q, text, input, query, prompt). The description adds examples of valid queries but no additional syntax or constraints beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly defines the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It identifies the resource (Pipeworx) and specific verb (routes/returns), and distinguishes from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' establish when to use. It also states exclusions: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This clearly differentiates from alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about the beta mechanism, current inactive candidate state, and that it is a full working router. It does not contradict annotations, though it could further detail what happens when a candidate is active.

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 succinct and well-structured, with each sentence providing critical information: beta status, current equivalence, usage directive, and experimental nature. No waste; front-loaded with the key identifier.

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 compensates by stating 'same response shape' as ask_pipeworx, though it does not elaborate on that shape. It fully covers current behavior, experimental status, and fallback. Slight deduction for relying on a sibling tool for output details.

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

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

Schema coverage is 100% and all parameters are aliases for 'question', well documented in the schema. The description merely says 'same arguments' without adding extra parameter-level meaning, so the baseline 3 applies.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental edge and live candidate routing improvements.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router, providing clear when-to-use guidance. It also mentions when no candidate is active, implying use as a drop-in for ask_pipeworx.

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 substantial behavioral traits: it costs an extra LLM call, returns a structured refusal object with specific refusal reasons, and guarantees answers are grounded in the tool result. It also details the exact success and failure return shapes, adding significant context the annotations do not provide. 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 front-loaded with the core purpose and then efficiently covers routing, extraction, return format, refusal cases, use cases, and cost trade-off. Every sentence adds value, and the structure flows logically from what the tool does to when to use it.

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 present, the description fully compensates by listing the success return fields ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and all refusal reasons. It also captures the operational nuance of an extra LLM call and gives concrete high-stakes scenarios, making it complete 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% with all parameters being aliases for the same question field. The description does not add any parameter-level meaning beyond what the schema already states, 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 identifies this as a hallucination-resistant answer mode for high-stakes reads, using a specific verb ('extracts') and resource ('tool result'). It explicitly distinguishes itself from sibling ask_pipeworx by describing the same routing but a stricter answer extraction process, making it unique.

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 explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives an alternative: 'prefer ask_pipeworx for casual lookups,' directly telling the agent when not to use this tool.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds rich behavioral detail: fan-out patterns, status codes (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), resolver contract, parent_event extractor, news fallback fields, and cancellation-rule risk. This far exceeds the annotation baseline and provides actionable transparency.

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

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

The description is long, but it earns the length through dense, labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) that aid parsing. It's front-loaded with the core purpose. A 5 would require more brevity; a 4 acknowledges the well-organized but heavy detail.

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

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

With no output schema, the description fully covers return shapes: result.market fields, result.analysis, result.evidence, resolver metadata, parent_event, news fields, and statuses. It also preempts edge cases (cancellation rules, 429 fallback, wide spreads). This is complete enough for an agent to invoke and interpret 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 with 100% schema coverage, the description adds substantial meaning: it clarifies the market parameter accepts slug/URL/question text, explains quick vs thorough depth with source counts, and details when include_raw is needed ('recompute deltas, cite specific observations, or post-process'). The examples in the schema are reinforced by the fan-out examples.

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

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

The opening sentence states the exact function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the resource (Polymarket bet) and the verb (research/pull), and distinguishes from siblings like ask_pipeworx and polymarket_edges by focusing on the bet-resolution/fan-out workflow.

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 triggers: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when closed/low-confidence markets block with statuses. However, it doesn't explicitly name alternative sibling tools for non-Polymarket research, so it misses the explicit 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 already declare readOnly, idempotent, openWorld, and non-destructive, but the description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, metric sorting, and return format with pipeworx:// citation URIs. This goes well beyond the annotation baseline.

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

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

The description is dense but every sentence contributes: trigger phrases, preference rule, data-source details, sorting behavior, and return format. It is slightly longer than ideal but well-organized and front-loaded with usage cues. No fluff, though a few phrases could be tightened.

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

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

For a tool with 2 simple parameters and no output schema, the description covers all critical aspects: input types, data sources, sorting, output format (paired data + citation URIs), and efficiency rationale. Combined with strong annotations, the agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% with both type and values described, but the description adds meaningful enrichment: explains what each enum value retrieves (10-K metrics vs. adverse-event counts) and provides input examples ("AAPL", "MSFT", "ozempic"). This adds value beyond the schema, though the schema already covers the essentials.

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

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

The description clearly identifies the tool as a side-by-side comparator for 2–5 companies or drugs, with specific trigger phrases like "X vs Y" and "rank these companies." It distinguishes itself from siblings by emphasizing it replaces sequential lookups, making its 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?

Provides explicit when-to-use guidance with example queries and domain (company/drug) specifics. It directly states "ALWAYS PREFER over sequential single-pack lookups," naming the alternative behavior to avoid, and quantifies efficiency savings ("Replaces 8–15 sequential lookups").

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, non-destructive, open-world behavior. The description adds critical context: account requirement (free, paid for 'thorough'), latency 15-90s, gap[] semantics with 'never invented', contradictions[] for standard/thorough, citation_uri resolvability, semantic excerpting, and hop field. This goes far beyond what annotations provide and is fully consistent with them.

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

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

The description is long (~200 words) but front-loaded with critical access info and alternatives. Every sentence contributes to a complex tool's behavior. Could be improved with clearer segmentation (e.g., bullets) but it is not 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?

With no output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[] and contradictions[] handling, latency, depth differences, and fallback behavior for out-of-catalog topics. This leaves little ambiguity for an agent to invoke it correctly.

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

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

Schema covers both parameters with 100% description coverage. The description adds meaningful depth-specific behavior (gap recovery for 'standard', lead-chasing for 'thorough') and confirms that 'Broad/multi-part is fine' for the question parameter, enriching beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups. The verb+resource+scope is specific and distinguishes it well.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', plus an auth fallback. This is model-level guidance with named alternatives.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description adds valuable behavioral context: it returns top-N relevant tools with full input schemas and curated examples, ready to call directly without a second lookup. This explains what happens upon invocation and the tool's efficiency benefit.

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

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

The description is well-structured and front-loaded with the core purpose. It includes a list of use-case domains, return behavior, and a 'call first' guidance—all in a compact format without unnecessary verbosity.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (top-N tools with descriptions and schemas), when to use it, and what the query parameter expects. It covers the essential aspects for a discovery tool, making it complete.

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

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

Schema description coverage is 100%, with all parameters (query, q, task, limit, search, description) explained in the schema. The description does not add significant new parameter semantics; it merely summarizes the query concept, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Find tools by describing the data or task.' It lists concrete domains and distinguishes itself from sibling tools by being the discovery/meta tool, not a domain-specific query tool.

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

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

The description explicitly says when to use it: '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 provides clear context, though it does not name specific alternatives or exclusion criteria.

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

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

The description discloses several behavioral traits beyond the annotations: it fans out across multiple data sources in parallel, returns specific fields, and notes the USPTO PatentsView API sunset with soft-fail behavior. This adds meaningful context about the tool's execution and limitations, complementing the readOnly/idempotent 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 long but every sentence is informative: it leads with example queries, states preference, lists return fields with formats, and gives parameter constraints. No filler or redundancy; the structure aids quick comprehension of 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?

Given the tool's complexity and the absence of an output schema, the description thoroughly explains what the tool returns (CIK, filings, fundamentals, patents, news, LEI) with specific details like URI format and sorting. It also covers input constraints and fallback behavior, making it self-sufficient for an agent to invoke 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?

The input schema already fully describes both parameters, including examples ("AAPL" or "0000320193") and the restriction that names are unsupported. The description repeats these details without adding new semantic information, so it does not exceed the baseline of 3 for a 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 tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb ('profile') and resource (US public company via SEC/XBRL/news/GLEIF). It distinguishes itself from single-pack lookups and explicitly references resolve_entity for name resolution, making it distinct 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 when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear when-not scenario: 'names not supported (use resolve_entity first if you only have a name).' This gives actionable alternatives 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and deleting previously stored memories, reinforcing the destructive nature 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?

Two sentences clearly state purpose and usage guidance with no wasted words. The description is front-loaded with the primary action.

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

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

For a single-parameter destructive tool with clear annotations and no output schema, the description provides sufficient context for selection and invocation. It explains when to use and how it relates to siblings.

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 the parameter described as 'Memory key to delete.' The description mentions 'by key' but does not add further semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Delete a previously stored memory by key.' It clearly distinguishes from sibling tools like remember and recall, stating the action and object.

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 explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also points to related tools: 'Pair with remember and recall.'

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This tells the agent the tool performs a network fetch and returns a structured text blob, providing valuable context beyond the annotations.

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

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

Three compact sentences front-loaded with the primary action, followed by process and use cases. Every sentence adds value with zero waste, making it both concise and well-structured.

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

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

Given the simple two-param schema, clear annotations, and the description's coverage of functionality, output format ('single text blob'), and common use cases, the description is complete for an agent to invoke the tool correctly. No output schema is present, but the description specifies the return format sufficiently.

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

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

Schema coverage is 100% with descriptions for both url and max_links. The description's 'for any URL' aligns with the url parameter but does not add new meaning beyond the schema. The baseline 3 applies because the schema fully documents parameters.

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

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

The description uses a specific verb+resource+scope: 'Generate a production-ready llms.txt file for any URL' and clearly distinguishes the tool from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which focus on visibility checks rather than file generation.

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 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') that give clear context for when to invoke it. It does not name alternatives or exclusions, but the unique purpose is evident.

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, covering the safety profile. The description adds valuable context by listing the exact fields returned and emphasizing that it lists 'active' subscriptions by default, which goes beyond the schema and 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: the first states the action and return fields, the second explains when to use it. No unnecessary words, front-loaded with the core purpose.

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

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

For a simple list tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers the action, return values, and usage context, and aligns perfectly with the schema and annotations.

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

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

Schema description coverage is 100% for the single parameter (include_inactive) with a clear description. The tool description does not add any additional meaning about the parameter beyond the schema, 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 action ('List') and the resource ('the caller's active subscriptions'), and specifies the return fields. It distinguishes itself from siblings like subscribe and unsubscribe by focusing on the read-only listing of existing subscriptions.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly implies when to use it relative to subscribe/unsubscribe, though it does not explicitly name the alternative tools or state when not to use it.

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

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

The description reveals critical behavioral traits beyond the sparse annotations: rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token return mechanism, and the team's daily digest review. This is exactly the kind of operational context that annotations don't capture.

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

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

Though the description is lengthy, every sentence provides essential information. It is logically structured: purpose → use cases → exclusions → message guidance → token/claim flow → rate limits. No fluff or repetition; the only slight overlap is the claim_token mention, which appears in both schema and description but is necessary for behavioral clarity.

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

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

For a tool with no output schema and minimal annotations, the description is remarkably complete. It covers all key aspects: what the tool does, when to use it, exclusions, message content guidelines, response/claim_token handling, rate limits, and impact on roadmap. There is no missing critical context needed for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the intended content of the message parameter. It also reinforces the claim_token usage pattern, though the schema already documents that. Minor redundancy, but clear added guidance.

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

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

The description opens with a clear directive: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback categories (bug, feature/data_gap, praise) and explicitly contrasts with sibling tools by stating 'ONLY for tools served by this Pipeworx connection.' This fully differentiates it from other tools in the catalog.

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 comprehensive: it states when to use ('when a tool returns wrong/stale data...'), when not to use ('if the tool came from a different MCP server... file it with that server instead'), and even how to follow up (claim_token flow). The description gives both inclusion and exclusion criteria, making it exceptionally clear.

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

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

The description adds meaningful behavioral context beyond the annotations (readOnly, idempotent, openWorld, non-destructive). It discloses caching behavior ('Cached 5min-1h depending on window'), data privacy ('no PII'), and provenance ('derived from CF analytics-engine'), which are not captured by the annotations. This is a strong addition, though it stops short of detailing rate limits or explicit response format.

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

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

The description is dense yet efficient. Each sentence serves a purpose: the opening establishes the tool's nature, the second defines outputs, the 'Useful for' list provides practical contexts, and the final sentences cover data provenance and caching. There is no filler, and the most important information is front-loaded. Every sentence earns its place.

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

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

This is a simple tool with one optional parameter, rich annotations, and no output schema. The description fully covers the tool's purpose, expected return content ('top tools, top packs, and total call volume', 'just (pack, tool, count)'), and important behaviors like caching and privacy. There are no significant gaps for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already describes the `window` parameter with its enum values and semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The main description repeats this information but does not add new parameter-level meaning, so it meets the baseline without exceeding 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then states the verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This distinctly identifies the tool as a trending/aggregation tool, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

The 'Useful for' section explicitly lists three concrete scenarios: discovering hot data sources, confirming a canonical tool choice, and aligning use cases with common agent needs. This gives strong contextual guidance, though it does not explicitly mention when not to use it or name alternative tools. The window parameter guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand') also helps choose the right invocation.

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

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

Annotations already mark this as read-only and idempotent, but the description goes far beyond that by disclosing specific behavioral thresholds (3pp partition deviation, 0.30 Jaccard similarity, >20% placeholder fraction) and the fill check rule: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade; do not trade it.' This adds genuine decision-relevant context.

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

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

The description is long and dense, but every sentence serves a purpose. The use of sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) makes it navigable, and there is no filler content. It is structured well for an agent to extract the required information.

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

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

Covers all invocation modes, response structure ('opportunities[]'), filters, edge cases (placeholder rejection, low-similarity pairs), and tradeability warnings. It even points to a sibling tool for custom sizing. With no output schema, the description carries the full burden and meets it completely.

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 strong descriptions for both event and topic, so the baseline is high. The description adds behavioral meaning by explaining what each mode does internally (event walks child markets and checks date/threshold ordering; topic searches related events and runs a comparator on the union), going beyond the schema's one-liners.

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, unambiguous purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from siblings like polymarket_fill_risk and polymarket_edges by naming both the resource and the analytical method.

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 explains when to use each mode: 'Call with NO args for a trending_scan', 'pass `event` for...', 'or `topic` for...'. It also directs users to polymarket_fill_risk for custom sizing, providing an alternative tool and making the usage context complete.

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 extensive behavioral context beyond these: response segmentation (by_segment), edge calculation details (net of slippage, Kelly caps, favorite-longshot bias correction), a 24h-move warning, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostics for empty segments. This far exceeds the baseline annotation coverage.

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 one massive, uninterrupted paragraph with no section breaks, bullet points, or headings. It is information-dense but not concise or well-structured. While every sentence contains relevant detail, the lack of organization makes it harder to scan quickly. This is a clear structural deficiency, warranting a low 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?

For a tool with 9 parameters, no output schema, and high complexity, the description is exceptionally complete. It explains the three model families, response top-level fields, diagnostics, caching, parameter interdependencies, and even why fed candidates are excluded. It anticipates why segments might be empty and how to debug them. The description fully compensates for the absence of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics beyond the schema, such as explaining the purpose of tradeable-edge knobs (min_liquidity/max_spread_pp drop opportunities where edge isn't realizable) and the nuance of min_partition_leg_kelly (applies per-leg inside partitions since parent-level kelly is always 0). It also clarifies that min_kelly is half-Kelly and that edge is evaluated net of slippage, which adds value beyond the raw parameter descriptions.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan'), names the resource (Polymarket markets), and describes the output (opportunities). It also distinguishes itself from siblings by emphasizing 'agents discover opportunities without paging hundreds of markets,' which positions it as a high-level discovery tool rather than a niche arbitrage scanner.

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: 'Built for "what should I bet on today"' and explains the filtering knobs for tradeable edges. However, it does not explicitly mention when NOT to use it or name sibling alternatives. It gives clear context but lacks explicit exclusions, which fits the 'clear context, no exclusions' level.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses key behavioral traits: snapshots are written on cache-miss, gaps indicate no scan that day, history is bounded by a 60-day TTL, and decay is based on daily closes of edge_pp_net rather than intraday data. These details help the agent anticipate data availability and interpretation.

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

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

The description is lengthy but well-structured with intro, Args, RESPONSE, and LIMITS sections. Every sentence carries useful information, and the front-loaded purpose makes it easy to grasp. The length is justified by the richness of the output format and the need to explain snapshot semantics, though it could be tightened slightly.

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

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

With no output schema, the description fully explains the return structure: tracked[] with fields like edge_pp_net time-series, first_seen, trend, and decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[]. It also covers limitations like TTL and daily-close basis, making it exceptionally complete for a telemetry tool.

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

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

The input schema already provides 100% coverage of both parameters ('days' with default/clamp and 'window' with possible values). The description's restatement of defaults adds little beyond the schema. It does offer minor context about the meaning of 'snapshot family', but the schema is equally explicit, so the description provides no significant additional parameter value.

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

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

The description clearly identifies the tool as tracking edge persistence and decay, answering the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges by focusing on historical telemetry across snapshots rather than current edges.

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

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

The description provides a clear usage context: it is for evaluating whether an edge is fresh or aged, noting that 'a fresh wide edge and a 3-week-old wide edge are different trades'. It does not explicitly name alternative tools, but the context makes it evident when this tool is appropriate in contrast to single-snapshot edge tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: it 'walks the ladder', returns verdicts (clean|degraded|cannot_fill), and warns that 'partial basket fills convert an arb into an unhedged directional position'. No contradiction with annotations.

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

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

The description is long (~300 words) but exceptionally well-structured with uppercase mode labels and semicolon-separated detail lists. Every sentence conveys operational information, though it could benefit from bullet points or line breaks to improve skimmability. Slight deduction for density, not verbosity.

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 present, the description enumerates all key 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, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers prerequisites, defaults, and risk caveats, making it fully self-sufficient.

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

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

Though the schema covers all four parameters, the description adds crucial mode-specific semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also discloses defaults and clamp range ('default 1000, clamp 10–1,000,000'), going beyond the schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb+resource combination that clearly defines what the tool does and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It further clarifies two distinct modes (single-market vs basket), leaving no ambiguity about 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why this tool is necessary ('theoretical overround on thin books is not capturable') and when to use each mode (market vs event).

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

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

Beyond the annotations (read-only, idempotent), the description discloses detailed behavioral traits: compatibility_warning conditions, temporal_alignment meaning, skipped_cross_type/subtype semantics, and the honest caveat that most pre-mapped topics return warnings. This is rich, non-obvious context.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. However, it is long and includes some repetition (e.g., bet-shape equivalence mentioned both in the opening and in compatibility_warning details), making it slightly less concise than ideal.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers the response format, safety fields, and interpretation of edge cases (e.g., matched_pairs:0 scenarios, temporal_alignment). It leaves no significant gaps for an agent to understand when and how to use the tool.

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

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

The schema already covers 100% of parameter descriptions, so the baseline is 3. The description adds valuable semantic context by explaining the two modes (topic vs explicit) and that explicit parameters override mapped ones, which clarifies parameter relationships beyond the schema.

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

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

The description opens with a specific verb-resource combination: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately differentiates from sibling tools by emphasizing cross-venue comparison and bet-shape equivalence, making the tool's purpose unmistakable.

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

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

The description explicitly presents TWO MODES with concrete examples for each, and provides clear when-not-to-use guidance: 'pre-mapped ≠ tradeable' and warnings about compatibility_warning cases. This is strong usage direction beyond mere functionality.

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. The description adds substantive behavioral context beyond those: the ability to list all keys by omitting the key argument, scoping to the caller's identifier (anonymous IP, BYO key hash, or account ID), and the relationship to remember/forget. No contradiction with annotations.

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

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

The description is four sentences, each earning its place: function, use cases, scoping, and companion resources. No filler or redundancy. Front-loaded with the core action and then expands context. Well-structured and tight.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the essential behavior, use cases, scoping, and relation to siblings. The only minor gap is not describing the return format (e.g., what happens when the key is not found), but the tool's simplicity and clear function make this a minor omission.

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% (the sole 'key' parameter is fully described). The description adds value by explaining that the key refers to something saved via 'remember' and that omitting it lists all keys. It provides examples of what keys might be, but this mostly reinforces semantics already present in the schema, so a 4 is appropriate.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly states both primary functions and distinguishes from sibling tools (remember, forget). It is specific, unambiguous, and immediately scopes the tool's purpose.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and pairs it with companions ('Pair with remember to save, forget to delete.'). It also gives concrete examples of use cases (target ticker, address, research notes), providing clear guidance without needing to explicitly list alternatives.

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

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

The description goes beyond annotations by detailing the return payload contents (source, citation_uri, raw event payload), the mark_read side-effect for subsequent calls, and polling behavior. It also states the feed is persisted. This adds value without contradicting the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint 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 and well-structured: it opens with the core function, then explains return contents, then usage options, and finally additional context about polling and an alternative endpoint. No redundant words or filler; every sentence earns its place.

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

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

For a read-only tool with 5 parameters and no output schema, the description covers the essential aspects: what is returned, key filtering options, the mark_read side-effect, and the alternative feed URL. It doesn't explicitly detail 'limit' or 'unread_only', but these are adequately covered in the schema. It's sufficiently complete for an agent to invoke correctly.

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

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

With 100% schema description coverage, the schema already documents all parameters. The description adds contextual meaning, such as the example type 'sec_8k', the semantic of mark_read affecting next calls, and clarifying the 'since' filter as ISO timestamp with fired_at comparison. This supplements the schema with practical usage context.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with specific verbs ('Pull', 'Returns') and a resource ('your subscription feed'). It also differentiates from siblings like recent_changes by emphasizing subscription alerts and the evaluator's persisted 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 gives clear context for when to use the tool, such as polling and filtering by type and since, and notes that the same feed is accessible via a public URL. However, it does not explicitly mention alternatives or when NOT to use it, falling just short of the top bar.

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 source-specific behavior (SEC EDGAR, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset), date parsing flexibility, and the return structure. This goes well beyond the readOnly/idempotent hints by adding failure modes and external dependencies.

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 perfectly structured: front-loaded examples, then source fan-out, date formats, output summary, and alternative. Every sentence adds distinct value with no repetition or filler.

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

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

For a multi-source tool with no output schema, the description covers all necessary ground: input formats, source behaviors, fallback logic, output shape, and an alternative tool. It is practically 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?

Although schema coverage is 100%, the description enriches each parameter: since gets concrete formats ('2026-04-01', '7d', '30d', '3m', '1y'), value is shown as ticker or CIK, and type is confirmed as only 'company'. This adds practical usage context beyond the schema.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, illustrated with specific example queries. It explicitly differentiates from entity_profile by noting the alternative for static profiles, so its purpose is unambiguous and distinct from 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?

It provides concrete intents ('What's new with X', 'updates on Acme') and explains the fan-out to multiple sources. It explicitly names entity_profile as the alternative for static profiles regardless of window, giving clear when-to-use vs. when-not-to-use guidance.

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

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

Beyond annotations, the description discloses key behavioral traits: storage as a key-value pair scoped by identifier, and persistence details (persistent for authenticated users, 24-hour retention for anonymous sessions). This adds useful context about memory lifecycle that annotations don't cover.

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

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

The description is concise, front-loaded with the main action, and every sentence provides useful information. It avoids redundancy and is appropriately sized for a simple two-parameter tool.

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

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

Given the simple schema and no output schema, the description fully covers the tool's behavior, persistence, and relationship to sibling tools. It answers likely agent questions about memory scope and duration, making it complete for this tool.

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

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

The input schema already describes both parameters (key and value) with examples and 100% coverage. The description adds the context of a scoped key-value store, but doesn't significantly enhance parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes itself from sibling tools by explicitly mentioning companion tools recall and forget, and provides concrete examples of what to store.

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

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

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with examples. It also tells the agent to pair with recall and forget, giving clear context for integration with other tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds rich behavioral detail: cascading lookups, graceful degradation of LEI/FIGI enrichment, explicit handling of unresolved identifiers, and source labeling for every identifier. This significantly exceeds what annotations alone 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 densely packed with essential information, structured by examples and supported types. Some verbosity exists, but every sentence adds value for a tool with two distinct entity types and multiple identifier sources.

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

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

Given the tool's complexity (two entity types, multiple identifier systems, cascading internal calls) and no output schema, the description thoroughly covers inputs, outputs, source labeling, unresolved handling, and fallback behavior. It fully prepares 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?

Although the schema covers 100% of parameters, the description enriches both params: it explains 'type' enum values ('company', 'drug') with domain-specific detail, and 'value' with concrete examples (ticker, CIK, brand/generic names). It also adds return-context semantics not present in the schema, such as source attribution and unresolved identifier handling.

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

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

The description clearly identifies the tool's function: resolving user-spoken names to canonical/official identifiers required by other tools. It lists example queries and distinguishes itself from siblings by emphasizing name-to-ID resolution, not profiles or comparisons.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use context. It doesn't name alternative tools or when-not-to-use situations, but the guidance is direct and actionable.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that it probes each entity, ranks by score, and returns score, confidence, and signal density per entity. It also notes that the first entity is treated as the 'subject' for narrative, adding useful behavioral context. There is no contradiction with annotations.

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

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

The description is only two sentences plus a short example, front-loading the core purpose and key behavior. Every sentence adds value, with no redundant or filler content.

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

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

For a tool with no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density). Combined with full schema coverage and robust annotations (readOnly, idempotent, non-destructive), the description is complete enough for an agent to understand when and how to invoke the tool correctly.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for entities, models, _apiKey, and context. The description adds contextual clarity by explaining that entities includes the subject plus competitors and gives a context example, but it does not significantly extend the parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each entity, ranks by score, and identifies most/least recognized. It explicitly references ai_visibility_check as the underlying probe, distinguishing it from single-entity sibling tools, and the phrase 'competitive AI-marketing audits' makes the competitive differentiation apparent.

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 a concrete use case ('competitive AI-marketing audits') with an illustrative question ('does Claude know about us as well as our competitors?'). This implies when to use the tool (multi-entity comparison) vs a single check, but it does not explicitly list exclusions or directly name alternative sibling tools for comparison scenarios.

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 richly discloses behavioral traits beyond annotations: it returns a summary block with specific fields, lists per-advisory detail and recent versions, and explicitly states that partial failures degrade gracefully with bundlephobia's first measurement potentially taking 5-30s and timing out being listed in sources_failed. This transparency exceeds what the readOnly/idempotent hints provide.

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

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

While the description is lengthy, every sentence earns its place: purpose, usage triggers, output details, ecosystem scope, and failure mode. It is well-structured with dashes and lists, and front-loaded with the core purpose. 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?

The description is remarkably complete for a composite tool with no output schema. It explains return values (summary block, per-advisory detail, links, recent versions), data sources, ecosystem limitations, timeout behavior, and graceful degradation. There is no significant missing 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% with both parameters (package, version) fully described in the schema. The description does not add significant extra parameter semantics beyond what's in the schema, but it is consistent. 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 the tool's purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It names specific resources and aspects (license, advisories, bundle size, tree-shaking), making it distinct 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?

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies ecosystem limitations (NPM only in v1, other ecosystems fall under deps.dev:version directly), providing clear direction on when this tool is appropriate versus alternatives.

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

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

Annotations declare readOnlyHint and non-destructive, and the description adds significant behavioral detail: BGE-base-en embeddings, 500-char overlapping windows, a 200K char cap with truncation flagged, and output including character offsets and similarity scores. This goes far beyond the annotations, giving the agent a precise mental model.

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, each serving a purpose: core action, usage trigger, pairing, and technical mechanics. It is dense but not padded; every sentence earns its place.

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

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

There is no output schema, so the description must explain return value — it does: 'top-N passages with character offsets and similarity scores.' It also covers the input cap and truncation behavior and explains the practical use case. This is complete for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds context that 'text' should be a pre-fetched document (SEC 10-K, article, tool result) and that the query is natural-language, which enriches the schema descriptions without duplicating them. This modest extra value 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 'Semantic search INSIDE a fetched record' — a specific verb, resource, and scope. It clearly states what the tool returns (top-N passages with character offsets and similarity scores) and distinguishes itself from siblings like ask_pipeworx_grounded by framing it as the local retrieval step.

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 tool, ask_pipeworx_grounded, and provides a workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear usage context and alternatives.

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

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

Annotations cover basic flags (readOnlyHint false, idempotentHint true, destructiveHint false), but the description adds substantial context: OAuth requirement, phone verification and daily cap, webhook auto-disable after 10 failures, and that the signing secret is returned only once. This fully discloses operational behavior beyond annotations.

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

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

The description is dense but well-structured, with a clear opening and semi-colon separated details. Every sentence provides necessary information, though the length is high; it could be slightly more scannable with bullet points, but it remains 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?

This is a complex tool with nested objects, five subscription types, and multiple delivery channels. With no output schema, the description adequately explains return values (subscription id, one-time webhook secret), auth matters, type-specific params, and delivery limitations. No significant gaps remain.

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

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

Schema coverage is 100%, but the description enriches parameter meaning with concrete examples and semantic notes, such as 'items:["5.02"] = officer change' and the detailed conditions for each subscription type. It also clarifies delivery parameter behavior (verified phone, webhook HMAC signing), adding value beyond the raw 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by emphasizing the creation of a new subscription and the return of a new subscription id.

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 (proactive monitoring) and includes prerequisites (requires Pipeworx OAuth, anonymous/BYO can't persist), plus delivery channel constraints. However, it does not explicitly name alternative tools or state when not to use this tool, losing a point.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by explaining that it returns category-bucketed example questions drawn from a live catalog of thousands of tools, and that it can be called with no arguments or with a topic. This goes beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with natural language query examples, then explains what the tool returns, followed by usage and when-to-use. Every sentence earns its place, with no wasted words.

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

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

For a tool with no required parameters and no output schema, the description is remarkably complete. It covers the purpose, return content (category-bucketed questions with tool+argument shape), parameter usage, and explicit usage guidance, making it self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% for the single 'topic' parameter, and the schema already lists the valid focus areas and the 'omit for cross-category spread' instruction. The description adds examples (e.g., 'finance', 'pharma', 'betting') but these are a subset of what's in the schema, so it adds minimal extra meaning beyond the structured data.

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: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like discover_tools by emphasizing its role as a first-stop for users wondering what to 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 when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also lists example user queries and explains that passing a topic focuses the results, while omitting it returns the full spread.

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

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

Description adds important behavioral context beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('row is deactivated not deleted'), which explains why historical events remain accessible. No contradictions with readOnlyHint=false, destructiveHint=false, or idempotentHint=true.

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

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

Two sentences, front-loaded with the primary action, then concise behavioral nuances. Every word earns its place with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, ownership constraints, and side effects. It is sufficiently complete given the low complexity and rich schema.

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

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

The schema already provides 100% coverage of the single parameter id, describing it as 'Subscription id (uuid) returned by subscribe.' The description does not add new parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific resource (subscription). It distinguishes itself from sibling tools like subscribe (creation) and list_subscriptions (listing) by the verb 'cancel'.

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 (canceling a subscription you own) and hints at the consequence (deactivation, not deletion). It does not explicitly mention alternatives or when not to use it, but the ownership constraint and deactivation note offer sufficient guidance.

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

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

The description goes far beyond the read-only/idempotent annotations by explaining the dual pipeline behavior, the verdict vocabulary, and critical caveats—especially that `could_not_verify` means the check did not happen and carries `verification_error{stage,detail}`, and that it must not be presented as evidence. It also defines `unsupported`, giving the agent essential edge-case understanding.

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 well-structured, opening with the core purpose, then usage, pipeline routing, return format, and ending with two critical caller warnings and a performance note. Every sentence adds information; 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?

Given there is no output schema, the description fully compensates by specifying the verdict values, the return payload (actual value + citation + reasoning), and explaining ambiguous verdicts like `could_not_verify` and `unsupported` in depth. The schema and annotations cover parameters and safety, so nothing critical is missing.

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

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

The input schema already provides 100% coverage: `claim` includes examples and `tolerance_pct` is fully described with range, override behavior, and default. The tool description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies.

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

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

The description is explicit: natural-language claim verification against authoritative sources, with concrete triggers like "fact check" and "verify the claim that…". It distinguishes the tool from siblings by focusing on verdict-based validation and explicitly notes it replaces a multi-step pipeline.

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 clearly states when to use: "Use whenever the agent needs to check whether something a user said is factually correct." It also differentiates company-financial claims from other factual claims and describes the "grounded pipeline" fallback. However, it does not name specific sibling tools or give explicit when-not-to-use conditions, so it misses the top score.

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

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

While annotations declare readOnlyHint/idempotentHint, the description adds substantial context: supported draft-07 subset, offline/keyless behavior, and exact return format. This goes beyond annotations and helps predict tool behavior accurately.

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

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

Two sentences only: first states purpose and supported keywords, second gives return format and key constraints. Every sentence earns its place with no redundancy.

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

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

Given no output schema, the description fully compensates by specifying the return shape ({valid, errors}). It also covers supported subset and offline/keyless nature, making the tool fully understandable. Siblings are unrelated, so no missing 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 already provides 100% coverage with descriptions for both parameters. The description enriches the schema parameter by listing supported JSON Schema keywords, clarifying which schema features are accepted, adding value beyond the structured schema.

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

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

Description clearly states the tool validates a JSON value against a JSON Schema, with a specific verb+resource. It also distinguishes itself from siblings by being a unique validation utility, not related to AI/prediction 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 context ('Keyless, offline') but doesn't explicitly state when to use this tool over alternatives or exclude any use cases. No clear sibling alternatives exist, so the guidance is implied rather than explicit.

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