Storting No

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 value by explaining the free default model, the BYO key cost pass-through, and the exact return structure, 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, front-loaded with the core purpose, followed by cost behavior and return format. Every sentence earns its place with no redundancy or filler.

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

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

The description covers purpose, parameter behavior, return structure, and use cases. It does not explain the confidence scale or what 'signals' contains, but for a read-only query tool with full schema coverage and good annotations, it is sufficiently complete.

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

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

Schema coverage is 100% with all four parameters described in detail. The description adds a small amount of context around _apiKey ('BYO key — you pay Anthropic directly') and the default model, but mostly restates schema information, so it stays at 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 ('Probe') and resource ('one or more LLMs') with a clear output (visibility score 0-100 per model). It clearly states the tool's purpose and differentiates it from generic search tools by emphasizing LLM knowledge and scoring.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains cost implications (free default vs BYO Anthropic key). It does not explicitly name alternative tools or state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds non-obvious behaviors: returns stable pipeworx:// citation URIs, works on every tier, is one fast call, and routes to the appropriate source. It does not contradict annotations and adds useful context beyond the structured hints.

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

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

The description is long but information-dense, front-loading the most critical instruction ('PREFER OVER WEB SEARCH') and then layering types, examples, and alternatives. Every sentence contributes to routing decisions or clarifies behavior. While it could be trimmed slightly, the structure is logical and the length is justified by the tool's broad scope.

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 routing tool with no output schema, the description covers the vast majority of what an agent needs: when to use, what it returns (structured answer + citations), how it handles news, and when to step up to alternatives. Minor gaps like behavior on no-match or error handling are not explicitly addressed, but the description is sufficiently complete for typical calls.

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

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

Schema coverage is 100% — the schema fully documents the single question parameter and its five aliases. The description provides natural-language examples that illustrate how to phrase questions, but does not add new semantic meaning beyond what the schema already specifies, so it meets the baseline for high schema coverage without adding much.

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 answers factual questions about real-world data by routing to 5,621 tools and returning structured answers with citation URIs. It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with different use cases, 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH', lists concrete question types and trigger phrases, says 'START HERE for most questions', and names specific alternatives with conditions (grounded for hallucination-resistance, deep_research for broad queries). This leaves no ambiguity about when to select this tool over siblings.

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. The description adds that this is an experimental edge with candidate routing improvements that may be active, and that currently no candidate is active, so it matches ask_pipeworx exactly. It also discloses it's a full working router, not a stub. No contradictions with annotations.

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

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

The description is front-loaded with the key fact (beta version of ask_pipeworx) and logically flows through current state, usage, and functional status. Each sentence adds value, with no wasted words.

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

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

For a tool that is a beta variant of a stable sibling, the description adequately covers purpose, current state, usage, and functionality. It references the stable router for response shape and tools, which is sufficient given the sibling exists. No output schema is needed because the response shape is shared.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description does not add per-parameter semantics beyond confirming 'same arguments' as ask_pipeworx, which is redundant given the schema. 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 this is a beta version of ask_pipeworx, a universal router for 5,621 tools, and distinguishes it from the stable sibling by its experimental routing improvements. It also clarifies that it currently behaves identically to ask_pipeworx, so an agent can tell it apart from ask_pipeworx and ask_pipeworx_grounded.

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

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

The description explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives clear when-to-use guidance and implies the alternative (stable ask_pipeworx) for non-experimental needs.

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, but the description adds critical behavioral details: it makes an extra LLM call, extracts answers only from tool result, returns a structured response with evidence and refusal reasons, and handles data truncation. No contradictions with annotations.

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

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

The description is dense but well-structured, front-loading the core value proposition and then detailing behavior, usage, and cost. It's longer than a typical description but every sentence adds value. Minor deduction for length, though it earns its space.

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

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

Given no output schema, the description fully explains return values (answer, evidence, confidence, refusal reasons) and handles edge cases (refusal when data doesn't answer). It also covers cost and alternatives, making it complete for an agent.

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

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

Schema coverage is 100% and the schema already documents the aliases. The description adds no parameter-level detail beyond what's in the schema; it only mentions 'question' indirectly. Baseline 3 is appropriate given full schema coverage.

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

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

States a specific verb ('extracts the answer') and resource ('tool result') with a clear differentiator: hallucination-resistant for high-stakes reads. Explicitly contrasts with ask_pipeworx by highlighting evidence extraction and refusal handling, making it distinguishable without reading the sibling's description.

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 ('whenever an answer will be quoted, cited, or acted on...') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), including a cost tradeoff note (one extra LLM call). This is exemplary routing 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/reference, and the description adds extensive behavioral context: status codes (low_confidence_match, market_closed_or_inactive), tradeability warnings, resolution-rule parsing, news fallback behavior, and the resolver contract. It also warns about suppression of analysis fields on low confidence, which is beyond annotation 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?

Though long, the description is well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK) and front-loaded purpose. Each section adds distinct operational knowledge, but the length may exceed what's needed for a quick reference.

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 documents result.market, result.analysis, result.evidence, resolver match fields, parent_event, and news fallback fields. It also covers edge cases (closed markets, wide spreads, cancellation rules), making it very complete for a complex research 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 100% of parameters with detailed descriptions; the tool description doesn't add param syntax beyond the schema, but it does contextualize the market param with examples and explains how the fan-out uses it. Baseline 3 is appropriate since the schema is self-sufficient.

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?

Purpose is explicit: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug/URL/question text) and outputs (evidence packet + market-vs-model comparison), clearly distinguishing it from sibling tools that focus on arbitrage or edge tracking.

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

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

Provides explicit use cases ('Use for "should I bet on X"...') and gives detailed fan-out examples by category. However, it doesn't name alternative tools for when-not-to-use scenarios beyond implying this is for single-bet research.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses specific behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). This significantly augments the annotations with concrete implementation context.

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

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

The description is information-dense yet well-structured. It front-loads the most common query patterns, then provides a clear preference directive, followed by type-specific behavior and output summary. No unnecessary words; every sentence adds value.

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

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

Given there is no output schema, the description adequately covers return values (paired data + citation URIs). It also covers both entity types, edge cases (off-calendar fiscal years), and scalability (replaces many lookups), making it fully complete for this 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?

The input schema already covers both parameters well (type with enum, values with min/max and examples), providing 100% coverage. The description adds semantic depth by explaining what each type actually retrieves (e.g., 'company' pulls 10-K financials, 'drug' pulls FAERS counts), which enriches parameter understanding beyond the schema descriptions.

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

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

The description explicitly states what the tool does: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides clear query patterns ('Compare X and Y', 'rank these companies') and distinguishes itself from sequential single-pack lookups, making it distinct from siblings like entity_profile.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies the appropriate context for each type (company vs drug) and implies when not to use it (for single entity lookups). This directly addresses alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds rich behavioral context: parallel routing via 5,621 tools, findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], second-hop iteration logic, semantic excerpting, and expected latency. No contradiction with annotations; adds substantial depth beyond them.

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

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

The description is long but densely informative. It front-loads critical account info and immediately clarifies scope. Every paragraph contributes (use cases, exclusion, iteration, citation guarantees, excerpting, latency). While verbose, it's well-structured and each sentence adds value; not redundant.

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

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

Given the tool's complexity (5,621 tools, parallel routing, no output schema), the description explains return format, gap handling, contradictions, citation resolution, and limitations. Covers latency, account tiers, and depth behavior. An agent has enough to call it correctly and interpret results.

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

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

Schema coverage is 100% with detailed descriptions for both depth and question. The description goes beyond the schema by explaining depth semantics (gap recovery, contradictions scan, timing trade-offs) and giving examples of suitable questions. It clarifies what each depth value does operationally, which is not fully captured in the enum descriptions alone.

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

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

States a specific verb and resource: 'grounded multi-source research across Pipeworx's 1472 STRUCTURED data sources' in one call, with decomposition and parallel routing. It clearly distinguishes from sibling ask_pipeworx by explicitly noting it is NOT open-web search and contrasting use cases. Unambiguous about what it 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?

Provides explicit when-to-use ('broad/multi-part questions over structured data') and when-not-to-use (single lookup → ask_pipeworx; breaking/current news → ask_pipeworx). Also states account requirements and depth-tier implications. No ambiguity about selection among siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and each result is ready to call directly with no second schema lookup. This sets expectations about output format and efficiency.

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

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

The description is four sentences, each earning its place: function, use cases, return-value details, and strategic advice. It is front-loaded with the verb phrase 'Find tools' and avoids fluff. Slightly longer than the TDQS 4.3 example, but the added detail about ready-to-call results and 'call first' guidance is valuable, so a 4 is fair.

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 well by explaining exactly what the tool returns (top-N tools with names, descriptions, full schemas, curated examples) and the practical implication (each result is callable directly). It also embeds usage context and examples in the schema, making the tool self-sufficient for an AI agent.

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

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

Schema description coverage is 100%, with clear parameter descriptions for query and limit, plus aliases (q, task, search, description). The description text itself doesn't add much parameter-level meaning beyond what the schema already provides; it reinforces that queries are natural-language descriptions but doesn't go deeper. Since the schema carries the burden, a 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly states the tool discovers tools, and the long list of domains (SEC filings, FDA drugs, FRED data, etc.) further clarifies scope. This uniquely positions it among siblings as a meta-search/discovery tool, distinguishing it from task-specific tools.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' for the listed domains, and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and a decision heuristic, though it doesn't explicitly name alternative tools or state when not to use it.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds behavioral specifics: fans out across SEC EDGAR, XBRL, USPTO, GDELT→GNews fallback, and GLEIF; notes the USPTO PatentsView API sunset May 2025 with soft-fail; and returns a structured set of fields including up to 5 recent filings with URIs. 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 not bloated; it compresses a multi-source aggregation behavior, examples, constraints, and return fields into a single paragraph. Some introductory example phrases could be trimmed, but the length is justified by the tool's complexity. It remains organized and ends with a critical constraint.

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

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

Despite lacking an output schema, the description enumerates all key return components (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and details specifics like 'LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'. It also covers accepted inputs, fallback behavior, and a prerequisite (resolve_entity). This is thorough for a complex profile 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%; both parameters are fully described in the schema with examples. The description reiterates that value accepts a ticker or zero-padded CIK and that names are not supported, but adds little beyond the schema. A baseline of 3 is appropriate since the schema carries the load.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' with example queries like 'research Acme' and 'brief me on Tesla'. It distinguishes itself from siblings by explicitly saying to prefer it over chaining single-pack SEC/XBRL/news lookups when a holistic view is needed, and contrasts with resolve_entity for name-only inputs.

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 when the user asks for a holistic view, and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It also says to use resolve_entity first if only a name is available, and specifies accepted inputs (ticker or CIK). This clearly states when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds a valuable behavioral detail: '?format=json is added automatically' and instructs users not to include format in params. This goes beyond annotations but is not a rich behavioral disclosure.

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 short sentences, front-loaded with purpose, and includes necessary examples and caveats without any waste. Every sentence contributes meaningful information.

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

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

The description covers purpose, usage scenarios, examples, and the automatic format inclusion. Since there is no output schema, it could have offered a bit more on return values, but the tool is a generic fallback and the description is adequately complete for its scope.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by providing examples of resource names and params (e.g., {sesjonid}), and by clarifying that format should not be included in params. This enhances understanding beyond the schema.

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

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

The description clearly identifies the tool as a generic fallback to any data.stortinget.no/eksport resource, with concrete examples (moter, komiteer). It distinguishes itself from sibling tools by explicitly stating it is for endpoints without a dedicated tool.

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

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

The description explicitly states when to use the tool: 'Use for endpoints without a dedicated tool.' This implies that if a dedicated sibling tool exists, it should not be used. It does not explicitly name alternative tools, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which cover the core behavioral traits. The description adds the context that it clears 'sensitive data the agent saved earlier,' which is useful, but no additional side effects or limitations are disclosed. 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 two sentences, front-loaded with the primary purpose, followed by usage guidance. Every sentence adds value with no redundancy.

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

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

For a simple one-parameter destructive tool with no output schema, the description sufficiently covers purpose, usage, and pairing with related tools. The absence of return value details is acceptable given the tool's simplicity and the provided annotations.

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

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

Schema coverage is 100%, and the description of the 'key' parameter in the schema ('Memory key to delete') already provides clear semantics. The description reinforces 'by key' but adds little beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb ('Delete'), identifies the resource ('memory'), and distinguishes it from sibling tools like 'remember' and 'recall' by focusing on deletion.

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

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

Provides explicit conditions for use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' This gives clear context for when the tool is appropriate, though it doesn't explicitly mention when not to use it.

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

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

The description adds context beyond the annotations: it explicitly mentions fetching the page, extracting title/description/key links, and emitting the standard llms.txt markdown format. It also states the output is a single text blob, which complements the readOnly and idempotent hints. 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 sentences deliver purpose, process, output, and use cases without redundancy. The description is front-loaded with the primary function and each sentence adds value.

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

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

For a simple 2-parameter tool with strong annotations and no output schema, the description adequately covers what the tool does, how it works, and what it returns. It could mention error cases or limitations, but these are not critical for this straightforward tool.

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

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

Schema description coverage is 100%, so the schema already fully explains both parameters. The description does not add additional meaning for url or max_links beyond what is in the schema, hence the baseline score.

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

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

The description states a specific verb ('Generate') and resource ('llms.txt file for any URL'), and explains the process (fetches page, extracts title/description/key links, emits standard format). This clearly distinguishes it from siblings like ai_visibility_check by focusing on generating the file itself.

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

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

The 'Useful for' section provides clear use cases (client indexing, own project, competitor audit). However, it does not explicitly mention when not to use it or name alternatives such as ai_visibility_check, so it lacks exclusion guidance.

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

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

The description adds concrete behavioral details beyond the annotations, specifying the return structure (saker_liste with sakid, titles, emne_liste, and status) and the session scope. This complements the read-only and idempotent hints with practical information.

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 and resource, and every word contributes meaning. No redundant phrases or filler.

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

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

For a single-parameter list tool with full schema descriptions and safety annotations, the description sufficiently covers the purpose, scope, and return format. No output schema exists, but the description fills that gap adequately.

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

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

Schema coverage is 100% with the sesjonid parameter fully described including an example and cross-reference to get_sessions. The tool description adds no new parameter information beyond 'for a session,' so it meets the baseline but provides no extra value.

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

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

The description clearly states the tool lists parliamentary cases/bills ('saker') for a session, with a specific verb and resource. It distinguishes itself from sibling tools like get_votes and get_sessions by naming the exact resource type and session context.

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 implies usage for retrieving cases by session, and the parameter description instructs users to get valid session IDs from get_sessions. However, it does not explicitly exclude other tools or provide when-not-to-use guidance, though the context is clear.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context by defining what the returned fields mean (e.g., 'currently represented') and providing example IDs, going beyond the annotations.

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

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

The description is two short sentences, front-loaded with the action, and includes just enough detail (examples and field explanations) without extraneous text.

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 zero-parameter list tool, the description fully covers purpose, scope, and return fields. The absence of an output schema is compensated by describing the fields. 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?

The tool takes no parameters, so schema coverage is complete. The description adds value by explaining the semantics of the output fields, which is helpful for interpreting results.

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 lists all political parties known to Stortinget and specifies the returned fields (id, navn, representert_parti). This distinguishes it from sibling tools like get_representatives that focus on people rather than parties.

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 implies the tool is for retrieving the full list of parties, but it does not explicitly compare with alternatives or state when not to use it. Since the purpose is so specific, usage is inferred, but no exclusion criteria are given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds context by specifying the scope (4-year period) and return fields. This is sufficient for a read-only, idempotent data retrieval tool; no contradictions.

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

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

Two sentences with clear, front-loaded wording. No redundant or filler content; every word adds value.

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

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

The description is adequate for a simple read-only list tool with one parameter. It discloses the return fields and scope, and no output schema exists so listing fields is helpful. Minor omissions like sorting or limits do not detract significantly.

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

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

Schema coverage is 100% with the parameter description already providing context. The description mentions '4-year electoral period' which aligns with the parameter but adds little beyond the schema. 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 verb 'List' and the resource 'members of parliament' with a specific scope ('for a 4-year electoral period'). It distinguishes itself from siblings like get_parties or get_votes by focusing on representative data.

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 implies the tool is used for retrieving MPs for a given electoral period, but it does not explicitly mention when not to use it or point to alternative tools. Usage context is present but no exclusions or alternatives are stated.

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, so the read-only nature is covered. The description adds behavioral context beyond annotations: the session period ('runs ~Oct–Sep') and the id format ('like "2023-2024"'), which help the agent understand the return value structure.

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

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

The description is two sentences: the first states the core purpose, the second adds essential usage context. Every sentence carries meaningful information with no redundancy or fluff.

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

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

This is a simple, zero-parameter read-only tool with rich annotations. The description provides the domain (Stortinget), the id format, and the relationship to other tools ('sesjonid'). Together with the annotations, this gives the agent enough 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?

The tool has zero parameters, so the input schema is empty and the baseline is 4. The description adds value by explaining the output id format, which is relevant for using the result with other tools. No parameter explanation is needed.

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 Norwegian Parliament (Stortinget) sessions.' This uses a specific verb ('list') and resource ('sessions'), and the mention of session ids and their format distinguishes it from sibling tools like get_cases, get_votes, and get_representatives.

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 the returned ids as sesjonid for other tools.' This informs the agent when to use this tool (before other session-dependent tools) and why it is the appropriate entry point. It does not explicitly name alternatives, but no direct sibling alternative exists, so this is sufficient.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by explaining the granularity of the result (per representative) and the possible vote options (for/against/absent), which is useful given the lack of an output schema.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains no redundant or unnecessary information. Every word adds value.

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

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

For a simple tool with one parameter and comprehensive annotations, the description adequately conveys what results the agent will receive. It does not specify the exact response structure (e.g., list vs. object) but is sufficient for the tool's low 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?

The input schema fully documents the parameter 'voteringid' as a numeric vote id from get_votes. The description reiterates this but adds no extra semantic nuance beyond the schema's description, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: retrieving per-MP results for a single vote, specifying the exact data (for/against/absent). It distinguishes itself from the sibling get_votes tool, which presumably lists votes, by focusing on one vote's breakdown.

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 instructs the agent to pass a votering id from get_votes, establishing a clear prerequisite and chaining with the parent tool. However, it does not explicitly mention when not to use this tool or present alternative tools for similar needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful return-structure context (sak_votering_liste with votering ids) and the relationship to a sibling tool, providing value beyond annotations without contradicting them.

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

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

Two sentences, front-loaded with purpose, no filler. Every sentence adds value: purpose, return structure, and next-step guidance.

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 one-parameter list tool with strong annotations, the description is complete. It explains the return value, the source of the parameter, and how to use the result with a sibling tool. No output schema exists, but the description compensates by clearly describing the output structure.

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

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

Schema coverage is 100% and the parameter description 'Numeric case id (sakid) from get_cases' is already clear. The tool description itself adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('List') and resource ('votes held on a single case'), clearly distinguishing this from siblings like get_cases (case list) and get_vote_result (per-MP breakdown). It also specifies the output structure (sak_votering_liste) with votering ids.

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 implies when to use this tool (when you need votes for a case) and mentions the follow-up tool get_vote_result for per-MP breakdown, offering clear workflow context. However, it does not explicitly state exclusions or alternatives, so it falls short of a 5.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive. The description adds useful context by listing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifies it returns only the caller's subscriptions. No contradiction.

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

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

Two sentences, front-loaded with the core purpose, and every sentence adds value: the first states what it does and returns, the second explains when to use it. 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?

This is a simple read-only tool with one optional parameter. The description covers the purpose, return fields, and typical usage scenarios, making it fully self-contained even without an output schema.

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

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

The single parameter include_inactive is fully described in the schema (100% coverage). The description's mention of 'active subscriptions' implicitly relates to the parameter, but it adds no new syntax or behavior beyond the schema's own description.

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

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

The description opens with 'List the caller's active subscriptions,' a specific verb+resource that clearly states the action. It also distinguishes from siblings like subscribe/unsubscribe by focusing on listing existing subscriptions.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call this tool versus alternatives like subscribe or unsubscribe.

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

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

Despite annotations providing no safety signals (all false), the description discloses key behaviors: filing returns a claim_token, rate-limited to 5 per identifier per day, free, and doesn't consume quota. It also reveals that the team reads digests daily and feedback affects roadmap, adding context far beyond the structured fields.

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

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

The description is longer than average but every sentence contributes: purpose, usage rules, exclusions, token mechanics, rate limits, and quota impact. It is front-loaded with the primary purpose and logically structured, though it could be slightly tightened without losing value.

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

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

For a tool with no output schema and four parameters, the description fully covers the expected behavior, return semantics (claim_token), constraints, and exclusions. It even warns against pasting end-user prompts, covering an important edge case. 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 coverage is 100% with rich per-parameter descriptions, so the baseline is high. The description goes further by explaining the claim_token lifecycle in detail—how to use it later to check status—and specifying message length (2000 chars). This adds meaning beyond the schema, especially for the claim_token parameter.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by framing it as feedback about Pipeworx tools themselves, not data querying or 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?

Explicit when-to-use guidance covers four feedback types (bug, feature, data_gap, praise) with concrete examples. It also states a firm when-not-to-use exclusion: any tool not served by this Pipeworx connection, and directs users to the correct server. 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that the data is 'derived from CF analytics-engine', contains 'no PII', and is 'cached 5min-1h depending on window.' This adds meaningful context about data provenance, privacy, and freshness. No contradiction with annotations.

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

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

The description is front-loaded with a clear summary sentence, then a numbered use-case list, and ends with two sentences about data source and caching. Every sentence serves a purpose, but it is slightly more verbose than the minimal two-sentence ideal.

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

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

Although there is no output schema, the description adequately states what will be returned (top tools, top packs, total call volume) and the aggregated shape ('pack, tool, count'). It also covers caching and data origin, making the tool usable without further assumptions.

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 only parameter, `window`, is fully documented in the input schema with enum values and an explanation of short vs. long window semantics. The tool description merely repeats '24h, 7d, or 30d' without adding new information beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description opens with a clear one-liner ('What other AI agents are calling on Pipeworx right now') and explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This is a specific verb+resource with scope, and the trending-aggregation focus clearly distinguishes it from siblings like 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 'Useful for' list explicitly provides three concrete scenarios: discovering hot data sources, confirming a canonical tool choice, and checking alignment with agent needs. This is clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, but the description goes far beyond by disclosing thresholds (deviations >3pp), the fill check behavior with 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it', the partition filter with '>20% placeholder fraction return null arb signal', and the semantics of skipped_low_similarity. This adds rich behavioral context without contradicting the annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides necessary information for correct invocation, with no filler. It is slightly verbose, but the complexity of the tool (multiple modes, thresholds, response format) justifies the length. A 4 reflects that it is not as concise as a two-sentence description but is efficient for its scope.

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

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

Despite having no output schema, the description thoroughly covers the response structure ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)') and the event-mode partition_check fields. It also covers edge cases (fill check, placeholder filters, similarity thresholds) and the relationship to sibling tools. Given the tool's complexity, this description is complete enough for an agent to invoke it correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains the difference between event and topic modes with examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), describes what each mode does (walks child markets, searches related events), and provides guidance on when to use each. This goes far beyond the schema's bare explanations.

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 and informative statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states the verb (find), resource (Polymarket arbitrage opportunities), and method, distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk. The detail about modes (trending_scan, event, topic) further clarifies its unique scope.

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

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

The description explicitly defines when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends a specific mode ('event (recommended for a specific market)') and differentiates between single-event and cross-event modes. It also references an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), giving clear usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response segmentation with diagnostics funnel counters, and the specific gate logic for structural arbitrage placeholders. It also discloses a limitation (Fed signal unreliability), providing deep transparency beyond the structured fields.

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

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

The description is an extremely long, dense paragraph with many parentheticals and all-caps headers. While the information is relevant, it exceeds what an agent needs for selection and invocation; it could be restructured with bullet points or separated into a brief summary plus details. The front-loading of the core purpose is good, but the length hurts readability.

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 thoroughly explaining the response structure (by_segment, fed_candidates, _diagnostics), the meaning of edge_pp_net and kelly fractions, and the optional filters. It also covers caveats like the 24h-move warning and placeholder-slug filtering. For a complex tool with 9 parameters and no output schema, this is remarkably complete.

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

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

Schema description coverage is 100%, so the baseline is 3 as the schema already documents all parameters. The description does reinforce the purpose of knobs like min_liquidity and max_spread_pp, but it does not add significant meaning beyond what the schema provides. The description's mention of parameter behavior (e.g., min_partition_leg_kelly applies to per-leg) is mirrored in the schema text.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx cross-referencing. The purpose is unambiguous and immediately actionable.

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 its intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the tradeable-edge knobs and their effect, giving clear context for when to adjust parameters. However, it does not directly reference sibling tools or explicitly state when to use an alternative, so it stops short of full exclusion guidance.

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

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

Adds substantial behavioral detail beyond annotations: 60-day snapshot TTL bound, decay calc from daily closes not intraday, snapshot gaps meaning no scan, and open-world snapshots written on cache-miss. This is context an agent needs to interpret results correctly, and it does not contradict the readOnly/idempotent hints.

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

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

Well-structured with clear sections (purpose, args, response, limits) and front-loaded with the core question. It is somewhat long, but each section earns its place given the lack of an output schema; justifiable for a tool with this complexity.

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

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

Without an output schema, the description fully documents the return shape (tracked[], expired[], snapshot_dates[]), field semantics, and limitations. It also covers the two parameters and relevant edge cases, making it self-sufficient 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 coverage is 100%, so baseline is 3. The description restates defaults and families but adds no new semantic detail beyond what the schema already contains (days lookback, window family).

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?

Purpose is explicit: 'Edge persistence and decay telemetry' with a specific verb+resource. It clearly distinguishes from sibling polymarket_edges by describing itself as built from daily snapshots and answering a unique question about edge age and decay.

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?

Clear context is provided: the tool answers when an edge's persistence matters, implying use for assessing historical edge strength rather than current edge discovery. However, it does not explicitly name alternatives or give when-not-to-use guidance, 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/non-destructive, and the description adds substantial behavioral detail: walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and flags forced_directional_risk/thin_legs. This goes beyond annotations and characterizes output behavior and risk semantics. No contradiction.

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

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

One dense paragraph containing all key info; the first sentence is a crisp summary. Though long, every clause earns its place and there is no filler. Structure could be improved with section breaks, but the content is appropriately front-loaded and tight.

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

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

No output schema exists, but the description enumerates all return values for both modes, clarifies behavioral constraints (size clamp 10–1,000,000, thin_legs, max_clean_notional_usd), and explicitly ties usage to risk mitigation. For a complex four-parameter tool, this is complete enough to invoke safely and interpret results.

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

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

Schema covers 100% of params, and the description adds operational meaning beyond property names: size_usd default 1000 with 'max spend on buys, target proceeds on sells'; basket size_usd as settlement notional with each share paying $1; side default auto in basket based on partition sum. This enriches the schema but is slightly dense in a single paragraph.

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

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

Description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth' – a specific verb+resource. It clearly distinguishes single-market vs basket modes and names sibling tools (polymarket_arbitrage, polymarket_edges), clarifying scope and differentiation.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns when not to rely on theoretical overround and explains the dominant loss mode (partial basket fills → unhedged directional position), providing when/where-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?

While annotations already declare readOnly/idempotent, the description goes far beyond by detailing compatibility_warning conditions, matched_pairs:0 scenarios, temporal_alignment impact, and skipped_cross_type/subtype counters. This adds significant behavioral context that an agent needs to interpret results correctly. No contradiction with annotations.

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

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

The description is long and dense, but it is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence carries technical meaning for this complex tool. It is not bloated or redundant, but the length means it isn't as immediately scannable as a simpler 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?

Given the tool's complexity and the absence of an output schema, the description thoroughly covers inputs, outputs (leg-by-leg prices, top_spreads_pp), edge cases (non-equivalent shapes, unrelated events), and safety warnings. It provides sufficient context for an agent to correctly invoke and interpret the tool in most scenarios.

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

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

The schema already documents all three parameters with descriptions (100% coverage), and the tool description enhances meaning by explaining how topic maps to pre-mapped shortcuts and how kalshi_event_ticker/polymarket_event_slug override the mapped side. The examples (e.g., 'fed', 'btc') reinforce proper usage. This exceeds schema baseline without being redundant.

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

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

The description states it computes the 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource. It clearly distinguishes from sibling tools like polymarket_arbitrage (which likely focuses on single-venue arbitrage) by emphasizing cross-venue comparison and resolving or rejecting false signals.

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

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

It explicitly explains two usage modes: pre-mapped topic shortcuts and explicit event tickers/slugs. It also warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable,' setting strong usage expectations. However, it doesn't name alternative tools or state explicit 'when not to use' contexts, 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/idempotent/non-destructive behavior, but the description adds meaningful context: scoping ('Scoped to your identifier...') and the omit-key-lists-all behavior, enriching the agent's understanding of side effects and return 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?

Three sentences, each carrying distinct information: action, use case, and scope/companions. No filler or redundancy; front-loaded with the core operation.

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

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

Covers purpose, usage, scope, relationship to sibling tools, and behavior with/without the key parameter. For a simple read-only memory tool with one optional parameter, this is fully sufficient despite lacking an output schema.

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

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

Schema has full coverage (100%) for the single key parameter, so the baseline is 3. The description adds a behavioral nuance—'omit the key argument' to list all keys—that goes slightly beyond the schema's property description.

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

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

Description opens with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also explains the list-all-keys variant. It clearly distinguishes from sibling tools by naming 'remember' and 'forget' as pairing counterparts.

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?

States when to use: 'Use to look up context the agent stored earlier...' and explicitly names alternatives: 'Pair with remember to save, forget to delete.' This gives clear usage context and mitigates confusion 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?

Despite readOnlyHint=true, the description transparently discloses the optional side effect of mark_read (flags events read so next call shows only newer ones). It also explains the feed is persisted, written by the evaluator, and describes the return payload structure—adding meaningful 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 five sentences, front-loaded with the core purpose, then provides return format, filtering/read state, and an alternative access URL. Every sentence adds useful 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?

With no output schema, the description compensates by explaining what each alert contains (source, citation_uri, raw payload). It also covers read-state semantics and polling behavior, making it complete for a read-oriented feed 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. The description adds value beyond the schema by giving a concrete example for type ('sec_8k'), clarifying that mark_read affects future calls, and implying limit/since semantics. It does not describe limit or unread_only, but those are well-covered in the schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed' and specifies what is returned (alerts with source, citation_uri, raw payload). The resource 'subscription feed' distinguishes it from siblings like get_cases and get_votes.

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 practical usage context: polling works fine, and an alternative URL is provided for scripts/dashboards. It also explains filtering by type/since and mark_read behavior, but does not explicitly compare against sibling tools or state exclusions.

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

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

The description goes well beyond annotations by explaining the fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, and the USPTO soft-fail due to PatentsView sunset. It also discloses the return structure (changes[] grouped by source, total_changes, citation URIs), providing rich behavioral context beyond the readOnlyHint.

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: user intents, source details, fallback behavior, parameter syntax, return format, and an alternative tool. It front-loads with query phrases and avoids fluff, making it efficient despite 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?

Given the tool's complexity (multi-source fan-out, fallbacks, soft-fail, parameter flexibility, and no output schema), the description fully covers what the tool does, how it behaves, what parameters mean, what the response looks like, and when to choose an alternative. 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?

Although the schema already covers 100% of parameters, the description adds significant value by explaining accepted formats for `since` (ISO vs relative shorthand), examples for `value` (ticker or zero-padded CIK), and enriching the meaning beyond raw schema descriptions.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with concrete query examples like "What's new with X". It explicitly distinguishes itself from the sibling entity_profile tool, which fetches static profiles, making the purpose and differentiation 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 states when to use this tool (for dynamic changes/news/filings within a window) and explicitly directs users to entity_profile for static profile needs. It also explains the `since` parameter's relative/ISO formats and recommends '30d' or '1m' for typical monitoring, giving clear usage context.

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 valuable behavioral context beyond annotations: storage is scoped by the agent's identifier, authenticated users get persistent memory, and anonymous sessions retain data for only 24 hours. These details are not in the annotations and help the agent understand side effects. No contradictions with the provided annotations are present.

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

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

The description is four sentences with purpose front-loaded in the first sentence. Each sentence earns its place: purpose, usage trigger, storage characteristics, and companion tools. There is no redundant or filler content.

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

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

For a simple two-parameter write tool with no output schema, the description covers all necessary context: what to store, when to use it, persistence behavior, and how it relates to other tools. No missing operational details are evident.

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?

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description supplements this by explaining the key-value pair is 'scoped by your identifier', adding meaning about how the parameters relate to storage. The examples of values ('findings, addresses, preferences, notes') also reinforce 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 identifies a save operation with a specific verb ('Save data') and resource ('data the agent will need to reuse later'). It distinguishes itself from sibling tools by explicitly pairing with 'recall' and 'forget', making its role unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' and gives concrete examples like resolved ticker or user preference. It also names companion tools ('Pair with recall to retrieve later, forget to delete'), clarifying how this tool fits into a workflow.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing cascading internal lookups, graceful degradation (e.g., if GLEIF or OpenFIGI is unavailable), explicit handling of unresolved identifiers under an 'unresolved' key, and the multi-source resolution logic. 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 information-dense but front-loads the purpose with examples before detailing types. While it is longer than strictly necessary, every sentence adds value and no content is redundant. Structure is logical: purpose, usage hint, type details, graceful degradation, efficiency claim.

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

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

With no output schema, the description must explain return values. It does so thoroughly: for 'company' it lists CIK, ticker, company_name, LEI, FIGI, and explains unresolved identifiers are listed explicitly under 'unresolved'. For 'drug' it mentions RxCUI, ingredient, brand, and a citation link. The cascading and degradation behaviors are also covered.

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%, baseline 3. The description adds immense value: it explains that 'company' accepts ticker, CIK, ISIN, or name with specific resolution chains (EDGAR, GLEIF, OpenFIGI), and 'drug' accepts brand/generic names returning RxCUI and citation. It also clarifies that ISINs resolve to legal entities via GLEIF, which the schema does not imply.

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 names to official identifiers, provides concrete example queries, and distinguishes it from sibling tools by emphasizing it should be used when an ID is needed from a name. It specifies supported types (company, drug) with detailed resolution scope, setting it apart from tools like compare_entities or entity_profile.

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 FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It lists example queries making the context obvious. While it doesn't explicitly state when not to use it or suggest alternatives, the examples and context sufficiently imply its primary role without ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool calls ai_visibility_check on each entity and returns a ranked list, but does not disclose additional behavioral details like rate limits, handling of multiple models, or edge cases beyond what annotations and schema state. This is reasonable but not exceptional, consistent with the calibration example.

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

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

The description is two sentences long and front-loaded with the core purpose. Every clause adds value: the mechanism, the ranking, the use case, and the return format. No filler or redundancy.

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

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

The tool has a clear purpose and the description explains what it returns (ranked list with score, confidence, signal density). It is a compound tool that references another tool (ai_visibility_check), and the description covers the high-level behavior. No output schema exists, so the description's mention of return fields is valuable. It does not explain the exact ranking algorithm or threshold behavior, but that is not essential for basic usage.

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 parameters (entities, models, _apiKey, context) are already well-documented in the schema. The description reiterates that it probes 'your brand + N competitors' and mentions output metrics, but does not add new semantic meaning beyond the schema. It earns the baseline score 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility across entities) and the verb (Compare), and details the internal mechanism (probes each entity with ai_visibility_check, ranks by score). It distinguishes itself from generic comparison tools by focusing on AI recognition/marketing audits, even giving a concrete example question.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example ('does Claude know about us as well as our competitors?'). This makes the intended scenario explicit. However, it does not explicitly exclude alternatives or mention when to use a different tool (e.g., single-entity ai_visibility_check), so it falls short of a perfect 'when/when-not/alternatives' 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?

Even with annotations declaring read-only and idempotent behavior, the description adds crucial context: it fans out to external services, can take 5-30s on first bundlephobia measurement, and degrades gracefully with sources_failed. This helps the agent set expectations and handle timeouts.

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 serves a purpose, covering use cases, output details, limitations, and error behavior. It's well-structured with a clear lead sentence followed by supporting 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?

With no output schema, the description compensates by enumerating the summary block fields and the structure of the response (per-advisory detail, links, alternatives). It also covers degradation behavior and ecosystem scope, leaving few gaps for an agent.

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

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

Schema coverage is 100% with descriptions for both package and version. The description adds a small but useful detail about scoped packages and clarifies defaults, enhancing the schema's existing explanations.

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 composite npm package evaluation check, listing specific data sources (deps.dev and bundlephobia) and the question it answers. It is distinct from sibling tools like scan_competitor_ai_presence, which focus on competitors rather than dependencies.

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: 'Use whenever an agent asks...' and provides exclusions for other ecosystems, directing users to deps.dev:version directly. This gives clear decision criteria for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds behavioral details beyond that: it specifies the embedding model (BGE-base-en), cosine similarity, overlapping window size (500 chars), and the 200K character limit with truncation flagging. It also discloses that results include character offsets and similarity scores, which helps the agent understand expected 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 well-structured and front-loaded with the core action, followed by usage guidance and technical details. Each sentence adds value, though the phrase 'saves context, returns only the passages that matter' is slightly promotional but still informative. It is appropriately sized for the tool's complexity.

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

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

Given no output schema, the description explains the return format (top-N passages with offsets and similarity scores), the truncation behavior, and the partnership with ask_pipeworx_grounded. It addresses both when and how to use the tool, making it complete for an agent to select and invoke correctly. No critical details are 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%, so the baseline is 3. The description adds a bit of context (e.g., text examples like SEC 10-K body, query examples in schema) but doesn't significantly go beyond the schema. The limit parameter is already fully specified in the schema. Thus, it meets but does not exceed the baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which uses a specific verb and resource, clearly distinguishing it from general ask tools. It also provides concrete examples (SEC 10-K body, article) and differentiates from sibling ask_pipeworx_grounded by explaining its niche: searching within already-fetched content.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt,' and gives a named alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear context and an alternative workflow, satisfying the top criteria.

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

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

The description discloses behavioral traits well beyond annotations: requires OAuth account (anonymous + BYO cannot persist), phone verification, 10/day SMS cap, webhook auto-disable after 10 failures, and signing secret returned only once. These details are critical for user expectations and are not present in 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 information-dense but well-structured, starting with the primary action and return value, then covering prerequisites, types, and delivery. While it is lengthy, every sentence adds value; however, the formatting could be more scannable with bullet points.

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 complexity (multiple subscription types, delivery channels, authentication requirements) and the absence of an output schema, the description is thorough. It covers prerequisites, all type-specific parameters, delivery options with constraints, and expected return values, 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 provides detailed parameter descriptions. The description adds extra semantic value with concrete examples (e.g., items:["5.02"] = officer change) and clarifies the SMS cap and verification requirement, which are not in the schema. This goes 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 clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource ('monitoring subscription'), effectively distinguishing it from siblings like list_subscriptions and unsubscriibe.

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, including required OAuth account and delivery channel options. It implicitly differentiates from pulling alerts by mentioning 'feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)', though it does not explicitly state exclusions or alternative subscription methods.

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 that results come from the live catalog of thousands of tools and include the exact tool + argument shape, giving agents useful context about what the output will contain. No contradiction with annotations.

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

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

The description is dense but every part earns its place: example queries front-load user intent, the return format is clearly described, and the meta-tool guidance is useful. It is slightly long but not wasteful, achieving a good balance.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It clearly states the output—category-bucketed example questions with exact tool and argument shapes—along with invocation modes and when to use. This is complete for agent decision-making.

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 optional topic parameter with allowed values. The description recaps that passing topic focuses results but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for suggesting example questions, returning category-bucketed questions with exact tool and argument shapes. It distinguishes from siblings by instructing agents to use this FIRST and referencing meta-tools like ask_pipeworx.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes both invocation modes (no args for full spread, or with topic to focus). It could be improved by explicitly naming alternatives like discover_tools, but overall provides solid context.

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=false, destructiveHint=false, etc.), the description adds meaningful context: ownership is enforced, and the row is deactivated rather than deleted, so historical events remain available. This gives the AI agent a clear picture of side effects and constraints without contradicting the annotations.

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

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

The description is two concise sentences, front-loaded with the action ('Cancel a subscription by id') and includes only essential behavioral details. Every sentence earns its place 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?

For a simple one-parameter tool with no output schema, the description covers purpose, ownership, and the deactivation behavior, and even points to recent_alerts for historical data. It does not mention the return value or error cases, but these are not critical given the tool's simplicity and the annotations.

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

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

The input schema already provides 100% coverage with a clear description of 'id' as 'Subscription id (uuid) returned by subscribe.' The tool description does not add any additional parameter-specific meaning beyond reiterating that it cancels by id, so baseline 3 is appropriate.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb and resource that clearly distinguishes it from sibling tools like subscribe and list_subscriptions. The additional details about ownership and deactivation further clarify its purpose and scope.

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

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

The description implies when to use the tool (when you have a subscription id and want to cancel) and provides context about ownership restrictions. It also references recent_alerts as a destination for historical events, hinting at an alternative for viewing data. However, it does not explicitly state when not to use it or directly compare with subscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral insight beyond these: the routing behavior for company financial claims vs. other facts, the semantic difference between could_not_verify and unsupported, the verification_error structure, and the efficiency claim of replacing 4–6 sequential calls. No contradictions with annotations.

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

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

The description is about 150 words but every sentence carries operational value: purpose, examples, routing, return types, error semantics, and performance rationale. It is front-loaded with the core definition and examples, then layered with important details. There is no fluff or redundant restating of schema/annotations.

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 takes full responsibility for explaining return values and behavior. It lists the verdict types, mentions the pipeworx:// citation, and clarifies the key distinction between could_not_verify and unsupported. It also covers both pipeline paths and the tolerance parameter, making it a complete guide for an agent to invoke and interpret the tool correctly.

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

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

The schema already provides full descriptions for both claim and tolerance_pct (100% coverage). The description adds valuable extra guidance: for tolerance_pct it explains how to use it for hallucination detection (set 1–2) and the default cap of 5, which goes beyond the schema. For claim it provides concrete examples of natural-language inputs.

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 and specifically states the tool's purpose: natural-language claim verification against authoritative sources. It provides example phrasings like 'fact check' and 'verify the claim that…' and distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on producing a verdict. The two-path routing (SEC EDGAR vs. grounded pipeline) further clarifies its specific scope.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which provides clear context. It also explains the two categories of claims and includes an important caveat about interpreting could_not_verify. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, so it lacks the full explicitness of a 5.

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