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 communicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it routes to 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and is described as one fast call, giving the agent a clear model of expected 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 longer than typical but every sentence serves a purpose: priority guidance, scope, examples, and escalation paths. It is front-loaded with the critical 'PREFER OVER WEB SEARCH' instruction and organized into scannable paragraphs.

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 and the tool handles a wide variety of queries, the description thoroughly covers what the tool does, what it returns (structured answer with citation URIs), when to use it, and when to choose alternatives. It even addresses breaking-news queries, leaving no major contextual gaps.

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

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

Schema coverage is 100%, and the schema descriptions fully document the primary parameter and its aliases. The description adds use-case examples but no additional parameter-level detail, so it meets the baseline without exceeding it.

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

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

The description immediately states the tool's function: answering factual questions by routing to thousands of verified sources. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, making its specific role clear.

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

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

Provides explicit 'when to use' guidance with trigger phrases, examples, and a 'START HERE' directive. It also gives exclusion/alternative guidance: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the description adds value by explaining the beta/experimental routing behavior, the live comparison against the stable router, and the current state (no candidate active). This goes 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 front-loaded with the core identity ('Beta version of ask_pipeworx') and then logically explains the current state, usage, and assurance of full functionality. It is slightly verbose with some redundancy ('identical' plus 'same tools' list), but every sentence contributes important context.

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 complex universal router with no output schema, the description is thorough: it specifies the tool count, argument parity, response shape parity with ask_pipeworx, the experimental comparison process, and the current matching state. This provides enough context for an agent to use it correctly and interpret results.

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

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

Schema description coverage is 100%, so all parameters are already documented as aliases for 'question'. The description mentions 'same arguments' but doesn't add any semantic detail beyond what the schema provides; baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router for natural language questions, and explicitly distinguishes it from the stable ask_pipeworx. It specifies the scope (same 5,529 tools, same arguments, same response shape) and the experimental nature, which separates it from siblings like ask_pipeworx_grounded.

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

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

Provides a clear when-to-use statement ('Use it exactly like ask_pipeworx when you want the newest routing') and names the alternative (ask_pipeworx for stable routing). It doesn't explicitly state 'when not to use' but the context makes it obvious that stable use goes to ask_pipeworx. The 'currently matches ask_pipeworx exactly' note adds useful guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals the refusal mechanism, output structure including evidence and confidence, possible refusal reasons, and the extra LLM call overhead. It also clarifies that extraction uses only tool result content, which is a key behavioral guarantee. 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 dense but every sentence earns its place: purpose, process, output format, refusal reasons, usage guidance, and cost trade-off. It is well-structured with a logical flow, and despite its length, 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?

For a tool of this complexity, the description covers all necessary context: what it does, how it routes, what it returns (including an explicit refusal contract), and when to use it over alternatives. The absence of an output schema is compensated by the detailed return format described in the text.

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 aliases for 'question.' The description does not need to add parameter-level detail beyond what the schema already provides. The baseline of 3 applies, as no extra semantic value is added for parameters.

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

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

The description opens with a precise, specific verb phrase: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from sibling ask_pipeworx by detailing the extraction process and naming the sibling directly. The purpose is unambiguous and not a tautology.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Provides a direct alternative preference: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost trade-off, giving clear decision-making criteria.

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

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

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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account and paid-plan requirements, the never-invented gaps[] guarantee, stable resolvable citations, semantic excerpting behavior, and latency expectations (15-60s/90s). It also details depth-specific behaviors like gap recovery and contradictions[]. This far exceeds the annotation baseline.

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

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

The description is a dense single block, but every sentence earns its place: account requirements, alternatives, mechanism, output format, exclusions, depth behavior, and latency. It is front-loaded with the critical account note and core purpose. Slightly verbose 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?

With no output schema, the description thoroughly explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field, and citation_uri. It covers usage, limitations, depth variations, and latency, making it exceptionally complete for a complex tool.

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

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

Schema coverage is 100% with rich descriptions of both params. The description adds the paid-plan context for depth:'thorough', reinforces 'Broad/multi-part is fine' for question, and clarifies what each depth level does behaviorally. While not revolutionary beyond the schema, it meaningfully supplements it.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition/routing mechanism. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the alternative for single lookups, making its purpose unmistakable.

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

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

The description explicitly says 'Best for broad/multi-part questions over structured data' and provides clear when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also instructs unsigned-in users to use ask_pipeworx. This is exemplary usage guidance.

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

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

Annotations already 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?

Annotations already declare read-only, idempotent, open-world behavior. The description adds valuable context beyond those: it discloses the fan-out across SEC, XBRL, USPTO, news, GLEIF, mentions the soft-fail for the sunsetting USPTO API, and describes the GDELT→GNews fallback. This goes beyond the hints 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 long but every segment earns its place: example triggers, core functionality, preference guidance, fan-out sources, return fields, and input constraints. It is dense and front-loaded with the key phrase 'full cross-source profile' early. Minor inefficiency remains due to the extensive list of examples, but overall it is well organized.

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

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

With no output schema, the description fully accounts for return values: cik, recent_filings with URIs, fundamentals with specific fields and sorting, patents with sunset note, news with fallback, and LEI. It also covers scope limitations (US public company, ticker/CIK only) and alternative tools, making it 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% with detailed descriptions for both parameters. The description reinforces and extends this by giving concrete examples ('AAPL', '0000320193'), explicitly stating names are not supported, and pointing to resolve_entity as a workaround. This adds practical value beyond the structured schema.

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

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

The description states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It includes multiple example queries and clearly distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-based 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?

Explicitly specifies when to use the tool ('when the user asks for a holistic view'), what to prefer it over (chaining single-pack lookups), and provides a named alternative ('use resolve_entity first' if only a name is available). This covers both when and when-not scenarios.

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

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

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?

Beyond the readOnly/openWorld annotations, the description discloses rich behavioral details: compatibility_warning triggers, temporal alignment significance, the logic of skipped_cross_type/subtype counters, and a blunt warning that pre-mapped topics often return warnings and are not tradeable. This level of transparency far exceeds what annotations alone convey.

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

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

The description is a single dense paragraph with long, run-on sentences and excessive detail about safety fields and counters. While front-loaded with a clear purpose, the rest is an unstructured wall of text that could be organized into bullet points or shorter sentences to improve scannability. It is far from concise.

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

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

Even without an output schema, the description fully specifies the response contents (leg-by-leg prices, matched spreads in pp, compatibility warnings, temporal alignment) and explains failure modes. It also gives realistic expectations about how often the tool is useful, making the tool's behavior fully predictable for an agent.

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

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

The schema already covers all three parameters, but the description adds critical meaning: how topic is a shortcut for a predefined set, how explicit kalshi_event_ticker and polymarket_event_slug override the mapped side, and example formats (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). This interaction logic is not present in the schema itself.

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, 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' precisely defines the tool's function and differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on single-venue strategies or edge detection. The explicit mention of two modes (topic and explicit ticker) further clarifies scope.

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

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

The description thoroughly explains when to use each mode (10 macro shortcuts vs. explicit pairings) and provides concrete conditions (e.g., matched_pairs:0 with skipped_cross_type>0) that indicate when the tool should not be trusted for arb. However, it never explicitly names alternative tools or states 'use X when...', leaving sibling differentiation only 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?

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 annotations (readOnly, idempotent), the description reveals cascading internal lookups, graceful degradation of LEI/FIGI enrichment, and explicit handling of unresolved identifiers. This adds 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?

The description is longer than average but front-loaded with examples and a clear purpose statement. Every section adds value, though the initial quote examples are somewhat repetitive.

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 steps in to explain return values: labelled identifiers, unresolved list, citation for drugs, and fallback behavior. It covers all necessary context for selecting and invoking the tool.

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

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

The schema already describes both parameters fully (100% coverage), so the description doesn't need to add much. It does enrich understanding by explaining how `type` influences the output (company vs drug) and gives input examples, earning a 4.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools. It distinguishes from siblings with 'Use FIRST whenever you have a name but need an 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?

Provides explicit usage guidance with 'Use FIRST whenever you have a name but need an ID' and lists example queries. It also notes it replaces 2-3 manual lookups, indicating the efficient context for use.

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

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

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.