uooks

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 crucial behavioral context by revealing external API calls (Workers AI default, Anthropic when key passed), direct billing for Anthropic, and the exact output structure. This goes beyond the annotations without contradicting them.

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

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

The description is three compact sentences that front-load the purpose and output, then cover configuration, use cases, and cost. Every clause adds new information with no redundancy.

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

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

For a moderate-complexity tool with 4 params (1 required), rich schema descriptions, and no output schema, the description covers purpose, model options, output shape, cost, and ideal scenarios. An agent has sufficient grounding to select and invoke the tool correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by naming the default model (Workers AI Llama-3.3-70b), the 0-100 score range, and the BYO-key cost implication. These details complement the schema instead of merely repeating it.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs'), clearly stating it scores AI visibility (0-100) per model. It distinguishes itself from generic ask/research siblings by focusing on brand/topic visibility scoring with per-model output and explicit use cases.

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 names three concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model selection logic (default Workers AI, optional Anthropic with _apiKey). It doesn't explicitly say 'when not to use' or name alternative sibling tools, but the context is clear enough 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?

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description enhances transparency by revealing the internal routing mechanism (5,529 tools, 1,455 sources), stating that it returns structure with stable citations, and noting it works on every tier with one fast call. It does not contradict 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 dense but well-structured, front-loading the most critical instruction ('PREFER OVER WEB SEARCH') and then logically progressing through purpose, usage triggers, examples, and step-up alternatives. Every sentence adds distinct value, and the length is appropriate for a tool that serves as a default router.

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

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

For a tool with no output schema, the description explains return format (structured answer with citation URIs). It covers use cases, exclusions, alternatives, and operational characteristics (fast, every tier). Given the tool's broad scope, the description is remarkably complete and actionable.

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

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

The input schema provides descriptions for all six parameters (all aliases for 'question'), achieving 100% schema description coverage. The tool description does not add additional parameter-level semantics beyond what the schema already offers, but it does give illustrative example questions in the schema's examples array, which is adequate.

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: routes questions to the appropriate tool among 5,529 verified sources and returns structured answers with citation URIs. It explicitly states it is the default entry point and distinguishes itself from alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH' for a wide range of factual queries, and lists example phrasings ('what is', 'look up', etc.). It also specifies when to step up to alternatives ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part use deep_research'), making the decision process 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?

Beyond the annotations, it discloses that this is the experimental edge, that results are compared against the stable router, and that no candidate is currently active so behavior matches ask_pipeworx. This adds live-state and fallback context not present in annotations.

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

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

The description is four sentences and somewhat detailed, but each sentence provides relevant information about the beta state, candidate inactivity, and comparison workflow. It is front-loaded with the core identity and avoids irrelevant 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?

It explains the tool's relationship to ask_pipeworx, its current behavioral state, and its fallback behavior, which is sufficient for a read-only router with a fully documented schema. The absence of an output schema is mitigated by the explicit reference to the same response shape as ask_pipeworx.

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

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

Schema coverage is 100% and all aliases are documented in the schema, so the description does not need to repeat them. The phrase 'same arguments' adds a cross-tool equivalence but does not introduce additional 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 clearly states that this is a beta universal router identical to ask_pipeworx, with the same tools, arguments, and response shape. It differentiates it from the stable sibling by mentioning candidate routing improvements and the current inactive status.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and names the stable alternative. It also explains that when no candidate is active, the tool matches ask_pipeworx exactly, providing clear 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral traits: it routes across 5,529 tools, extracts answers only from tool results, returns an explicit refusal with specific reasons (not_in_source, no_tool_match, etc.), provides evidence quotes, and costs an extra LLM call. This is rich, actionable transparency.

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

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

The description is dense yet well-structured, front-loading the core purpose ('Hallucination-resistant answer mode for high-stakes reads') and then expanding with concrete details about behavior, return format, use cases, and cost. Every sentence adds value; no fluff or redundancy.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by detailing the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also covers when to use, when not to use, and the trade-off vs. the sibling tool. This is fully self-contained.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The description does not add parameter-specific semantics beyond the schema, but the overall behavior (filling arguments) is implied. Per the baseline for high schema coverage, this is adequate.

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 hallucination-resistant, grounded answering mode for high-stakes reads, with a specific verb ('answer') and resource ('Pipeworx'). It explicitly distinguishes itself from the sibling 'ask_pipeworx' by describing the extraction and refusal behavior, making its unique role in the toolset obvious.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusion: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This is exemplary usage guidance with a named 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?

The description discloses extensive behavioral details beyond annotations: parallel fan-out to category-specific data packs, the resolver contract (match_confidence, match_score, alternatives, suggestions), the parent_event extractor, news fallback fields, safety short-circuiting on low-confidence matches, closed-market handling, illiquid wide-spread warnings, and cancellation-rule risk. This far exceeds what readOnlyHint/openWorldHint/idempotentHint imply.

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

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

The description is long but every sentence provides actionable detail. It is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) that aid scanning. The purpose is front-loaded in the first two sentences, and the density 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?

With no output schema, the description fully compensates by detailing the response shape (result.market, result.analysis, result.evidence), resolver contract fields, parent_event structure, news fallback behavior, edge-case statuses (low_confidence_match, market_closed_or_inactive), and cancellation rules. It addresses conditions like wide spreads and 24h moves, making the tool safe to invoke correctly.

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

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

While schema coverage is 100%, the description enriches all parameters: `market` accepts slug/URL/question text with examples; `depth` is explained as quick vs thorough with consequences; `include_raw` is detailed with response size implications and when to pass true. The parameter semantics are greatly enhanced beyond the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like `polymarket_edges` (which likely scans many markets) and `ask_pipeworx` (general Q&A).

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing direct when-to-use guidance. However, it does not name alternatives or exclusions (e.g., 'for scanning many markets, use polymarket_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?

Beyond the readOnly/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA approvals), off-calendar fiscal year handling, result sorting by primary metric, and output structure (paired data + citation URIs). This is rich behavioral context that helps the agent predict the tool's actions and output. 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 well-structured: it front-loads trigger phrases and the core function, then gives usage guidance, type-specific details, and output characteristics. Every sentence adds value, though it is longer than the minimal two-sentence ideal, so it merits a 4 rather than a 5.

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 explaining that results are sorted by primary metric and that paired data plus citation URIs are returned. It covers data sources and edge cases (e.g., off-calendar fiscal years) adequately for the tool's complexity. It doesn't detail exact response structure or error conditions, but the level of completeness is appropriate.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning: it explains what data each 'type' value returns (10-K financials for company, adverse-event counts for drug), and clarifies the expected format for 'values' (tickers/CIKs vs. drug names) with examples. This goes beyond the schema's descriptions, 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 explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, with specific natural-language triggers like 'X vs Y' and 'which is bigger'. It clearly distinguishes itself from sequential lookups by emphasizing 'ONE parallel call', 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?

It provides an explicit usage rule: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' which gives clear when-to-use guidance. However, it does not name specific alternative sibling tools or state when not to use it, so it falls slightly 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 read-only, open-world, idempotent behavior, and the description adds substantial context beyond this: account/free-tier requirements, time expectations, gap[] handling (never invented), excerpting semantics, contradictions[], and resolvable citation_uri. 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 long, every sentence carries relevant operational detail. The account notice is front-loaded, and the content is densely packed with distinctions, constraints, and behavior. 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?

With no output schema, the description thoroughly covers return value structure ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation'), edge cases (gaps[], contradictions[]), timing expectations, and exceptions. This gives the agent all necessary context to invoke and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates and slightly elaborates on depth meanings (e.g., 'standard re-angles unanswered gaps') but adds no new parameter-level information beyond what the schema already documents.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with specific detail about decomposition and parallel routing. It also distinguishes itself from siblings by explicitly stating 'this is NOT open-web search' and comparing to ask_pipeworx.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes account requirements and non-signed-in fallback.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context by disclosing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotation baseline but could mention ordering or other edge cases.

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 ('Find tools by describing the data or task.') and then provides targeted usage and return details. The domain list is extensive but relevant and aids the search task. Every sentence serves a functional purpose with no filler.

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

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

There is no output schema, but the description adequately explains what will be returned: 'names, descriptions, and full input schemas' and that no second schema lookup is needed. It also clarifies when to use the tool ('Call this FIRST'). Given the tool's discovery nature, this is sufficient and complete.

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

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

Schema description coverage is 100%, and the schema already documents all parameters including aliases and examples. The description mentions 'top-N' which loosely corresponds to the 'limit' parameter, but it does not add parameter syntax details beyond what the schema provides. This matches the baseline of 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 clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and differentiates itself from siblings by being a meta-tool for browsing the available option set. The list of domains (SEC filings, financials, FDA drugs) further establishes its unique scope.

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

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

Provides explicit guidance: '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).' This implicitly tells the agent to use it for exploration and discovery, and not when a single answer is already known.

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, and the description adds substantial behavioral detail: it fans out across multiple sources, reports a patents API sunset with soft-fail behavior, notes GDELT→GNews fallback, and lists exact output fields. This 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 dense single paragraph but is front-loaded with user-phrase examples and prioritized usage guidance. Some redundancy exists (multiple paraphrase examples of 'tell me about X'), but every major piece of behavioral information earns its place for a complex multi-source 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?

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: cik, recent_filings, fundamentals, patents, news, and LEI are all enumerated. It also covers limitations, fallbacks, and source behavior, making it complete for an agent to set expectations.

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

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

The input schema already fully describes both parameters (type enum and value format), so the description adds little semantic meaning beyond examples like 'AAPL' and '0000320193'. The baseline of 3 applies because schema coverage is 100% and the description does not deepen parameter understanding.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call', with explicit verbs like 'profile', 'research', and 'brief me'. It differentiates from sibling tools by noting 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed.

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

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

The description explicitly says when to use the tool ('ALWAYS PREFER... when the user asks for a holistic view') and gives a clear alternative: 'Names not supported — use resolve_entity first if you only have a name.' This is strong when-to-use vs. when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. It adds context about the kinds of memories to remove (stale, sensitive) without contradicting annotations.

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

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

Three short sentences, each with a distinct purpose: action, usage, and tool relationships. No wordiness.

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?

Simple single-parameter tool with clear annotations and a complete description; it covers purpose, usage, and related tools, making it adequate for an agent to invoke correctly.

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

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

Schema description covers the 'key' parameter at 100%, and the description's 'by key' reinforces the parameter's role. No additional syntax or format details are needed beyond the schema.

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

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

The description opens with a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from sibling tools like remember and recall. It also explains the tool's role in the memory lifecycle.

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 ('when context is stale, task done, clear sensitive data') and references complementary tools (remember, recall), giving an agent clear decision 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context by explaining that it fetches the page, extracts specific elements, and outputs a single text blob in standard markdown format, which goes 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 three sentences, each serving a distinct purpose: what the tool does, how it works, and typical use cases. It is front-loaded with the core function and contains no 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 2-parameter read-only tool with no output schema, the description covers the essentials: purpose, process, output format, and use cases. It could mention potential limitations (e.g., page access issues) but is otherwise complete.

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

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

The input schema covers 100% of parameters with descriptions for 'url' and 'max_links'. The description adds high-level context (extracting links, output format) but does not provide additional parameter-specific semantics beyond what the schema already states.

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 precisely states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It also details the workflow (fetches page, extracts title/description/key links, emits markdown) and clearly distinguishes this tool from its siblings by focusing on llms.txt generation.

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

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

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 lacks an explicit list of alternatives or exclusions, but the context is clear enough for this unique tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by listing the specific return fields (name, birth_date, death_date, biographical summary, Wikipedia URL), which is useful behavioral context beyond the annotations.

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

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

The description is a single, well-structured sentence that immediately states the purpose, input, and expected outputs. No wasted words or redundant information, making it highly scannable for an agent.

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

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

The tool has one simple parameter, full schema coverage, and an output schema exists. The description notes the return fields, and the annotations supply safety semantics. Together, these provide complete context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with the property description 'Open Library author key (e.g., OL23919A)' already including an example. The tool description repeats the example ('OL23919A') but adds no new semantic meaning 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 uses a specific verb ('Fetch') and clearly identifies the resource ('author's profile from Open Library') and the required input ('author key'). It distinguishes itself from sibling tools like get_book and get_book_work by focusing on the author entity.

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

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

The description provides clear context on when to use the tool: when you have an author key and need profile data. It does not explicitly mention alternatives or exclusions, but the example author key reinforces the usage scenario. A minor gap is the lack of explicit guidance on when not to use it (e.g., for book lookups).

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds transparency about the specific returned fields, the 'subjects (up to 10)' limit, and the chaining opportunity to get_author, which goes beyond the structured annotations and provides useful behavioral context.

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

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

Two sentences, front-loaded with purpose, and every clause adds value: the lookup method, the input format, the returned fields, and a follow-up hint. 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?

For a simple single-parameter fetch tool with strong annotations and an output schema, the description is complete. It states the input condition, the output highlights, and a relevant follow-up. Nothing essential is missing.

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

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

Schema coverage is 100%, and the single parameter 'isbn' is already described as 'ISBN-10 or ISBN-13'. The description repeats this without adding new format constraints, validation rules, or edge-case guidance, so it adds minimal 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 a specific verb ('Fetch'), a specific resource ('Open Library edition details'), and the exact lookup key (ISBN-10 or ISBN-13). It differentiates from siblings like get_book_work (edition vs. work) and search_books (fetch by identifier vs. search) by specifying the input and the returned fields.

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: use this tool when you have an ISBN and need edition-level metadata. It does not explicitly name alternatives or exclusion criteria, but the ISBN-focused scope strongly implies when it should be used. Mentioning author_keys for follow-up get_author calls adds practical guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context: it explains what a 'work' represents (concept across editions), lists the returned fields, and notes the W-suffixed id format. While it doesn't disclose additional behavioral traits like pagination or error handling, the annotation coverage is strong and this added context is valuable.

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, each earning its place: the first states the core function, the second provides usage guidance, and the third explains the naming choice. No fluff or redundant repetition of schema details.

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

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

Given the low complexity (single required param), rich annotations, and presence of an output schema, the description is fully complete. It covers the tool's purpose, usage guidance, return fields, and relationship to siblings, leaving no meaningful gap for an agent to guess.

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

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

Schema coverage is 100%, with a clear description of work_id as the W-suffixed identifier. The description reinforces this with an example and the same W-suffix wording, but adds no new semantic information beyond the schema. Baseline 3 is appropriate because the schema already does the heavy lifting.

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 ('Fetch') and resource ('canonical Open Library work record'), clearly distinguishing it from sibling tools like get_book (edition-specific) and search_books (finding work IDs). It also explains the naming rationale to avoid collision with Crossref get_work, further clarifying its unique purpose.

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

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

Explicitly states when to use this tool and directs users to alternatives: 'Use search_books to find a work_id (the W-suffixed key); use get_book for a specific edition by ISBN.' This provides clear context and exclusions, making it easy for an agent to select correctly.

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

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

Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds value by disclosing the return structure (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are listed by default. This goes beyond the annotation hints and helps the agent anticipate the tool's output.

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 action verb 'List' and immediately specifies the resource and scope. It efficiently combines what it returns and when to use it, with no fluff or redundancy.

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

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

Given the tool's simplicity, one optional parameter, and no output schema, the description is complete: it states the action, the exact return fields, and the use cases. The absence of an output schema is compensated by listing the fields returned, giving the agent a full picture of what to expect.

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 single parameter include_inactive is fully described in the schema with 'Include cancelled subscriptions in the response (default false).' The description mentions 'active subscriptions' but does not add further semantic detail beyond the schema. Schema coverage is 100%, so the description provides no additional parameter insight.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It specifies the resource (subscriptions) and the scope (caller's own), and distinguishes from siblings by focusing on listing rather than creating or canceling. The returned fields are enumerated, making the purpose explicit.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies the alternatives (subscribe/unsubscribe) without explicitly naming them. There are no exclusions, but the guidance is direct and actionable.

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

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

Discloses several behavioral traits beyond annotations: returns a claim_token when filed without an account, allows later lookup with that token, is rate-limited to 5 per identifier per day, and is free (doesn't count against quota). These add meaningful context about side effects and constraints.

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 long single paragraph, but every sentence contributes important context (scope, usage, follow-up, rate limits, cost). It's front-loaded with the main purpose. Slightly verbose 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?

For a tool with 4 optional parameters, nested objects, and no output schema, this description fully covers the workflow: what to report, how to report it, claim_token mechanics, rate limits, and exclusions. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds valuable semantics for claim_token by explaining how to use it as a follow-up call, and clarifies the type enum values with examples (bug, feature, etc.), going beyond 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 it sends feedback to the Pipeworx team about broken, missing, or needed functionality, and explicitly distinguishes from other tools by noting it's only for this Pipeworx connection. The verb 'Tell' is specific, and the scope is unambiguous.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and when-not-to-use guidance (tools from other MCP servers), plus instructions for following up via claim_token. 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 declare readOnly, idempotent, openWorld, and destructiveHint=false, but the description adds substantial context: data source (CF analytics-engine), privacy (no PII), exact data shape ((pack, tool, count)), and caching behavior (5min-1h per window). This goes well beyond the annotations and informs the agent about lag, freshness, and response scope.

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 sized but well-structured: a compelling first sentence, a readable bullet-style enumeration of use cases, and a concise operational note on data provenance and caching. Each sentence contributes distinct information, though a few phrases (e.g., '24h, 7d, or 30d') redundantly echo the schema.

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 one optional window parameter and no output schema, the description fully accounts for what the agent needs: it names the return contents (top tools, top packs, total call volume), the window granularity, the data format ((pack, tool, count)), and the absence of PII. There is no significant ambiguity left for the agent to resolve.

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 sole parameter 'window' is fully described in the schema (100% coverage) with enum values and a tradeoff explanation ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description merely restates the window options in the first sentence and adds no new semantic meaning beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a configurable window, using the specific verb 'Returns' and identifiable resource ('what other AI agents are calling on Pipeworx'). It distinguishes itself from sibling tools like discover_tools by focusing on aggregate agent call behavior rather than individual tool discovery.

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?

An explicit 'Useful for' list provides three concrete scenarios (discovering hot data sources, confirming a canonical tool, checking alignment with agent needs), which gives strong context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it misses the full guidance bar for a 5.

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

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

Beyond the readOnlyHint annotations, the description details critical behavioral traits: the 3pp deviation threshold, the placeholder slug filter with >20% cutoff returning null, the skipped_low_similarity counter, and the fill_check logic that warns against trading when realizable_edge_pp ≤ 0. These are non-obvious behaviors that substantially affect how the agent should interpret 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 long but exceptionally well-organized. The first sentence states the core purpose, and subsequent sections are bolded (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for easy scanning. Every sentence adds actionable information; there is no fluff. The structure mirrors the tool's execution flow, making it easy for an agent to follow.

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 tool with no output schema, the description provides a thorough picture: it describes the response fields (opportunities[], partition_check{}, fill_check), explains edge cases (placeholder fractions, low similarity, thin legs), and even mentions a related tool for further sizing. This gives an AI agent enough context to invoke the tool correctly and interpret its 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?

Even though the schema already covers both parameters, the description enriches them significantly. It explains that event accepts slugs or full URLs, gives example slugs, defines topic as a seed question, and clarifies that no args triggers a trending scan. It also clarifies the semantic difference between event (single-event) and topic (cross-event) modes, which the schema only hints at.

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 method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three invocation modes (no args, event, topic) and gives concrete examples. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'pass topic for a themed cross-event scan'. It also recommends when to use each mode ('event (recommended for a specific market)') and points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk').

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 is exceptionally transparent about internal mechanics: model families, edge_pp_net after slippage, Kelly capping at 0.25, 24h-move warnings, tradeable-edge knobs, and diagnostics. It even discloses 1-hour KV-level caching. This far exceeds what the readOnlyHint/idempotentHint annotations provide and gives the agent accurate expectations for 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 very long, but every sentence adds substantive detail about model families, output segments, and knob interactions. It is front-loaded with the purpose and then dives into specifics. The lack of clear visual structure (single dense paragraph) prevents a 5, but the density 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?

Given the tool's complexity (9 parameters, three segments, no output schema), the description is remarkably complete. It describes the top-level response shape, explains why segments may be empty, and details the diagnostics funnel. The caching behavior and Fed-note caveat give the agent everything needed to invoke and interpret the result.

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

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

With 100% schema coverage, the baseline is 3, but the description adds meaningful cross-parameter semantics: it explains that min_kelly doesn't apply to partition arbs (which always return kelly_fraction_half=0), and that min_partition_leg_kelly operates per-leg. It also clarifies how max_spread_pp and min_liquidity act as 'tradeable-edge' filters. This goes beyond the schema.

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

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

The description opens with a specific action—'Scan top Polymarket markets and return opportunities'—and clearly identifies the resource (Polymarket) and the unique value proposition (Pipeworx data vs market price). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by framing itself as the 'what should I bet on today' discovery 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 provides clear context ('Built for "what should I bet on today"') and explains when opportunities are included/excluded (e.g., Fed bets surface but excluded from ranking). However, it does not explicitly name alternatives or state 'use this instead of X,' so it misses the explicit comparison that would earn 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing data nuances: snapshots are cache-miss-driven so gaps mean no scan that day, the 60-day TTL bounds history depth, and decay numbers are computed from daily closes not intraday. It also clearly states the trend calculation is on |edge_pp_net| and signed values indicate trade direction, giving critical behavioral insight.

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. It front-loads the core purpose, then uses labeled sections 'Args:', 'RESPONSE:', and 'LIMITS:' to structure parameter, return, and constraint details efficiently. This makes it easy to scan and parse despite its length.

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

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

With no output schema, the description fully explains the response structure: tracked[], expired[], and snapshot_dates[], including what each contains and why (e.g., median lifespan as a competition clock). It also notes limitations (TTL, cache-miss gaps, daily closes) that are critical for correct interpretation, 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 description coverage is 100%, so baseline is 3. The description restates parameters and their defaults ('days (lookback, default 14, max 30)', 'window (snapshot family, default "1wk")'), but does not add new semantics beyond what the schema already provides. It is consistent and correct, but not additive.

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

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

The description clearly states a specific verb+resource: it tracks edge persistence and decay from daily polymarket_edges snapshots. It answers a concrete question, 'how long has this edge existed and is it shrinking?', and differentiates itself from related tools like polymarket_edges by focusing on historical time-series rather than current values.

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

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

The description provides clear context for when to use the tool: when assessing whether an edge is fresh or old ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name sibling alternatives, but the 'built from daily polymarket_edges snapshots' phrasing implies it is the go-to for historical persistence analysis, which is sufficient contextual guidance.

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

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

Although annotations declare readOnlyHint=true and non-destructive, the description adds substantial behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced_directional_risk and thin_legs that could strand an arbitrage unhedged. 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-structured into SINGLE-MARKET and BASKET sections and is front-loaded with the core purpose, but it is quite verbose with many return fields and warnings. It is dense and valuable, though not as concise as it could be; still highly 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 carries the full burden of explaining return values, and it does so thoroughly: listing every return field for both modes (e.g., vwap_fill_price, capture_ratio, thin_legs[], max_clean_notional_usd). It also covers size semantics, mode selection, and failure modes, making it complete for a complex tool with two operational modes.

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

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

Schema coverage is 100%, but the description enriches each parameter beyond the schema: it explains the dual meaning of size_usd (max spend vs target proceeds in single-market; settlement notional per leg in basket), the default auto-selection for side in basket mode, and the required exclusivity of market vs event. This is substantial added meaning.

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

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

The description opens with a precise verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and the emphasis on fill risk differentiates it from sibling tools 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?

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial basket fills and why the check is necessary, giving clear when-to-use and why-not-to-skip guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it explains compatibility warnings, temporal alignment, skipped cross types, and when spreads are 'mathematically meaningless.' It discloses that the tool reports both matched and skipped pairs, and that pre-mapped topics often yield warnings. This goes well beyond the annotation hints.

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

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

The description is dense and long, but every sentence earns its place by explaining behavior, modes, safety fields, and caveats. It is structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) but lacks formal formatting. The length is justified for the tool's complexity, though it could be slightly more 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?

Given the tool's complexity and no output schema, the description thoroughly covers all necessary context: what it returns (leg-by-leg prices, spreads), what the safety fields indicate (compatibility_warning, temporal_alignment), and the failure modes (skipped_cross_type, skipped_cross_subtype). It also warns about the real-world tradeability, making it complete for an agent to understand when and how 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%, so the schema already documents each parameter, but the description enriches them by explaining the two modes ('topic' vs explicit tickers), how they override each other, and the exact shortcut values. It also clarifies the meaning of the response fields (spread, compatibility_warning, temporal_alignment, skipped_cross_type), adding depth that the schema alone doesn't provide.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs and resources, distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, and explains the two modes (topic shortcuts vs explicit tickers). This is a precise, non-tautological statement.

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

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

The description explicitly says when to use the tool: to measure spread between the same outcome on two venues. It also provides critical exclusion guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It explains the two modes and when to use explicit tickers, providing both context and caveats.

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

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

The description adds scoping behavior beyond the readOnly/idempotent annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also clarifies the optional-key listing behavior. No contradiction with annotations exists, and this context enriches the agent's understanding of the tool's operational boundaries.

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

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

Two sentences, each dense with purpose and context. The action is front-loaded, and every clause contributes value—no redundant phrasing or filler. It is an exemplary concise tool description.

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

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

For a simple 1-parameter memory lookup with strong annotations, the description covers purpose, usage, scoping, and sibling relationships in a compact space. No output schema exists, but the description clearly implies the return values (the value or the key list), 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% and the schema already documents the key property ('Memory key to retrieve (omit to list all keys)'). The description adds the contextual link to remember and forget, but no additional syntax or format details beyond what the schema already provides, so it only marginally enhances parameter understanding.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes it from the sibling tools remember and forget by defining its exact output behavior, leaving no ambiguity about what the tool does.

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 to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also frames the workflow with 'Pair with remember to save, forget to delete,' giving clear relational guidance on how it fits with sibling 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?

Adds substantial context beyond annotations: describes the payload structure ('source, citation_uri... raw event payload'), explicitly discloses that mark_read:true flags events read and affects subsequent calls, and notes the feed is persisted and also available via HTTP. This goes well beyond the readOnlyHint/idempotentHint annotations.

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

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

Three compact sentences: purpose, return contents, filtering, mark_read effect, and polling/alternative access. Every sentence earns its place, with no fluff or redundancy. Front-loaded with the core action.

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

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

Given no output schema, the description adequately explains what events carry and how filters work. It also covers side effects and alternative access. Missing details like pagination or default limit are already in the schema, so the overall context is sufficient for a read tool.

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

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

Schema covers all parameters (100%), but the description adds value with a concrete type example ('sec_8k'), clarifies that 'since' is an ISO timestamp, and explains the real-world consequence of mark_read (next call only shows newer ones). This enriches the schema descriptions, though limit and unread_only are not mentioned.

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

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

The description starts with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this tool from siblings like list_subscriptions or recent_changes by focusing on the persisted alert feed and the evaluator's events.

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

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

Provides clear usage context: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and explains mark_read behavior for polling. It also mentions an alternative endpoint for scripts/dashboards, effectively indicating when to use this tool vs. an HTTP feed, though it doesn't explicitly name sibling 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 readOnly/idempotent annotations, the description discloses fan-out to three external sources, fallback order (GDELT→GNews) with conditions, and the USPTO soft-fail due to the PatentsView sunset. These are non-obvious behaviors an agent needs to know.

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

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

The description is dense but well-structured, leading with usage examples, then return shape, then source details, parameter formats, and a sibling distinction. No filler; every sentence contributes.

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

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

Without an output schema, the description reliably describes the return contract and edge cases (fallback, sunset). It covers all three parameters, mentions supported entity types, and differentiates from entity_profile, making it self-sufficient.

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

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

While the schema already documents all parameters with 100% coverage, the description adds context: `since` formats (ISO vs relative) and that `value` accepts ticker or CIK. It also clarifies the `type` enum only supports 'company', reinforcing schema constraints.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with example phrasings that map to user intents. It explicitly contrasts with the sibling entity_profile tool, making it easy to distinguish when to choose this tool.

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

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

The opening lists concrete query patterns and states the tool does this 'in ONE parallel call', indicating efficiency. It includes explicit 'Use entity_profile instead...' for the static profile case, providing clear guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context beyond these annotations: persistence differences for authenticated vs. anonymous users and scoping by identifier. 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 compact and front-loaded, starting with the core purpose and then providing actionable usage guidance, scope, retention details, and companion tool references. Every sentence contributes meaningful information without redundancy.

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

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

For a simple two-parameter write tool, the description fully covers the lifecycle (save, retrieve, delete), persistence behavior, and usage examples. The schema and annotations are rich enough that no output schema is needed, and no critical context is missing.

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

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

Schema description coverage is 100%, with both key and value already well documented with examples. The description only restates the key-value model and gives examples already present in the schema, so it adds little semantic value beyond 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 uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), making the tool's function immediately clear. It also distinguishes itself from sibling tools by explicitly mentioning pairing with recall and forget.

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

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

The description gives concrete when-to-use guidance with examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the benefit ('so you don't have to look it up again'). It doesn't explicitly state when not to use it, but the context is clear and it references companion 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?

The description goes well beyond annotations by detailing the returned identifiers (CIK, ticker, LEI, FIGI, RxCUI), source labeling, explicit handling of unresolved identifiers, graceful degradation if GLEIF/OpenFIGI is unavailable, and the internal cascading of lookups. No contradiction with the readOnly/openWorld/idempotent 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 purposeful. The front-loaded example queries immediately convey intent, and the structured breakdown by supported types improves readability. It is longer than necessary, but for a tool that outputs complex identifier sets, each sentence adds value without redundancy.

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

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

Given the absence of an output schema, the description thoroughly explains return values, including identifier sources, the unresolved field, and graceful degradation behavior. It also covers edge cases like when a ticker is implied or when external services are unavailable, making the description 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?

While the schema already covers both parameters (type and value) at 100%, the description adds significant meaning: it explains accepted input formats per type (ticker, CIK, name for company; brand/generic for drug) and elaborates on the type-specific outputs. This is beyond the schema's basic descriptions, though not exhaustive enough for a 5.

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

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

The description clearly states the tool resolves user-spoken names into canonical/official identifiers, with concrete examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes this from sibling tools like compare_entities or entity_profile by emphasizing it provides the IDs other tools require as input.

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

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

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This establishes when to use the tool, and the examples imply when not to use it (when you already have the ID). However, it does not explicitly name alternative tools or state exclusions, 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 readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral detail beyond that: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also notes the first entity is treated as the 'subject', which is non-obvious and helpful for understanding 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 three sentences, with the core action in the first sentence and supporting details (how it works, use case, return value) in subsequent sentences. Every sentence contributes value: no fluff, no repetition of annotations, and information is front-loaded.

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

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

Given there is no output schema, the description adequately explains the return value ('ranked list with score, confidence, signal density per entity'). It also covers the use case, the number of entities (via schema, but the description implies N competitors), and the subject/competitor distinction. The tool's complexity is well addressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema already provides for parameters; for example, it mentions 'first entry treated as subject' but this is already in the schema. The description's reference to probing with ai_visibility_check indirectly maps to 'entities' but adds no new parameter detail.

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 ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from sibling tools like ai_visibility_check (which probes a single entity) and compare_entities (generic comparison). It also names the underlying probe mechanism and the output (ranked list), making the purpose unambiguous.

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

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

The description gives clear context: 'Useful for competitive AI-marketing audits' and an example query. It implies comparison across multiple entities, which differentiates it from ai_visibility_check, but does not explicitly state 'use this instead of X when...' or list exclusions. Thus it meets the 'clear context, no exclusions' bar.

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

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

The description discloses significant behavioral details beyond annotations: it fans out across multiple data sources, may have a 5-30s first-time delay from bundlephobia, degrades gracefully with partial failures, and includes 'sources_failed' to indicate timeouts. This complements the readOnly/idempotent hints and provides actionable expectations.

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 well-structured sentences: purpose, usage, and behavior. It front-loads the core function, includes examples, and covers failure modes without redundancy. Every sentence earns its place.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is complete: it lists return fields (summary block, advisories, links, alternative versions), explains the ecosystem limitation, and details failure handling and timing. The absence of an output schema is compensated by the explicit enumeration of returned data.

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 covers 100% of the parameters with clear descriptions (package name, optional version). The tool description does not add extra semantics about the parameters themselves, but it does imply that the package and version are used across the fan-out services. Baseline 3 is appropriate since the schema already handles parameter meaning.

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

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

The description clearly states the tool is a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. The specific verb ('check') and resource (npm package) are present, and the ecosystem scope ('NPM ecosystem only in v1') distinguishes it from sibling research 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?

It provides explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusions by stating that other ecosystems (PyPI/Maven/Cargo/Go) should use deps.dev:version directly, which serves as 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by specifying the returned fields (title, author, year, ISBN, cover image URL) and the discovery-oriented behavior. 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?

Three concise sentences, front-loaded with the action. Every sentence earns its place: what it does, what it returns, and when to use it. No redundancy or fluff.

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

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

For a simple search tool with two parameters and rich annotations, the description covers purpose, return fields, and usage context. It could be slightly more explicit about alternative tools, but the guidance is sufficient given the sibling list and output schema. A minor gap: it doesn't mention pagination or sorting, but those are likely covered by the output schema or are edge cases.

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 query and limit are well-described in the schema. The description does not add new parameter semantics beyond what the schema already states (e.g., search by title, author, or keywords repeats the query description). 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 function: 'Search for books by title, author, or keyword.' It specifies the verb (search), resource (books), and scope (title, author, keyword). It also distinguishes from siblings like get_book and get_author by framing this as discovery before fetching full details.

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 phrase 'Use this to discover books before fetching full details' gives explicit usage context, implying you should start here and then use a detail-fetching tool. It doesn't explicitly name alternatives (e.g., get_book) or state exclusions, but the guidance is clear enough for selection.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds significant extra context: it reveals the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and the 200K character cap with truncation flagging. These details go well beyond the annotation hints and clarify the tool's internal behavior.

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

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

The description is four sentences, each earning its place: it states the core function, gives usage guidance, explains the complementary tool, and specifies technical constraints. It is front-loaded with the main purpose and contains 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?

Despite having no output schema, the description explains what the tool returns (passages with character offsets and similarity scores), defines input limits (200K chars with truncation), and describes the intended workflow with ask_pipeworx_grounded. This gives a complete understanding of the tool's behavior and integration points.

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 full coverage with clear descriptions for all three parameters. The description adds value by giving concrete examples of the 'text' parameter (SEC 10-K body, article, long tool result) and clarifying the 'query' parameter as natural-language. However, it does not significantly enrich the 'limit' parameter beyond what the schema already states.

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

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

The description uses a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly explains the tool's function (search within user-provided text) and distinguishes it from sibling tools like search_books and ask_pipeworx. The output is also specified (top-N passages with character offsets and similarity scores), making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also explains how it relates to ask_pipeworx_grounded, describing a clear workflow: fetch with the gateway, then ground over relevant passages. This provides strong usage context and differentiates it from alternatives.

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

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

Beyond annotations, the description discloses account requirements, always-on feed behavior, SMS cap, webhook auto-disable after 10 failures, and one-time HMAC signing secret. These add significant operational context. There is no contradiction with annotations; readOnlyHint=false aligns with creation, and idempotentHint=true is not contradicted.

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 first sentence immediately states the action and return value, and every subsequent clause adds operational value (auth, type examples, delivery constraints, failure behavior). It is dense but not bloated — no filler sentences.

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

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

For a 3-parameter tool with a nested object and no output schema, the description plus schema fully cover required auth, type-specific parameters, channels, verification steps, limits, and webhook failure semantics. The return value is mentioned, and the one-time webhook secret flow is disclosed.

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

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

The input schema has 100% description coverage, including type-specific params and delivery channel details. The description adds a compact summary and examples, but largely restates what the schema already provides. Baseline 3 is appropriate because the schema carries the parameter-semantic burden.

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 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource that clearly separates it from sibling tools like list_subscriptions/unsubscribe. It also states the return value ('Returns the new subscription id'), which removes ambiguity.

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

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

The description gives clear context for when to use the tool: proactive monitoring, supported subscription types, delivery channels, and prerequisites (OAuth account, verified phone for SMS). It does not explicitly name alternatives such as list_subscriptions or recent_alerts for managing/reading subscriptions, so it stops short of full when/not guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: it returns category-bucketed example questions drawn from a live catalog, includes the exact tool + argument shape, and explains how omitting vs providing a topic changes the output. This gives the agent a clear model of the tool's behavior.

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

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

The description is front-loaded with example user prompts, then clearly states its purpose, output, and usage. Every sentence earns its place—there is no filler or redundancy. Despite being long, it is dense with useful information, structured logically from intent to behavior to invocation.

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?

Although there is no output schema, the description fully explains the return value (category-bucketed example questions with tool + argument shape) and gives sufficient context for an agent to invoke it correctly. Combined with the annotations and schema, this provides a complete picture 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 coverage is 100% for the single optional 'topic' parameter, and the schema already lists all allowed values and the omit behavior. The description provides examples ('finance', 'pharma', 'betting') but does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as the onboarding entry point for agents, stating it returns category-bucketed example questions with the exact tool and argument shape. It explicitly distinguishes itself from siblings by positioning it as the FIRST tool to use when unfamiliar with Pipeworx, unlike discover_tools or ask_pipeworx.

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

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

The description provides explicit usage instructions: 'Call with no arguments for the full spread, or pass topic to focus' and 'Use this FIRST when you do not yet know what Pipeworx can do for you.' This gives clear when-to-use context and differentiates from alternative tools like ask_pipeworx and discover_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 annotations (idempotent, non-destructive), the description discloses ownership enforcement, deactivation (not deletion), and the impact on historical events. These are significant behavioral details not present in the structured metadata, giving agents a fuller understanding of side effects.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence adds value without redundancy. It is 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 one-param tool with no output schema, the description covers purpose, access control, and data retention behavior. It is complete for the tool's complexity, addressing the key aspects an agent needs to know.

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 the parameter fully ('Subscription id (uuid) returned by subscribe'), and the description does not add additional semantic meaning beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes the tool from related siblings like subscribe and list_subscriptions by specifying the cancellation behavior. It also clarifies that the subscription is deactivated, not deleted, adding specificity beyond the title.

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 useful context for when to use this tool, such as the ownership constraint and the fact that historical events remain available via recent_alerts. However, it does not explicitly name alternative tools or give exclusion criteria, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds crucial nuances: the special meaning of could_not_verify (not evidence), unsupported (no source coverage), and the exact verdict set. This goes beyond the annotations and clarifies caller expectations.

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 long, every sentence earns its place: example triggers, usage rule, routing logic, return values, and special verdict semantics. It is front-loaded with purpose and structured logically from usage to outcomes. No fluff or redundancy.

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

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

With no output schema, the description fully explains return values (verdict options, citation, reasoning) and the meaning of exceptional verdicts. It also covers fallback behavior and error context (verification_error). For a tool with 2 params and 1 required param, this is complete and self-contained.

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 description doesn't need to explain parameters. It adds extra guidance on tolerance_pct, including the suggestion to set 1–2 for hallucination detection and the default cap of 5, which is not in the schema. This provides actionable meaning beyond the structured definition.

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 concrete example phrasings ('Is it true that…' / 'fact check') and a clear verb+resource: natural-language claim verification. It distinguishes itself from siblings by describing a consolidated pipeline that replaces 4–6 sequential calls, and by specifying the domain (company-financial vs. any other factual claim).

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and gives guidance on routing (SEC EDGAR fast path vs. grounded pipeline). It does not explicitly name alternative tools or when not to use, so it stops 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.