dnd5e

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context about cost ('free' Workers AI default) and authentication ('BYO key' for Anthropic, with direct payment). It also reveals the return structure (per-model score, confidence, signals, raw_response). This goes beyond what annotations provide.

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

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

The description is a compact, three-sentence paragraph where each sentence serves a distinct purpose: what the tool does, configuration details, and use cases. No redundant wording; it is 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 tool with 4 parameters, full schema coverage, and annotations, the description adequately covers purpose, configuration, output format, and practical use cases. Minor details like rate limits or error handling are not mentioned, but they are not essential for correct invocation given the tool's simplicity.

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

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

The schema has 100% description coverage for all parameters, so the baseline is 3. The description enriches this by explaining defaults (e.g., 'Default model is Workers AI Llama-3.3-70b'), the _apiKey pass-through behavior, and provides an example entity. This adds meaning beyond the schema.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility on a 0-100 scale. It specifies the resource (LLMs) and the action (probe and score), and this distinguishes it from siblings like scan_competitor_ai_presence, which likely focuses on a different aspect of AI visibility.

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

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

The description provides concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. It does not explicitly list alternatives or exclusions, but the context is sufficient for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it routes questions to sub-tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and accesses live data sources. It also notes the tool uses citations for hallucination resistance. This goes beyond what annotations convey, though it does not detail rate limits or error behavior.

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

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

The description is long but purposeful. It front-loads the most critical instruction ('PREFER OVER WEB SEARCH') and packs detailed domain lists and trigger phrases into compact form. The examples and routing explanation earn their place, though the text could be slightly trimmed without losing value. Overall it is efficient relative to the amount of guidance it provides.

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

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

Given the tool has 6 parameters (5 aliases + question), 100% schema coverage, and no output schema, the description is complete enough for an agent to select and invoke it correctly. It explains what the tool does, when to prefer it, what alternatives exist, what behavior to expect (routing, argument filling, citations), and provides multiple concrete examples. There is no critical missing information 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 description coverage is 100%, with the single required parameter 'question' fully described and five aliases documented. The description reinforces the parameter's semantics by explaining that it accepts natural-language requests and providing examples of valid questions. While the schema already covers the parameter well, the description adds contextual value by specifying that the question will be routed and answered, and shows example formulations.

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

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

The description explicitly states that ask_pipeworx answers factual questions with authoritative structured data and routes to 5,767 tools across 1,506 verified sources. It lists specific domains (SEC filings, FDA data, economic stats, patents, real estate, weather, clinical trials, news, stocks, crypto, sports, academic papers) and provides concrete examples, making the purpose unmistakable and distinguishing it from web search and other 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 strong usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' explicitly state when to use it. It also names sibling alternatives (ask_pipeworx_grounded, deep_research, *-news-feeds packs) and gives conditions for choosing them, such as 'for a broad/multi-part question that should fan out across many sources at once use deep_research' and 'for breaking-news use *-news-feeds packs'. Trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', 'current' further clarify when to invoke.

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

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

Annotations already mark it read-only and idempotent; the description goes beyond by revealing that routing improvements may be live under test and that no candidate is currently active (retired 2026-07-26), so behavior currently matches the stable router but may drift later. The statement 'Falls back to nothing — this IS a full working router, just the experimental edge' preempts a wrong assumption that beta might be a stub. This is valuable behavioral context not present in the schema or 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 not wasteful, front-loading the beta identity and the 'identical router' fact before explaining the dynamic test state. The historical retirement date is slightly extraneous for an agent deciding how to call the tool, but the rest of each sentence carries operational or behavioral value.

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

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

For a query-only router with rich annotations and full schema coverage, the description covers the essential context: what it is, how it currently behaves, when to use it, and the fact that it is not a fallback stub. It also points to the stable ask_pipeworx for the response shape and arguments, closing the gap left by the missing 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%, with all six parameters documented as string aliases for the natural-language question; the description adds no parameter-level details beyond what the schema already provides. Per the rubric, with full schema coverage the baseline is 3 even without parameter text in the description.

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

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

The description identifies ask_pipeworx_beta as a beta version of the ask_pipeworx universal router with the same 5,767 tools, arguments, and response shape. This clearly states a concrete function (routing questions to a large toolset) and differentiates it from stable and other siblings by its experimental candidate-routing behavior. No tautology or vagueness.

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

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

It explicitly instructs: 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a concrete condition for choosing this variant. It also clarifies that results are compared against the stable router, but it does not explicitly say when NOT to use it, e.g., when stability is required, leaving that exclusion implicit.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses crucial runtime behaviors: that answers are extracted only from tool results, the exact success/refusal output shapes, explicit refusal reasons, and the extra LLM call cost. This is substantial behavioral context not available from structured fields.

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

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

The description is information-dense yet efficiently structured: purpose, routing behavior, extraction guarantee, return/refusal shapes, usage guidance, and cost comparison all fit within four sentences. It is front-loaded with the core purpose and every sentence adds operational value.

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

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

For a grounded answer tool with no output schema, the description fully covers return values, refusal behavior, when to use it, alternatives, and cost trade-offs. It is complete enough for an agent to decide on and invoke this tool correctly in high-stakes contexts.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter as an alias for 'question.' The description adds no additional parameter semantics, but it does not need to; the baseline of 3 is appropriate when the schema carries the explanatory weight.

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 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying a specific purpose and mode. It contrasts with ask_pipeworx by emphasizing grounded extraction using only tool results, and names the sibling it is not via 'Same routing as ask_pipeworx.' This distinguishes it sharply 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?

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives the exclusion and alternative: 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost. This is direct, actionable guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral traits: market resolution and classification, parallel fan-out, resolver contract with match confidence and alternatives, parent_event extraction, safety short-circuiting for low-confidence matches, closed-market status, wide-spread tradeability flag, and resolution-rule risk parsing. It also explains the GDELT fallback and blocked paths, providing deep context for agent decision-making.

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

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

The description is very long but exceptionally well-structured with clear headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every section adds distinct value for the complex fan-out and safety behavior, so the length is justified, though it pushes the edge of conciseness.

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

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

With no output schema, the description carries the full burden of explaining return values, and it thoroughly does so: result.market fields, result.analysis with edge metrics, evidence keying, resolver contract, parent_event, news fallback fields, statuses, and resolution-rule risk. It also covers edge cases like closed markets, wide spreads, and mismatched resolutions, making the description complete for an AI agent to invoke the tool safely.

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 for the three parameters (market, depth, include_raw), so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema: it repeats the slug/URL/question-text format for market and mentions the default behavior for depth and include_raw, but does not introduce syntax or format details beyond what the schema gives. The fan-out examples illustrate depth behavior but are more about tool behavior than parameter semantics.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on single-bet research with fan-out, and provides explicit use cases ('should I bet on X', 'what does the data say about Y'). The scope of Polymarket bets and the resolver/fan-out mechanism make it distinct from other Polymarket 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 usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also conveys that one call handles resolution, classification, and fan-out. However, it does not name alternative sibling tools or state when not to use it, so it lacks explicit exclusions or alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: it pulls specific SEC EDGAR/XBRL data for companies and FAERS data for drugs, sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond the safety 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 front-loaded with user-matching trigger phrases and gets to the core purpose in the first sentence. Every subsequent sentence adds essential detail (type-specific data sources, sorting, output format, efficiency gain) without redundancy. It is dense but appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (two entity types, sorting behavior, citation output) and the absence of an output schema, the description fully covers what the agent needs to know: what data is returned, how results are ordered, and how many sequential calls it replaces. 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?

Although schema coverage is 100%, the description enriches parameter meaning by explaining what type='company' and type='drug' actually retrieve (10-K financials vs. adverse-event counts, etc.). It also provides concrete examples of valid values, exceeding 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 verb 'compare' and the resource '2–5 companies or drugs'. It also includes trigger phrases like 'X vs Y' and 'rank these companies', making the purpose unmistakable. It distinguishes itself from siblings like entity_profile by emphasizing parallel comparison in a single call.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear when-to-use directive. It also describes the alternatives it replaces (sequential lookups) and provides concrete examples of queries that should trigger 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?

Goes well beyond the readOnly/idempotent annotations by describing parallel tool routing, findings-packet fields, gaps[] for unanswered facets, never-invented guarantees, contradictions[] on deeper depths, semantic excerpting, citation_uri fetchability, and expected latency. This gives an agent a strong operational model of what will happen when invoked.

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

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

The opening is well front-loaded with purpose and alternatives, but the description repeats a large block almost verbatim, which bloats the text and forces the agent to wade through duplicates. The repetition prevents this from being an appropriately sized, tightly structured description.

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

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

Even though there is no output schema, the description enumerates the return packet contents, citation behavior, gaps[], contradictions[], account constraints, and latency expectations. This is complete enough for an agent to select and invoke the tool correctly and interpret its result.

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 schema already documents both the question and depth parameters thoroughly, including hop and contradiction differences. The description adds paid-plan and latency context, but largely restates behavior already present in the schema. Baseline 3 is appropriate at this coverage level.

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?

States a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources ... in ONE call' and explicitly distinguishes itself from open-web search and from ask_pipeworx. Example questions make the intended use concrete. Despite duplicated text, the core purpose is unmistakable.

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

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

Explicitly names ask_pipeworx as the alternative for single lookups and for users not signed in, and says deep_research is best for broad/multi-part structured-data questions. It also communicates the account and paid-plan requirement for thorough depth. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish a safe, read-only, idempotent operation. The description adds meaningful context about return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations by clarifying the self-contained nature of results.

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

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

The description is front-loaded with the core purpose and then provides a useful domain list, return format, and usage guidance. The domain enumeration is somewhat lengthy but serves to set expectations for scope. Each sentence contributes to understanding; no significant 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?

There is no output schema, so the description must explain return values, and it does: it returns top-N tools with names, descriptions, and full schemas. Combined with rich annotations and a clear single-parameter schema, the description covers the essential usage scenarios sufficiently. Some minor edge cases (e.g., empty results) are not covered, but the core context is complete.

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

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

Schema coverage is 100%, with detailed descriptions for all 6 parameters including aliases and examples. The description adds minimal new meaning; it reaffirms that queries are natural-language descriptions and mentions 'top-N' which aligns with the limit parameter already documented. The schema carries the heavy lifting, 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's purpose with a specific verb ('Find tools') and resource ('by describing the data or task'). It distinguishes itself from siblings by being a meta-tool for discovering other tools, listing specific domains it covers (e.g., SEC filings, FDA drugs, weather) and noting it returns schemas for direct invocation.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives clear context but does not explicitly list when-not-to-use or name alternative tools, though the 'not just one answer' hint implies exclusion.

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

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

Although annotations already mark the tool as read-only and idempotent, the description adds substantial behavioral context: it fans out across SEC, XBRL, USPTO, USAspending, FDA, DOL, news, and GLEIF; explains that empty sections mean real 'no data'; discloses the USPTO PatentsView API sunset with soft-failure behavior; and clarifies that private companies return resolved:false with an explicit notes line. None of this contradicts the annotations.

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

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

The description is long, but the tool is genuinely complex with many data sources and edge cases. It front-loads the purpose and triggers before listing outputs and source semantics. Some sentences are dense and could be trimmed, but each section earns its place for such a comprehensive tool.

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

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

Given the tool has no output schema and the task is broad, the description is unusually complete: it enumerates every returned field group, explains source-level failure modes, covers input type flexibility, and gives explicit guidance for expected empty results. An agent can accurately predict behavior and formulate a call without additional 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 description coverage is 100%, and the description goes beyond the schema by noting that 'type' accepts 'company' or 'ticker' interchangeably and that 'value' can be a ticker, zero-padded CIK, or company name. It also explains name resolution via SEC EDGAR and the private-company fallback, which adds real operational meaning not present in the schema alone.

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

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

The description names a specific verb and resource: building a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts itself with 'chaining single-pack SEC/XBRL/news lookups,' making it easy for an agent to select this tool over the general category of piecemeal lookups.

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

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

It gives concrete trigger phrases ('Tell me about X', 'research Acme', 'brief me on Tesla') and an explicit directive to prefer this over chaining single-source calls when a holistic view is requested. It also covers edge cases like private companies and how to pass inputs, so an agent knows both when and how to invoke it.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description adds context about clearing sensitive data and that the memory was previously stored. This exceeds the bare annotation signal without contradicting it.

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 accomplish the entire description: the first states the core action and the second adds usage criteria and related tool context. No filler or repetition.

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

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

For a single-parameter memory deletion tool with rich annotations and clear sibling relationships, the description fully covers purpose, usage, and pairing. No output schema exists, so return value explanation is unnecessary.

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 property description 'Memory key to delete'. The tool description does not add additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. This uniquely distinguishes it from sibling tools like remember and recall, which store and retrieve memories respectively.

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

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

It explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with related tools, guiding the agent toward proper selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a single text blob, which helps manage expectations. No contradictions with annotations.

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

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

The description is concise and well-structured: three sentences covering purpose, process, and use cases. Every sentence adds value, and the information is front-loaded in the first sentence.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description is largely complete. It covers the output format, process, and use cases. Minor gaps include lack of mention of error handling for unreachable URLs, but this is not critical for a read-only, idempotent tool.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are fully documented in the schema. The description does not add additional parameter-specific details beyond what the schema provides, but it does explain the overall process, which is consistent with the baseline of 3.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the resource (llms.txt), the action (Generate), and the intended use for AI crawlers. It also differentiates from sibling tools like ai_visibility_check by focusing on file generation rather than checking visibility.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent.

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, so the safe read-only nature is covered. The description adds useful context by stating what the return includes ('feature progression, proficiency gains, and subclass options'), going beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the main action and resource, with no filler. Every sentence contributes to understanding what the tool does and how 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?

The tool is simple with one parameter, an output schema exists to define returns, annotations cover safety, and the description mentions return content. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the parameter 'index' is already described with examples. The description reinforces this with additional examples ('barbarian', 'wizard', 'rogue'), but this adds only marginal value beyond the schema, so a 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 uses the specific verb 'Get' with a clear resource ('class') and enumerates what is retrieved ('features, hit dice, proficiencies, and advancement tables'). It also provides example indices, making the purpose unambiguous and distinct from sibling tools like get_monster and get_spell.

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

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

The description clearly instructs the agent to 'Provide class index' with examples, establishing when to use the tool. It does not explicitly mention alternatives or exclusions, but the sibling tools are for different entities, so the usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds details about the output (ability scores, skill bonuses, attack actions) but does not disclose extra behavioral traits like rate limits, error handling, or edge cases. 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 concise and front-loaded with the purpose. It has some redundancy between the initial stats list and the later return details, but overall it is efficient and free of 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?

For a simple read-only lookup tool with a single parameter, an output schema, and comprehensive annotations, the description is sufficiently complete. It covers input and output details, though it could mention error handling or non-existence cases, which is minor.

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

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

Schema coverage is 100% and the schema already describes the 'index' parameter in detail with examples. The description repeats these examples but adds no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool gets monster stats, listing specific attributes (AC, HP, abilities, skills, senses, actions). It distinguishes from sibling tools like get_spell and get_class by explicitly focusing on monsters and providing monster index examples.

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

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

The description gives clear usage context: it tells the agent to provide a monster index with examples. However, it does not explicitly mention when not to use this tool or name alternative tools for other entities, though the sibling context implies it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it 'Returns damage dice, range, casting time, and effect descriptions,' which is helpful but largely redundant given the output schema exists. No additional behavioral traits such as permission requirements or edge cases are disclosed, so the description adds only marginal transparency beyond the annotations.

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

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

The description is two sentences and immediately front-loads the purpose ('Get spell details'). It includes necessary examples and a brief return summary without any wasted words. Every sentence serves a clear function, making it highly 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?

For a simple single-parameter tool with an output schema and strong annotations, the description is largely complete. It states the input requirement, gives examples, and outlines what information is returned. The only gap is the lack of explicit guidance on using list_spells for browsing or finding indices, but this is a minor omission given the tool's simplicity.

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

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

The schema has 100% coverage with a detailed description of the 'index' parameter including kebab-case examples. The description repeats 'Provide spell index' and offers the same examples from the schema, adding no new semantic information. Since the schema already documents the parameter fully, the description's contribution is minimal, warranting the baseline score of 3.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('spell details'), and lists the types of information returned (damage, range, duration, components, effects). It also provides concrete examples of valid indices, leaving no ambiguity about what the tool does. The sibling tool list includes list_spells, which reinforces the distinct lookup-by-index 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 provides a prerequisite by instructing the user to 'Provide spell index' and gives example indices, which implies the tool is used when you already know the specific spell. However, it does not explicitly mention when to use this over sibling tools like list_spells or get_monster, nor does it state any exclusions. Usage context is implied but not fully articulated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds return value context (indices, names, levels) but creates confusion by implying search parameters ('by name or level') when the schema has none. It does not disclose this mismatch or explain how the search is actually performed.

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

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

Two concise sentences with clear front-loading of the action and resource. Every word earns its place, with no filler or redundancy.

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

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

The tool is simple with no parameters and an output schema, and the description covers the purpose and return format effectively. However, the reference to searching 'by name or level' is unresolved given the empty schema, leaving a completeness gap regarding how filtering is supposed to work.

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 zero parameters, the baseline is 4, but the description misleadingly implies filtering by name or level without providing any parameter names or formats. The schema is empty, so the description adds little beyond what the schema shows and actively creates ambiguity.

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 searches D&D 5e spells by name or level, with a specific verb and resource. It distinguishes itself from the sibling get_spell by noting that it returns indices, names, and levels for later use with get_spell.

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 positions this tool as a precursor to get_spell ('for use with get_spell to fetch full details'), giving clear guidance on when to use this tool and when to use an alternative.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, covering safety. The description goes beyond annotations by specifying the return fields and the default focus on active subscriptions, which helps the agent understand the tool's output and behavior.

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

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

The description is concise, with two sentences that front-load the main purpose and return values, followed by a relevant usage note. No unnecessary fluff or repetition.

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

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

Given the low complexity (one optional parameter, no output schema), the description is complete: it explains what the tool does, what it returns, and when to use it. Annotations cover safety, and the schema covers parameters, so 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% for the only parameter (include_inactive) with a description. The tool description does not add additional meaning to the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and differentiates from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions. It also enumerates the returned fields, which adds purpose clarity.

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

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

It explicitly tells when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't name alternative tools directly, it clearly implies that adding or cancelling involves different operations, making the usage context strong.

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

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

Despite annotations being all false, the description adds rich behavioral context: rate-limited to 5 per identifier per day, free and not counted against quota, anonymous filing returns a claim_token, and later passing that token returns status and resolution details. It also mentions that the team reads daily and signal affects roadmap. No contradictions with annotations.

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

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

The description is a single dense paragraph but logically ordered: purpose, usage triggers, exclusions, token mechanic, rate limit. While every sentence adds value, the length is higher than strictly necessary and could benefit from bullet points for scannability. It is front-loaded with the core purpose, so it earns a strong score despite the paragraph format.

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

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

Given the simple tool with 4 optional parameters and no output schema, the description fully covers what the agent needs: when to use it, what to include, how to check a previous report, and operational limits (rate limit, quota). It explains the return token behavior that the missing output schema would otherwise leave unclear. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving general guidance on composing the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This is above baseline but not exhaustive, since type and context are already well-documented in the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly differentiates the feedback tool from siblings like ask_pipeworx or discover_tools. It names concrete categories (bug, feature, data_gap, praise) that map directly to the input schema enum.

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

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

Explicit when-to-use guidance is given for each feedback type ('Use when a tool returns wrong/stale data (bug)...'). It also states a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and tells the agent to file with the correct server otherwise. This is exemplary usage guidance, including how to disambiguate Pipeworx 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 readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: the data is self-aggregating, derived from CF analytics-engine, contains no PII, is cached for 5min-1h depending on window, and the output shape is (pack, tool, count). This goes well beyond the annotations and gives the agent an accurate 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 well-structured, front-loaded with the core function, then use cases, then data-source/caching details. It's slightly longer than strictly necessary but every sentence adds information; the bulleted use cases make it scannable.

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

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

For a read-only tool with a simple single-parameter schema, the description fully explains what is returned, the data source, the caching behavior, privacy characteristics, and why the tool is useful. There's no output schema, so the description's description of return contents is essential and sufficient.

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

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

The input schema fully documents the single 'window' parameter, including its enum values and the trade-off between shorter and longer windows. The description repeats the enum values but adds no additional syntax or formatting guidance, so it's at the baseline 3 for high schema coverage.

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

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

The description states a specific verb and resource: 'returns the top tools, top packs, and total call volume' for Pipeworx, based on what other AI agents are calling. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx, focusing on aggregate trending signals.

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 enumerates three concrete use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents. It provides strong context but does not name alternatives or state when not to use this tool, so it misses the full 'when-to-use vs alternatives' 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?

While annotations already state readOnly, openWorld, idempotent, and destructiveHint=false, the description adds valuable behavioral context: thresholds (>3pp signal, ≥0.30 Jaccard similarity, >20% placeholder fraction), that it returns null signals in certain cases, and a fill check that warns against trading when realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and modes. Every sentence adds necessary detail for a complex tool. It could be slightly more concise, but the length is justified by 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?

There is no output schema, so the description fully explains return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like placeholder filters and fill check realizability, making it complete for an agent.

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

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

Schema coverage is 100% and both event and topic parameters have descriptions, but the tool description adds significant meaning: it explains exactly what happens with each parameter (event walks child markets and checks ordering; topic flattens related events and runs comparator on union), includes example slugs, and describes output fields. This exceeds the baseline.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges (edge tracking) and polymarket_fill_risk (fill risk) by focusing on arbitrage via specific mathematical checks.

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

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

It provides explicit usage modes: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', or 'topic for a themed cross-event scan.' It also gives an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This satisfies the 'when/when-not/alternatives' requirement.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent) by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), diagnostic funnel counters, Fed candidate exclusion rationale, the 24h-move warning, placeholder-slug filters, and partition skip logic. No contradiction with annotations is present.

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

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

The description is front-loaded with the core purpose and uses all-caps section labels (TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) to structure detailed content. It is dense and every sentence carries information, but the inclusion of internal version details (e.g., 'Run 8') and exhaustive enumeration of model families makes it longer than necessary for tool selection.

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 (9 parameters, no output schema), the description thoroughly explains the output structure (by_segment, fed_candidates, _diagnostics), edge calculation, filtering logic, caching, and limitations. An agent has enough context to understand what to expect and how to invoke the tool correctly without 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?

The input schema provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The description adds some context by grouping knobs (e.g., 'tradeable-edge knobs drop opportunities where edge isn't realizable') but this is largely redundant with schema descriptions. It does not substantially enhance parameter understanding beyond the schema.

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

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

The first sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scan and return opportunities), and the differentiating data source (Pipeworx). The description further elaborates on the three output segments, making the purpose unambiguous and 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 a clear use case ('what should I bet on today') and gives guidance on adjusting tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and slippage. However, it does not explicitly state when NOT to use this tool or directly compare with alternative siblings like polymarket_arbitrage, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: snapshots are written on cache-miss so gaps indicate no scan, history is bounded by a 60-day TTL, decay is computed from daily closes not intraday, and edge_pp_net is signed (negative means SELL YES). It also warns that expired opportunities may be closed/resolved/arbed away. No contradiction with annotations.

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

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

The description is well-organized with labeled sections (Args, RESPONSE, LIMITS) and packs in essential operational details. It is longer than average but every sentence contributes either behavioral context or output/limitation info. A minor deduction for the slightly verbose explanatory asides ('wide for a reason nobody is willing to take') that are illustrative but not strictly necessary.

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

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

Given that there is no output schema, the description fully explains the response structure: tracked[] with time-series, trend categories, decay metrics; expired[] with lifespan; and snapshot_dates[] semantics. It also covers data gaps and TTL limits. This is a complete picture for an agent to select and invoke the tool correctly, even though the tool is relatively complex.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter defaults ('default 14, max 30', 'default 1wk') already present in the schema. It adds slight context by calling 'window' a 'snapshot family' and noting days limit, but this is minimal beyond structured schema coverage. No significant additional semantic value is provided.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly answers 'how long has this edge existed and is it shrinking?' and differentiates its temporal scope from the likely current-edge tool 'polymarket_edges' by emphasizing snapshot history. The verb 'track' and resource 'edge persistence/decay' are specific and unambiguous.

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

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

The description provides clear usage context: it explains that a fresh wide edge and a 3-week-old wide edge are distinct trading situations, implying when historical persistence matters. It also describes the snapshot mechanism and gaps, helping the agent reason about data availability. However, it does not explicitly name sibling tools as alternatives (e.g., 'use polymarket_edges for current edges'), so it falls short of a 5.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond this by detailing return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), mode-specific behavior ('walks the ladder', 'returns per-leg fill detail'), and failure modes ('thin_legs[]', 'forced_directional_risk'). This is rich behavioral context without any contradiction.

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

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

The description is lengthy, but every sentence is informative and the structure uses clear section markers (SINGLE-MARKET, BASKET, USE THIS) to organize information. It front-loads the core purpose and uses all-caps keywords for key phases. A slightly tighter edit could shorten it, but the density justifies its length for a complex two-mode 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?

There is no output schema, so the description must explain return values, and it does so exhaustively for both modes. It covers all four parameters, defaults, clamping, mode selection, outputs, and edge-case risks (partial fills, thin books, forced directional risk). Combined with the rich annotations, this description is fully capable of guiding 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?

Even though the schema covers all parameters, the description adds crucial mode-dependent semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S (shares per leg)' in basket mode. Side defaults and meanings are also clarified (auto default from partition sum). This significantly enhances what the schema alone provides.

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

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

Description opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket), and the verb 'check' plus resource 'order-book depth' makes the tool's function unambiguous. It also separates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit usage instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also gives required parameters (REQUIRES one of market or event) and explains when each mode is appropriate, plus the risk rationale for using it.

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

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

Annotations already indicate read-only and idempotent behavior, and the description adds substantial behavioral context: gross vs net spreads, unmodeled Kalshi fees, keyword-based matching rather than a shared resolution source, temporal alignment pitfalls, and why compatibility_warning can be non-empty even when pairs are returned. No contradiction with the annotations is present.

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

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

The description is long but front-loaded with the core purpose, then moves from modes to response shape to safety fields. It earns its length for a complex cross-venue matching tool, though it could be tightened without losing essential caveats.

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

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

There is no output schema, so the description carries the full burden of explaining return values; it does so thoroughly, covering spread fields, compatibility codes, temporal alignment, skipped/unclassified legs, low-confidence pairs, fees, and counters. Complex edge cases such as temporal_alignment_unknown and pairing_unverified are explicitly disclosed.

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 meaningful mode-level semantics, explaining that both modes run the identical token-overlap matcher and receive the same disclosures. It reinforces the override relationship between explicit parameters and topic-mapped sides, which goes beyond the schema text.

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 computes a cross-venue probability spread between Kalshi and Polymarket for the same resolving question, and explains its two modes. It is unambiguous about what the tool does, though it does not explicitly name or contrast sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description gives concrete guidance on when to use the topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairings, and warns that pre-mapped topics are frequently not tradeable. It does not explicitly say when to prefer sibling tools, but the context for choosing between the two modes is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond this: scoping to 'anonymous IP, BYO key hash, or account ID,' and the behavior of listing all keys when the key argument is omitted. This enriches the behavioral profile without contradicting the annotations.

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

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

The description is three sentences, each earning its place: the core action, the use case, and the scoping/pairing. It is front-loaded with the verb-object structure and contains 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 simple tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers purpose, usage context, data scoping, and relationships to sibling tools, leaving no significant gap for an agent to misuse 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining that the key is a 'previously saved via remember' memory key and providing concrete examples (user's target ticker, address, prior research notes). This contextualizes the parameter more richly than the schema alone.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb and resource, and distinguishes itself from siblings by explicitly naming remember and forget as complementary 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 guidance on when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and pairings: 'Pair with remember to save, forget to delete,' making the usage context 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 discloses that each returned event includes source, citation_uri, and raw payload, and that mark_read:true flags events as read so subsequent calls only show newer ones. This adds behavioral context beyond the annotations' readOnlyHint, idempotentHint, and destructiveHint, which are safe defaults. No contradiction between the description and annotations is present.

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

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

Three sentences deliver core purpose, return format, filtering, read-tracking, and an alternative API endpoint, with no filler. Each sentence adds distinct information, making it efficient 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 no output schema, the description compensates by describing the event structure (source, citation_uri, payload). It covers filtering, limit semantics (via schema), read state, and polling suitability, making it sufficient for an agent to use effectively.

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

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

The schema already describes all five parameters (100% coverage), but the description adds meaning by giving an example type 'sec_8k', clarifying that since expects an ISO timestamp, and explaining the effect of mark_read on subsequent calls. This enriches the parameter semantics beyond mere schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed', which clearly identifies the resource (subscription feed) and action (pull events). It distinguishes from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes) by specifying it returns alerts written by the evaluator to the 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 provides usage context by explaining that events can be filtered by type and since, and that mark_read controls what appears next. It also gives an alternative endpoint for scripts/dashboards, implying this tool is for interactive polling. However, it doesn't explicitly mention when to prefer this over sibling tools or when not to use it, so it's clear but not fully explicit.

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

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

Discloses parallel fan-out to multiple sources, fallback behavior (GDELT preferred, GNews on rate-limit/5xx), USPTO soft-fail due to API sunset, and return structure (changes[], total_changes, citation URIs). These details go far beyond the provided annotations, adding significant behavioral context.

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

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

Though lengthy, every sentence carries functional weight: example queries, source breakdown, fallback logic, since syntax, return format, and alternative recommendation. No filler or redundancy; well-structured and front-loaded with 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?

With no output schema, the description compensates by detailing the output shape (changes[] grouped by source, total_changes, pipeworx:// URIs) and notable edge behaviors (fallback, soft-fail). This makes the tool's behavior and results sufficiently clear for reliable 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 covers all parameters with descriptions, but the description adds practical guidance for 'since' (e.g., '30d' or '1m' for typical monitoring) and clarifies that the window applies across all data sources, providing extra value beyond the schema.

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

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

The description clearly states it's a change feed for a company over a time window, naming specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also explicitly contrasts with entity_profile for static profiles, making its purpose distinct from at least one sibling.

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 natural-language query examples ('What's new with X'), explains the time-window parameter ('since'), and explicitly directs users to entity_profile when static profile is needed, offering an alternative and when-to-use guidance.

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

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

Annotations already indicate idempotent, non-read-only, non-destructive. The description adds valuable context: storage as key-value pairs scoped by user identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond annotations to explain lifecycle and scoping.

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 front-loaded, starting with the core purpose, then usage, then storage details. Each sentence contributes meaningful information, and no word is wasted.

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

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

For a simple two-parameter tool with no output schema, the description covers all essential aspects: purpose, when to use, persistence behavior, scoping, and companion tools. It is fully sufficient 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 coverage is 100% and both parameters (key, value) are well-described with examples in the schema. The description does not add additional meaning beyond what the schema provides, making a baseline score of 3 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 reuse, using the verb 'save' and specifying the resource as key-value pairs. It also distinguishes itself from sibling tools by explicitly naming recall and forget for retrieval and deletion.

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

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

Provides clear 'when to use' guidance with examples (resolved ticker, target address, etc.) and mentions pairing with recall/forget as alternatives. It does not explicitly state 'when not to use', but the context is sufficient for an agent to decide.

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 important behaviors: ambiguous name matches return `figi_candidates`, unresolved identifiers are listed under `unresolved`, enrichment degrades gracefully when GLEIF/OpenFIGI are down, and identifier provenance is labelled per source. This gives the agent a strong model of edge-case behavior.

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

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

The description is front-loaded with examples and a clear usage directive, but the 'company' branch is a single sprawling parenthetical that packs many distinct behaviors into one hard-to-parse sentence. It would be more concise and scannable with bullets or shorter sentences.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. It covers return fields for both company and drug types, ambiguity handling, unresolved identifiers, input acceptance, and degradation behavior. An agent has enough context to invoke the tool correctly across the main scenarios.

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 still adds substantial value: it provides concrete value formats ('AAPL', '0000320193'), explains ISIN-to-LEI mapping, and warns against passing full noun phrases like 'NEW YORK ST DORM AUTH revenue bonds.' This goes well beyond the schema's simple field 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 resolves user-spoken names into canonical/official identifiers and enumerates supported types ('company', 'drug') with concrete examples. It does not explicitly distinguish itself from siblings like entity_profile, but the 'other tools require as input' phrasing establishes its role as a lookup utility.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also specifies when to use the company vs drug branches. However, it does not state when not to use this tool or name alternative tools for richer entity research.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description's burden is lower. It adds valuable behavior context: that it probes each entity, ranks by score, and returns confidence and signal density. It also reveals the internal dependency on ai_visibility_check, which is useful for understanding cost and behavior, though it doesn't discuss rate limits or the impact of the models parameter.

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: the first states the core capability, the second gives the use case and return value. Every sentence earns its place; there is no fluff or repetition.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description covers the what, why, and expected return (ranked list with score, confidence, signal density). It also explains the internal process (probes with ai_visibility_check and ranks by score). It could be slightly more explicit about how the models parameter changes behavior, but the schema already covers that detail.

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% — every parameter is already documented in the input schema, including the 'first entry treated as subject' nuance for entities. The description adds no new parameter-level semantics beyond what the schema provides, 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 opens with 'Compare AI visibility across multiple entities side-by-side,' a specific verb, resource, and scope. It clearly differentiates from the sibling ai_visibility_check by emphasizing multiple entities and side-by-side comparison, and from generic compare_entities by focusing on AI presence.

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

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

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It implicitly suggests the alternative of using ai_visibility_check for single-entity probes by naming it as the internal mechanism, though it does not explicitly state 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?

Beyond the readOnly/idempotent annotations, the description discloses the fan-out behavior, partial failure handling via sources_failed, and the 5-30s possible delay for bundlephobia's first measurement. It also enumerates the returned summary fields, which is valuable since no output schema exists.

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

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

The description is moderately long but every sentence carries essential information: purpose, use cases, output fields, and failure behavior. It is front-loaded and well-structured with em-dashes and a list.

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 detailing the return structure (summary block, advisories, links, alternative versions) and covering ecosystem limitation, timing, and graceful degradation. It is complete for a complex composite tool.

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

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

Schema coverage is 100% for both parameters, so the description adds little beyond the schema. It reinforces npm-scoped package acceptance and the version default, but those are already in the input 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, composite purpose: a single-call 'should I add this npm package' check covering deps.dev and bundlephobia. It lists concrete outputs (license, advisories, bundle size, etc.) and therefore is clearly distinguishable 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?

Explicitly states when to use: when the agent asks if a package is safe, popular, small, or what adding it costs. Also gives an exclusion for non-npm ecosystems, directing them to deps.dev:version directly.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds no contradictions. It discloses concrete mechanics: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and character offsets for quote verification.

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 'Semantic search INSIDE a fetched record.' Each clause adds value: function, use case, and implementation detail – no filler.

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

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

For a 3-param tool with no output schema, the description covers input requirements, output shape (passages with offsets and similarity), usage guidance, and technical constraints. The annotation set already covers safety and idempotency, so no gaps remain.

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

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

Schema descriptions cover all three parameters (text, limit, query) with max length, range, default, and example. The description adds only contextual guidance on what text to pass (SEC filings, articles) but doesn't go beyond the schema's parameter semantics.

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

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

The description opens with 'Semantic search INSIDE a fetched record' – a specific verb+resource statement. It distinguishes itself from sibling tools by framing it as a post-fetch operation that returns passages with offsets, rather than acting as a general ask 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?

It explicitly states 'Use when the record is too big to cram into the prompt' and explains context-saving benefits. It also names ask_pipeworx_grounded as a complementary tool, providing a clear alternative workflow.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds valuable context: OAuth requirement, inability to persist for anonymous/BYO, phone verification for SMS, 10/day cap, and always-on feed. It omits webhook delivery from the main description (though present in schema), so not a 5.

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

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

The description is long but well-structured, with front-loaded purpose and compact use of dashes and parentheses. Each sentence adds value, though it slightly repeats schema details (e.g., delivery channels). Efficient for the tool's complexity.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers types, delivery channels, account requirements, and return value. It omits webhook (with its one-time secret) and idempotency details, but these appear in the schema, so the description is largely complete.

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

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

Schema coverage is 100%, but the description adds rich examples and semantics: e.g., items:["5.02"] = officer change, Polymarket↔Kalshi mispricings, FRED series with series_id. It explains delivery channel options in behavioral terms, exceeding what the schema alone provides.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream.' It names specific resource (subscriptions) and differentiates from sibling tools like list_subscriptions, recent_alerts, and unsubscribe by focusing on creation and returning 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 gives useful context: requires OAuth, supports specific subscription types, and explains delivery via feed (pull via recent_alerts). However, it does not explicitly state when NOT to use this tool or directly compare with alternatives, so it's clear but not exhaustive.

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 beyond these by explaining the return structure (category-bucketed example questions with tool+argument shapes) and how omitting or providing the topic parameter changes the result. 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?

Although the description is lengthy, every sentence contributes value: it opens with common user queries, lists categories, describes the output format, gives invocation guidance, and names related tools. The structure is well-organized and front-loaded, making it dense but not wasteful.

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

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

Despite having no output schema, the description fully covers what the tool returns (category-bucketed example questions with exact tool and argument shapes) and how to tailor the call. It also situates the tool within the broader toolset, making it complete for an agent to decide when and how to use 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?

The schema description covers 100% of the single parameter, listing valid focus areas and the default cross-category behavior. The description reinforces this by providing concrete examples ('finance', 'pharma', 'betting') and explicitly stating 'Call with no arguments for the full spread, or pass `topic` to focus', adding a bit of practical meaning beyond the schema.

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

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

The description explicitly states the tool's function: it 'returns category-bucketed example questions' and is 'the onboarding entry point'. It clearly identifies the resource (Pipeworx) and distinguishes itself from siblings by naming meta-tools like ask_pipeworx, entity_profile, and compare_entities, with a directive to use it FIRST.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus via the topic parameter. It also lists alternatives (meta-tools) to learn about after onboarding, giving clear context for when this tool is appropriate.

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 (idempotent, non-destructive), the description adds crucial behavioral context: the row is deactivated not deleted, and historical events remain available via recent_alerts. It also discloses ownership enforcement, providing a complete safety profile.

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

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

Two concise sentences with the main action front-loaded. The first sentence states what and how, the second adds important caveats about ownership and soft-delete. No unnecessary words or repetition.

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

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

For a simple one-parameter tool with rich annotations, the description covers the core action, ownership rules, and the non-destructive consequence. It also connects to recent_alerts for post-cancellation behavior, making it complete without 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?

The schema already provides a full description of the id parameter ('Subscription id (uuid) returned by subscribe'), so the description adds no additional param-level detail. The description's 'by id' is redundant, but coverage is 100% so a 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 uses a specific verb ('Cancel') and resource ('subscription'), and clearly distinguishes from siblings like subscribe and list_subscriptions by stating what it does with a subscription by id. The soft-delete behavior further clarifies the exact action.

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

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

The description gives clear context: ownership is enforced and this deactivates rather than deletes, which implies when to use it (to cancel your own subscriptions) and what it doesn't do (delete records). However, it does not explicitly state when not to use it or mention alternatives beyond recent_alerts for historical events.

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. The description adds significant behavior: precise verdict vocabulary (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the error semantics distinction between could_not_verify and unsupported, the SEC EDGAR fast path vs grounded pipeline, and the requirement not to treat could_not_verify as evidence. It also warns that 'our LLM or source failed'.

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

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

The description is somewhat long but every sentence carries operational insight. It front-loads the trigger phrases and purpose, then packs returns, behavioral caveats, and efficiency benefits into a compact, well-structured block.

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

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

While there is no output schema, the description enumerates the exact verdict types, the response structure (verdict + value with citation + reasoning), and failure modes. It gives callers enough information to interpret results and handle errors, making it complete for a tool of this complexity.

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

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

Schema already documents both parameters (100% coverage). The description adds value by explaining tolerance_pct's use ('set 1–2 for hallucination detection') and default cap at 5, plus providing realistic examples for the claim parameter.

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 list of natural-language trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states it performs 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from siblings by describing its single-call design (replaces 4–6 sequential calls) and the two-tier routing for company-financial vs other claims.

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 whenever the agent needs to check whether something a user said is factually correct.' It also specifies the routing behavior for company-financial claims vs any other factual claim, and notes it replaces a multi-call pipeline. It doesn't name alternative tools, but the guidance is sufficiently clear for selecting this tool.

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