Folketinget Dk

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

The description goes beyond the readOnlyHint/idempotentHint annotations by revealing that the default model is free Workers AI but probing Anthropic requires a BYO key with direct cost to the user. It also discloses the return structure. This adds valuable behavioral context not captured in annotations, though it omits edge cases like network failures or rate limits.

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

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

Three sentences, front-loaded with the primary purpose, followed by necessary configuration details and use-case examples. Every sentence earns its place with no fluff or redundancy.

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

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

The description is self-contained: it states the tool's input (entity), the output format (per-model object with score/confidence/signals/raw_response and combined view), default behavior, and typical scenarios. While there is no output schema, the return structure is explicitly summarized. It could mention error handling or limitation but this is acceptable for a probe/read-only 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?

Since schema description coverage is 100%, the baseline is 3. The description adds meaningful context: it clarifies the default model when 'models' is omitted, explains that '_apiKey' is passed through to Anthropic, and implies that 'models' can contain 'workers-ai' or 'anthropic'. This enhances the schema rather than just repeating it.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs') with a clear deliverable ('score visibility (0-100) per model'), making the core function obvious. It does not explicitly distinguish itself from similar-sounding siblings like 'scan_competitor_ai_presence', but the scope (any business/brand/product/topic) is implicit in the examples.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which tells the agent when to invoke the tool. It does not explicitly state when not to use it or name alternative tools, but the context is sufficient for most selection scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond those: it routes to sub-tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call'. No contradiction exists.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and organized into clear usage, examples, and escalation guidance. Some phrasing is redundant—'even if web search could also answer it' echoes the opening—but overall each section earns its place and supports agent decision-making.

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

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

For a tool with no output schema, the description provides a reasonable amount of what an agent needs: the input type via examples, the behavior via routing/citations, the default status, and when to escalate. It doesn't specify the exact response fields or formatting beyond 'structured answer', but the examples and annotation profile make the call actionable.

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

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

Schema coverage is 100%, with the primary 'question' parameter and all aliases fully documented. The description does not add new parameter-level details, but it supplies illustrative example queries that reinforce the range of acceptable inputs. This meets the baseline for well-covered schemas without exceeding it.

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

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

The description clearly identifies the tool as a routing/answering layer: it sends questions to one of 5,708 tools across 1,494 sources and returns structured answers with stable citation URIs. It also distinguishes itself from ask_pipeworx_grounded and deep_research. The verb 'routes' plus the concrete resource scope make the tool's function unmistakable.

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

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

The description is explicit about when to use it: prefer over web search for factual and data-oriented questions, use for phrases like 'find', 'look up', 'how much', and 'current'. It also names alternatives and conditions: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions, and the news feeds for breaking-news sentiment. This is strong 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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds context about the beta nature, that results are compared against the stable router for merges, and that it currently matches ask_pipeworx exactly. This is valuable behavioral context beyond the annotations, though it doesn't disclose any additional side effects beyond what annotations imply.

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

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

The description is about four sentences, reasonably concise and front-loaded with the most important info (beta, identical, no candidate active). It's readable and wastes little space, though it could be slightly tighter without losing meaning.

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

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

For a complex router tool with no output schema, the description covers its purpose, current state, and usage. It explicitly mentions 'same response shape' as ask_pipeworx, leveraging the sibling tool's known behavior. It doesn't elaborate on response format, but given the clear reference to ask_pipeworx, the description is sufficiently complete for an agent familiar with the sibling 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 parameters (question and its aliases) are already well-documented in the schema. The description mentions 'same arguments' but doesn't add any new semantic meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states that this is a beta version of ask_pipeworx, an identical universal router with the same 5,708 tools and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. The purpose is unambiguous and well-differentiated from siblings.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the current state (no active candidate, matches ask_pipeworx exactly) and clarifies it's a full working router, not a fallback. It implicitly tells when not to use it (when you don't need experimental routing) by contrasting with the stable router.

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

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

Beyond the readOnly/idempotent annotations, the description discloses refusal behaviors with exact refusal_reason enum values, the 'only what the tool result contains' extraction policy, the extra LLM call cost, and the detailed success response shape. This gives the agent a strong behavioral model.

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

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

The description is dense but longer than average; however, each section earns its place: use-case framing, routing behavior, return/refusal contract, and cost trade-off. Slightly front-loaded and well-paragraphed, though the detailed response schema could arguably be trimmed if an output schema existed.

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

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

For a tool with no output schema, the description fully specifies success and refusal return shapes, enums, sources, timestamps, and cost considerations. It also provides routing details, use cases, and an explicit alternative. Nothing essential for correct invocation or expectation-setting is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context that the question drives tool selection and argument filling, but does not add detailed parameter semantics beyond what the schema already provides. It serves as a general context layer rather than parameter-specific guidance.

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

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

The description clearly identifies a distinct mode: 'Hallucination-resistant answer mode for high-stakes reads' and states specific behavior ('EXTRACTS the answer using ONLY what the tool result contains'). It distinguishes itself from ask_pipeworx by name and by cost/use-case contrast.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete example domains. Explicit when not to use: 'prefer ask_pipeworx for casual lookups' and cost tradeoff ('Costs one extra LLM call'). Names the alternative directly.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description goes far beyond by detailing fan-out behavior, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, and resolution-rule risk. It discloses edge cases like medium/low matches, illiquid wide spreads, and cancellation rules, which is exceptional operational transparency.

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

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

The description is long but well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section conveys crucial operational detail, and the purpose is front-loaded. While not concise in word count, it is information-dense and justifies its length.

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

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

Given the tool's high complexity and absence of an output schema, the description thoroughly explains response shapes (result.market, result.analysis, result.evidence), resolver fields, parent_event, news fields, statuses, and safety mechanisms. It covers success paths, failure modes, and edge cases, making it complete for an agent to understand what will be returned.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual flavor (fan-out examples for different categories) but doesn't offer additional parameter-level syntax or format details beyond what the schema already provides. The schema adequately documents market, depth, and include_raw.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by emphasizing Polymarket bet research, classification, and fan-out to data packs. Explicit use cases like 'should I bet on X' further sharpen purpose.

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

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

The description gives explicit use cases ('Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'') and provides clear examples of when the tool applies. While it doesn't name sibling tools as alternatives, its niche is well-defined, and it warns about blocking conditions (low-confidence match, market closed) that guide appropriate use. Missing explicit 'when not to use' relative to 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 establish read-only/idempotent safety. The description adds substantial behavioral detail: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), proper handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation 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 compact but information-dense, using bullet-like separations and front-loading with example triggers. Every sentence contributes value, from usage guidance to data-source details. It is slightly longer than strictly necessary but justified by the tool's complexity.

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

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

With no output schema, the description compensates by explaining the return format (paired data + pipeworx:// citation URIs), sorting behavior, and edge-case handling (off-calendar fiscal years). For a multi-entity comparison tool, this is complete enough for an agent to select and invoke correctly.

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

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

The schema already covers both parameters (type with enum, values with min/max). The description enriches meaning by specifying what data each type pulls (latest 10-K metrics vs. adverse-event counts) and gives concrete examples for values. It also clarifies off-calendar fiscal year handling, which the schema doesn't mention.

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 explicit trigger phrases ('Compare X and Y', 'X vs Y') and defines the tool's scope as a side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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 to prefer this tool over sequential single-pack lookups for comparisons, and lists specific user phrasings that should trigger this tool. It also differentiates between type='company' and type='drug' use cases.

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 readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: account and paid-plan requirements, parallel decomposition across 5,708 tools, latency expectations, gap reporting, contradiction scanning, semantic excerpting, and resolvable citations. It richly discloses behavior beyond the annotations and does not contradict 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 the tool is complex and nearly every sentence carries operational guidance. The account requirement is front-loaded, which is appropriate. It could be tightened with better paragraphing, but the length is justified by the number of distinct behavioral and routing facts an agent needs.

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 on the burden of explaining what the tool returns: evidence, confidence, source, fetched_at, pipeworx:// citations, gaps, contradictions, and hop fields. It also covers auth, latency, and alternatives. For a tool of this complexity, the description 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 coverage is 100%, so the baseline is 3. The description adds genuine meaning by clarifying what kind of question fits the 'question' parameter and by explaining depth behavior beyond the enum values: quick=single hop, standard=gap-recovery hop plus contradictions scan, thorough=iterative lead-chasing plus contradiction scan. This exceeds the schema's parameter documentation.

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

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

The description names a specific verb and resource: 'research across Pipeworx's 1494 STRUCTURED data sources' in one call. It sharply distinguishes itself from open-web search and from the sibling ask_pipeworx. It is immediately clear what this tool does and how it differs from nearby 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 gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', for breaking/current-news prefer ask_pipeworx, and if not signed in use ask_pipeworx. It also explains how depth levels map to different use cases. This leaves little to inference.

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 valuable behavioral context by specifying the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations without contradicting them.

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

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

The description is four sentences, with the second sentence containing a long but valuable list of supported domains. Every sentence earns its place: purpose, usage, return value, and priority. The length is justified by the information density, though it is slightly longer than the minimal needed.

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

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

For a read-only discovery tool with no output schema, the description fully explains the return value (top-N tools, names, descriptions, full input schemas, examples), how to use results (directly callable, no second lookup), and when to invoke it (first when exploring many tools). No critical gaps exist.

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

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

Schema description coverage is 100%, with all six parameters described. The description reinforces that 'query' is a natural language description but doesn't add syntax or format details beyond the schema. The domain list helps agents formulate queries, but that's more usage context than parameter semantics, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find) and resource (tools) and distinguishes itself from sibling tools by positioning itself as the discovery/meta-tool among many domain-specific tools. The enumeration of domains further clarifies scope.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides strong when-to-use guidance and implies when not to use it (i.e., when you already know the target tool). It also lists example domains, reinforcing applicability.

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 and idempotent nature, but the description adds valuable behavior: fans out across multiple sources, discloses PatentsView sunset with soft-fail, and notes a GDELT→GNews fallback. This goes beyond annotations to explain operational nuances.

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-organized: examples front-load intent, then scope, return fields, and input constraints. Each sentence contributes, though the multiple example phrasings add minor 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?

Even without an output schema, the description enumerates return fields (cik, filings with URIs, fundamentals, patents, news, LEI) and limitations (names unsupported, patents soft-fail), making it sufficiently complete for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the schema's examples ('AAPL', '0000320193') and name restriction, adding no new semantic detail beyond the structured definition.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from sibling tools by explicitly recommending preference over 'chaining single-pack SEC/XBRL/news lookups' and referencing 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name).'

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 that the tool deletes a stored memory, which is consistent with the destructiveHint=true annotation. While this is useful context, it largely restates what the annotation already conveys. No additional behavioral details (e.g., permanence, error handling) are disclosed, so the value beyond annotations is modest.

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, with the first sentence clearly stating the core action and the second providing usage context. Every word serves a purpose; there is 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?

For a simple tool with one parameter, strong annotations, and no output schema, the description covers the purpose, usage conditions, and related tools. It is sufficiently complete to guide an agent without missing critical information.

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 fully describes the 'key' parameter with 100% coverage. The description's phrase 'by key' reinforces the parameter but does not add new meaning or format details. Since the schema already carries the load, the baseline of 3 applies.

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

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

The description begins with a specific verb+resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from siblings like remember and recall, which perform complementary operations. The purpose is unambiguous.

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

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

The description explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with remember and recall. It does not explicitly mention when not to use it, but the provided guidance is clear and actionable.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds context by explaining it fetches the URL, extracts key metadata, and emits a standard llms.txt markdown blob. It does not disclose failure modes, but that is beyond what annotations require.

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, front-loaded with the primary action, and every sentence earns its place: purpose, process, output, and use cases. It is concise 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 two-parameter tool with no output schema, the description fully covers purpose, behavior, return format ('single text blob ready to drop at site-root/llms.txt'), and usage scenarios. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: both 'url' and 'max_links' have clear descriptions. The tool description adds no additional parameter-level nuance, 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 opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly explains the process (fetches page, extracts title/description/key links) and output format, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not name alternatives or exclusions, but gives clear context for when 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 cover read-only, idempotent, non-destructive behavior. The description adds valuable context beyond the annotations by revealing the return format ('not wrapped in `value`') and the $expand capability, which are not otherwise specified. No contradiction exists.

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

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

Three concise sentences cover purpose, return format, and expansion capability without redundancy. Each sentence contributes distinct information and the description is front-loaded with the core action.

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

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

For a simple fetch-by-id tool with comprehensive annotations and schema, the description is complete. It explains the key behavioral quirk (direct return) and optional expansion, and no output schema exists, so further return details are unnecessary. It also gives a concrete entity example to reduce ambiguity.

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

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

The input schema provides a full description for all four parameters (id, entity, expand, select) with high coverage. The description only mentions $expand in passing, adding no new semantic details beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the action: 'Fetch a single Folketinget entity record by its numeric id' with a concrete example (Sag(1)). This distinguishes it from sibling tools like query_entity by highlighting the id-based lookup and direct return format.

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 usage context is implied by 'by its numeric id'—use when you have a specific numeric id and need a single record. However, it does not explicitly name alternatives or exclusion criteria, such as recommending search tools for non-id-based queries, so guidance is present but not fully developed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety context is provided. The description adds behavioral detail about scope ('caller's active subscriptions') and return fields, which is useful beyond annotations. 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 no filler; first sentence combines purpose and output, second gives usage guidance. Efficient and well-structured.

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

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

For a simple read-only list operation, the description covers purpose, return fields, and usage context. Combined with schema and annotations, it is complete for an agent to invoke correctly.

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

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

The single parameter include_inactive is fully described in the schema with default value. The description does not add parameter-specific semantics but the schema coverage is 100%, so a baseline of 3 applies.

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

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

The description states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from subscribe/unsubscribe siblings by focusing on enumeration rather than creation or removal. It also lists returned fields, making scope 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?

It explicitly instructs when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for monitoring and pre-unsubscription lookup, though it doesn't name sibling tools explicitly as alternatives.

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

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

Beyond the annotations (all false), the description discloses critical behavioral traits: 'Filing without an account returns a `claim_token`', 'Rate-limited to 5 per identifier per day', 'Free; doesn't count against your tool-call quota', and 'The team reads digests daily'. These details reveal async processing, rate limits, and account implications that annotations do not convey. No contradiction with annotations.

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

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

The description is long but every sentence provides actionable guidance: purpose, usage criteria, exclusions, message formatting, claim_token workflow, rate limits. It is front-loaded with the primary function and flows logically through the decision matrix. 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?

Given there is no output schema, the description fully explains the return mechanism (claim_token) and resolution workflow. It addresses complexity (different feedback types, async processing, cross-server boundaries) and provides complete contextual guidance. The tool is simple enough that this description is comprehensive.

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 meaning beyond the schema by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})...') and constraining the message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches parameter understanding beyond field-level descriptions.

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

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

The description opens with a clear, specific verb-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists concrete use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by explicitly scoping to Pipeworx tools only. This unambiguously identifies the tool's purpose.

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

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

The description gives explicit criteria for when to use the tool ('Use when a tool returns wrong/stale data...'), when not to use it (for tools from other MCP servers: 'file it with that server instead'), and how to identify eligibility ('Pipeworx tool names are the ones this connection lists'). It also explains the claim_token retrieval flow, providing complete 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses data source (CF analytics-engine), privacy (no PII), output granularity (pack, tool, count), and caching behavior (5min-1h). These are valuable behavioral insights not captured in annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by return details, use cases, and caveats. Every sentence adds value, though the 'Useful for' list could be slightly condensed. It remains appropriately sized for the information conveyed.

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

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

Despite having no output schema, the description explains what will be returned (top tools, packs, total call volume) and the data format (pack, tool, count). It also covers caching and privacy. For a simple read-only trending tool, this is complete and actionable.

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

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

The schema description for the 'window' parameter already fully explains the meaning of each option (24h default, 7d, 30d, and the trade-off between hot vs steady-state). The description merely repeats these values without adding new semantic nuances, so a baseline 3 is appropriate given 100% 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: showing what other AI agents are calling on Pipeworx, returning top tools, packs, and call volumes. This specific verb+resource+scope distinguishes it from siblings like discover_tools, which is about general discovery rather than agent behavior trends.

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 three concrete use cases (hot data sources, canonical tool confirmation, alignment with agent needs), giving clear context for when to use it. However, it does not explicitly mention when not to use it or alternative tools, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond those by detailing the Jaccard similarity threshold (≥0.30), the placeholder-slug filter (>20% yields null), the fill_check behavior that prices signals against live CLOB depth, and the warning 'realizable_edge_pp ≤ 0 ... do not trade it.' No contradiction with annotations exists.

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

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

The description is long but densely packed with necessary details, and uses bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to aid scanning. Every sentence earns its place, though the length and inline technical caveats could make quick parsing slightly harder than a more compact version.

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

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

With no output schema present, the description carries the full burden of explaining return values. It enumerates the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}.' It also covers edge cases like skipped_low_similarity, placeholders_filtered, and thin_legs[], making it highly complete for a complex arbitrage tool.

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

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

The input schema already covers 100% of parameters with descriptions, and the tool description adds rich semantics: event mode vs topic mode, recommended usage, concrete slug examples, and the difference in output. It explains that 'event' walks child markets and computes partition checks, while 'topic' flattens related events for cross-event scans, meaningfully extending the schema's bare descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly enumerates the three invocation modes (trending_scan, event, topic) and distinguishes this tool from siblings like polymarket_edges, polymarket_fill_risk, and polymarket_kalshi_spread by focusing on arbitrage detection and partition-sum logic.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event mode for a specific market and names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This clearly tells the agent when and how to invoke the tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: caching behavior (1h at KV level), response segmentation (by_segment, fed_candidates, _diagnostics), gates and filters, and the warning about edge already being priced in. 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 long, but every sentence is information-dense and organized into clear segments (model families, response structure, knobs, caching). It front-loads the purpose and then systematically details behavior. While not terse, the complexity of the tool justifies the length and it remains well-structured.

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

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

With no output schema, the description must explain return structure, and it does: by_segment, fed_candidates/fed_note, and _diagnostics. It also covers caching, filtering rationale, and model details. For a tool with 9 parameters and multiple edge types, this description is exceptionally complete.

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

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

The input schema has 100% coverage, so baseline is 3. However, the description adds unique semantic value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining the subtle behavior of min_partition_leg_kelly (why min_kelly doesn't filter partitions, per-leg Kelly). This goes beyond the schema descriptions and justifies a higher 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by emphasizing the Pipeworx-disagreement angle and the 'what should I bet on today' use case.

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 the primary use case ('Built for what should I bet on today') and notes it avoids paging hundreds of markets. It also describes knob-based filtering for tradeability, but does not explicitly name sibling tools to exclude (e.g., polymarket_arbitrage). This is clear context but lacks explicit alternative differentiation.

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, and non-destructive behavior. The description adds substantial context beyond annotations: the 60-day TTL limit, snapshot gaps indicating no scan that day, decay computed from daily closes (not intraday), and detailed semantics of the response fields (e.g., negative edge_pp_net means SELL YES). This is rich, non-contradictory 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 long but well-structured with labeled sections (intro, Args, RESPONSE, LIMITS). It is front-loaded with the purpose and every sentence adds value. However, it is verbose enough that an agent might need to parse carefully; a more concise version could retain clarity while reducing length slightly.

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

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

With no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and their meanings, including field-level details like trend values and decay_pp_per_day. It also covers limitations, data source behavior, and interpretation guidance (median lifespan as competition clock). This is exceptionally complete for a complex telemetry tool.

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

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

Schema coverage is 100% with both parameters fully described. The description's 'Args' section essentially mirrors the schema (defaults and clamps), adding only minor context like 'snapshot family' for window. It does not go beyond the schema in meaningful new detail, 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 opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the core question ('how long has this edge existed and is it shrinking?') and clearly differentiates itself from sibling tools like polymarket_edges by focusing on temporal dynamics rather than current edge values.

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

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

The description provides clear context on when to use the tool by framing the analytical question and giving a concrete example ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies the use case of analyzing edge history/decay but does not explicitly name alternatives or state when NOT to use it, leaving a minor gap in exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: it walks the order-book ladder, returns risk metrics, flags thin legs, and warns that partial basket fills can convert an arb into an unhedged directional position. This goes well beyond what annotations provide and does not contradict 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 dense and long, but every sentence carries substantive information: mode explanations, parameter semantics, output fields, and usage warnings. It is front-loaded with the core purpose and structured logically. It loses one point for being a single verbose paragraph that could benefit from breaking out the two modes more visually, but it remains highly efficient 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?

Given the complexity of the tool (two modes, multiple parameters, rich output), the description is remarkably complete. It explains both modes, parameter interpretations, return values (top_of_book, vwap_fill_price, slippage_pp, etc.), and risk caveats. Without an output schema, the description carries the full burden of explaining behavior, and it succeeds.

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

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

Schema coverage is 100%, but the description adds crucial semantic distinctions: the dual mode (market vs event), the interpretation of side (single-market options vs basket auto default), and the size_usd context (spend vs target proceeds vs settlement notional). These details clarify ambiguous parameter meanings beyond the schema's basic property descriptions.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies distinct modes (single-market vs basket/partition) and names output metrics. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on execution risk rather than edge detection.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when the tool is necessary (thin books, partial fills) and names the specific sibling tools it complements, providing clear when-to-use and why-to-use 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?

The description goes far beyond readOnlyHint/openWorldHint by documenting compatibility_codes (event_subject_mismatch, temporal_mismatch, non_equivalent_bet_shapes, etc.), the rule that unknown legs are never paired, and skipped counters. It also discloses which returned pairs are unverified. 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 text is long but organized with TWO MODES, RESPONSE, and SAFETY FIELDS labels, and it front-loads the core definition before the code reference list. A few warnings repeat (unverified pairing appears in the codes list and the closing admonition), so it is slightly less tight than it could be.

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 specifying the response shape (per-venue leg prices, top_spreads_pp in percentage points, temporal_alignment, skipped counters) and the main failure/compatibility conditions. An agent has enough to call the tool and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents each parameter; the description adds the mode-level semantics: topic auto-fetches the matching event on each venue, while explicit ticker/slug create custom pairings and override the topic-mapped side. This is more than a restatement, though the extra meaning is modest.

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

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

The opening sentence identifies a specific function: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It then enumerates two modes and describes the output, which is readily distinguishable from the single-venue sibling tools like polymarket_edges or polymarket_arbitrage. No ambiguity remains.

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 scopes the two entry modes (topic shortcuts vs explicit ticker/slug overrides) and warns that most pre-mapped topics currently return compatibility_warning, with 'pre-mapped ≠ tradeable.' It does not name an alternative sibling tool for cases where the cross-venue match is unreliable, so it misses explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to cover safety. It adds useful context about the response shape ('value array') and the Danish language convention for fields, 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?

Three sentences, front-loaded with purpose, followed by language note and capabilities. No fluff; every sentence serves a purpose.

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

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

Even without an output schema, the description explains the return format, language, OData feature support, and provides examples. It covers the essential behaviors of a query tool, though it doesn't detail edge cases like case sensitivity or per-entity OData support, which is acceptable.

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

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

The schema covers all 7 parameters with descriptions, so the baseline is 3. The description adds concrete OData filter examples and clarifies that fields are in Danish, enriching the semantic meaning of the filter and entity parameters beyond the schema.

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

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

The description clearly states the verb ('Query'), the resource ('Folketinget OData v3 entity collection'), and return format ('value array'). While it doesn't name siblings, it is distinct from 'get_entity_by_id' and 'search_cases' by its generic OData nature.

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 querying arbitrary entity collections with OData filters and paging, but it doesn't explicitly state when to choose this over 'get_entity_by_id' or 'search_cases'. It provides examples of valid filters, which helps, but no exclusions or alternative 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 valuable behavioral context beyond the annotations: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), which is a privacy-relevant trait. It also discloses that omitting the key lists all saved keys, a behavior not in annotations. No contradictions with readOnlyHint, idempotentHint, or destructiveHint.

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

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

The description is three sentences with no filler. It front-loads the primary action, then provides usage context and scoping, and ends with complementary tool relationships. Every sentence serves a purpose and the length is appropriate for the tool's simplicity.

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

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

Given the tool has a single optional parameter, high schema coverage, and annotations for readOnly/idempotent/destructive, the description covers all necessary context: what it does, when to use it, scoping, and relationship to remember/forget. No output schema exists, but the tool's return behavior is straightforward and the description sufficiently sets expectations.

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

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

The schema already documents the key parameter with 100% coverage, so baseline is 3. The description adds semantic richness by providing examples of what keys represent (e.g., target ticker, address, research notes) and clarifies the dual-mode behavior (retrieve specific key vs. list all), which helps the agent select appropriate arguments.

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 retrieves a saved value or lists all keys, naming the specific resource (saved memories) and the verb (retrieve/list). It distinguishes from siblings by explicitly referencing 'remember' and 'forget' and provides concrete examples (target ticker, address, research notes), making the purpose unambiguous.

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

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

The description gives clear usage context: 'Use to look up context the agent stored earlier' and explains the pairing with remember/forget. It does not explicitly state when not to use or name alternative tools beyond the complementary ones, but the guidance is strong enough to know when to invoke it.

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

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

The description explicitly says `mark_read:true` will 'flag returned events read' and alter future results, which is a state change. This directly contradicts the annotation `readOnlyHint: true`, making this an annotation contradiction. The read-only claim is misleading, and no additional behavioral context (auth, rate limits, errors) is provided.

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 and front-loads the main action and return payload. It then covers filters and mark_read behavior, and ends with a useful alternative endpoint. Each sentence earns its place, though the final clause about registry.pipeworx.io is slightly tangential.

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?

Since there is no output schema, the description compensates by naming returned fields (source, citation_uri, raw event payload). It covers filtering, mark_read side effects, and polling/alternative access. Minor gaps like explicit pagination or unread_only interplay are already covered by the schema, making this complete for a low-complexity read tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by giving a concrete type example ('sec_8k'), specifying `since` as an ISO timestamp, and explaining the downstream effect of `mark_read:true` on subsequent calls. This exceeds what the schema alone provides.

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

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

The description opens with 'Pull fired events from your subscription feed', clearly identifying the verb and resource. It distinguishes itself from siblings like list_subscriptions by focusing on fired/persisted alerts rather than subscription management. The return payload details further clarify its exact purpose.

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

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

The description states when to use the tool ('Polls work fine') and offers an alternative GET endpoint for scripts and dashboards. It also gives concrete filter usage examples ('sec_8k', ISO timestamp) and explains mark_read behavior. It does not explicitly contrast with sibling tools, but the context is sufficient for typical use.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses multi-source fan-out, fallback logic (GDELT→GNews with rate-limit trigger), a soft-fail condition (USPTO PatentsView API sunset), and the exact return shape (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations; the annotation hints are reinforced.

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 densely packed but every sentence earns its place: purpose, sources, fallback, parameter semantics, return format, and sibling differentiation. It is front-loaded with the core purpose and structured with clear signal phrases. Length is proportionate to the tool's complexity.

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

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

With no output schema, the description compensates by detailing the return payload (changes[] grouped by source, total_changes, citation URIs). It also covers source-specific edge cases (USPTO soft-fail) and provides a comparison to entity_profile. The tool is complex (3 params, multi-source fan-out), and the description fully addresses what an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a practical usage tip for `since` ('Use "30d" or "1m" for typical monitoring') and reiterates accepted formats with examples. It does not deeply elaborate on `type` or `value`, but the schema already fully describes them, so the extra tip justifies a 4.

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

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

The description uses a specific verb+resource: 'change feed for a company in the last N days/weeks/months'. It lists concrete data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes itself from sibling tool entity_profile ('Use entity_profile instead when you want the static profile'). This makes the purpose unmistakable.

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

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

The description provides explicit when-to-use context with natural language examples ('What's new with X' / 'latest on Y'), and gives a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains the internal fallback behavior (GDELT preferred, GNews on rate-limit) so agents know when to expect degraded results.

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

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

Adds substantial context beyond annotations: key-value pair scoped by agent identifier, persistence differences for authenticated vs. anonymous sessions (24 hours), and pairing with recall/forget. This is exactly the kind of behavioral nuance (auth, scoping, lifetime) that annotations alone don't convey.

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

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

Two substantive sentences plus a companion-tool note, totaling ~70 words. Every sentence carries distinct value: purpose, usage examples, persistence mechanics, and pairing. Efficiently front-loaded.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers what it does, when to use it, how persistence works, and related tools. No significant gaps given its simplicity.

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

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

Schema coverage is 100% (both key and value have descriptions). The description adds no additional parameter syntax or format details; it only restates the key-value concept already captured in schemas. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly distinguishing it from siblings like recall and forget. It explicitly frames the tool as a storage operation for later retrieval.

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

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

The description provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference) and names companion tools (recall, forget). However, it lacks an explicit 'when not to use' clause, though the positive use cases are clear enough.

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 significant behavioral detail: it cascades through multiple endpoints, degrades gracefully (LEI/FIGI enrichment degrades but EDGAR returns), returns unresolved identifiers explicitly under 'unresolved', and labels sources. This goes well beyond annotations.

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

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

The description is verbose (three dense paragraphs) and includes some redundancy ('Use FIRST' appears both early and late). While the detail is valuable, it could be tightened by moving the internal cascade details to a separate note or trimming examples. It is front-loaded with key purpose, which is good.

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 covers what the tool returns (identifiers, source labels, unresolved list) and handles edge cases (degradation, ISIN resolution for non-US issuers). It lacks an explicit return structure example, but the narrative provides enough for an agent to understand the output. Completeness is strong for a tool that replaces 2-3 manual lookups.

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

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

Schema coverage is 100% with both type and value described. The description adds rich meaning: it explains that value can be ticker, CIK, ISIN, or name for company (and that ISIN resolves via GLEIF), and for drug accepts brand or generic. It also details the type enum and notes that the tool handles multiple identifier types, making the parameter semantics crystal clear.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, supported types are enumerated with specific examples (CIK, LEI, RxCUI, etc.), and it positions itself as the primary entry point ('Use FIRST whenever you have a name but need an ID'). This separates it from siblings like get_entity_by_id 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 gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details input formats (ticker, CIK, ISIN, name for company; brand/generic for drug). However, it does not explicitly exclude cases when the agent already has an ID (e.g., suggesting get_entity_by_id as alternative), leaving a minor gap in when-not-to-use.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it discloses that probes use ai_visibility_check, that ranking is by score, and that Anthropic requires an _apiKey. It does not contradict 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?

Four concise sentences: purpose, mechanism, use case, and output. Every sentence adds value and there is 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?

The description covers the core behavior, use case, and return shape (ranked list with score, confidence, signal density) despite having no output schema. It doesn't discuss edge cases, but the schema already constrains entity counts. Overall it's sufficient for an agent to select and invoke the tool correctly.

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

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

All four parameters have descriptions in the schema (100% coverage), so the baseline is 3. The main description adds no parameter-specific meaning beyond what the schema already provides (e.g., 'first entry treated as subject' is already in the schema).

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

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

The description opens with a specific action ('Compare AI visibility across multiple entities side-by-side'), identifies the underlying probe mechanism (ai_visibility_check), and differentiates from the single-entity sibling by focusing on multi-entity ranking. The use-case quote ('does Claude know about us as well as our competitors?') further clarifies intent.

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 frames the tool for competitive AI-marketing audits and implies a multi-entity context versus the single-entity ai_visibility_check. However, it does not explicitly state when to use an alternative or when not to use this tool, so it earns a 4 rather than a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts, and the rest still returns. It also states the NPM-only limitation and mentions the return structure (summary block, advisory detail, links, alternatives), providing rich 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 dense but every sentence earns its place: purpose, data sources, usage triggers, output fields, limitations, failure behavior, and latency warning. It is well-structured, front-loaded with the core value, and contains no fluff.

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

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

Given there is no output schema, the description thoroughly explains the return values (list of summary block fields, per-advisory detail, links, alternative versions). It also covers limitations, failure modes, ecosystem scope, and timing, making it complete and actionable 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 description coverage is 100%, and the schema already explains both parameters (package name, with scoped package support, and version with default behavior). The description adds context for usage (e.g., 'adding lodash' example) but doesn't add 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 states this is a composite 'should I add this npm package' check with specific verbs and resources: it fans out across deps.dev and bundlephobia. It distinguishes itself from sibling tools by explicitly scoping to npm packages and listing the exact data sources and outputs, leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also offers an alternative for non-NPM ecosystems by directing to deps.dev:version directly, which clarifies when not to use this tool and what to use instead.

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, indicating a safe read operation. The description adds behavioral context beyond that: results are 'Sorted by most recently updated' and it describes a 'convenience search' (implying a simplified wrapper). This adds value beyond the annotation, though it could go further by noting the substring matching is case-insensitive or explaining return format.

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

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

The description is two sentences, front-loaded with the core functionality, then usage guidance and an alternative. No fluff or redundant repetition of schema information. Every sentence earns its place.

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

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

For a simple search tool with a small parameter set and no output schema, the description delivers all necessary context: what it searches, how matching works, sort order, and when/alternatives to use it. The annotations cover safety. This is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic context for the query parameter by explaining it is a 'substring to match in the Danish title (titel)' and provides examples. This goes beyond the schema's basic type/description, clarifying the matching behavior. The top and skip parameters are already well documented in the schema.

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

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

The description clearly states the tool's function: 'finds cases whose Danish title (titel) contains a substring.' It names the specific resource (Sag/cases/bills) and the matching mechanism. It also distinguishes itself from the sibling tool query_entity by noting 'for full control use query_entity,' which differentiates it from alternatives.

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 tells when to use this tool: 'Use this to look up legislation/matters by keyword.' It also provides an alternative: 'for full control use query_entity.' This gives clear guidance relative to sibling tools, fulfilling the 'when vs. alternatives' requirement.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: exact embedding model (BGE-base-en), window size (500-char overlapping), truncation behavior (200K cap, flagged), and output characteristics (offsets, similarity scores). This exceeds the baseline for annotated tools.

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 purpose ('Semantic search INSIDE a fetched record'), then usage guidance, then technical specifics. Every sentence serves a distinct function, and the information density is high without redundancy. It is compact yet comprehensive.

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

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

Despite having no output schema, the description explains return format (top-N passages with character offsets and similarity scores). It also covers input constraints (200K char cap), algorithm details, and integration with a sibling tool. For a 3-parameter tool with strong annotations, this is fully 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%, so baseline is 3. The description adds meaning by explaining 'text' as 'the text you already pulled (e.g. a SEC 10-K body, an article, a long tool result)' and provides concrete query examples, going beyond the schema descriptions. Limit is not described in prose but is well covered by the schema.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings like ask_pipeworx (grounded Q&A) and search_cases (case search) by emphasizing the 'inside a fetched record' scope and the output format (passages with offsets and similarity scores).

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and directly names an alternative/pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and 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?

Beyond annotations, the description discloses critical behavioral traits: auth requirement ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), side effects (creates persistent subscription, returns id), and detailed delivery behaviors (SMS verification, 10/day cap, webhook HMAC signing, auto-disable after 10 failures). No contradiction with annotations.

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

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

The description is long but appropriately sized for the tool's complexity. It front-loads the core purpose and return value, then logically organizes supported types and delivery channels. Every sentence adds useful information without fluff or repetition.

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

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

With no output schema, the description clearly states what the caller receives (new subscription id, and webhook secret for webhook delivery). It covers prerequisites, rate limits, verification steps, and failure behavior. The description is complete for an AI agent to invoke the tool correctly and understand the consequences.

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 has 100% parameter descriptions, the tool description adds substantial semantic value: it gives concrete examples for each subscription type, explains the meaning of item codes, and details delivery channel options (feed, email, sms, webhook) with specific constraints. This goes well beyond the schema's field-level 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 first sentence clearly states the tool's action and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinguishes it from siblings like list_subscriptions and unsubscribe, which manage existing subscriptions.

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

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

The description gives practical usage context: requires OAuth account, enumerates supported subscription types with concrete examples (e.g., sec_8k, polymarket_edge, fred_series), and explains delivery channels. It does not explicitly mention alternative tools for read-only alert retrieval (e.g., recent_alerts) or when not to use this tool, but the purpose and constraints are clear enough for an agent to select it appropriately.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return format: category-bucketed examples with exact tool+argument shapes, drawn from the live catalog. It doesn't mention any edge cases or limitations, but the added context is meaningful and doesn't contradict 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 and packed with necessary information. It front-loads example queries, lists the category buckets, and gives clear call instructions. While slightly verbose, every sentence contributes value and it remains readable.

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 role as an onboarding entry point, the description covers everything an agent needs: when to invoke, what to expect in the response, the argument behavior, and the context of the live catalog. Even without an output schema, the return format is clearly described, making the tool complete and self-explanatory.

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 (topic) with a description of allowed values. The description enhances this by explaining the effect of passing vs. omitting topic: 'Call with no arguments for the full spread, or pass topic (e.g. "finance", "pharma", "betting") to focus'. This adds practical usage nuance beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent that wants to know what questions to ask Pipeworx. It specifies the exact output (category-bucketed example questions with tool+argument shapes) and distinguishes itself from siblings by positioning itself as the FIRST tool to use when unfamiliar with Pipeworx's capabilities.

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

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

The description provides explicit guidance: '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 names specific alternatives (ask_pipeworx, entity_profile, compare_entities) and explains how to call with or without the 'topic' argument, covering when-to-use and alternatives.

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

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

Annotations already establish non-read-only, idempotent, non-destructive behavior. The description goes further by explaining ownership enforcement, deactivation (not deletion), and the preservation of historical events for recent_alerts. This adds valuable behavioral context beyond the structured fields, with 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 concise sentences: the first states the primary action, the second packs ownership, deactivation, and data retention implications. Every word earns its place; no redundancy or fluff.

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

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

For a single-parameter, no-output-schema tool, the description covers the essential behavior: action, ownership, effect on data, and relation to recent_alerts. Combined with the annotations, it provides a complete understanding for correct invocation.

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

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

Schema coverage is 100%—the single id parameter is fully described as 'Subscription id (uuid) returned by subscribe.' The description does not add extra parameter semantics beyond restating 'by id,' so the baseline of 3 is appropriate given the 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 opens with 'Cancel a subscription by id,' a specific verb+resource statement that unambiguously defines the tool's purpose. It differentiates from siblings like subscribe and list_subscriptions by focusing on cancellation, and adds ownership enforcement details.

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

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

The description clearly implies when to use it (to cancel a subscription) and adds a constraint ('you can only cancel your own subscriptions'). It does not explicitly name alternatives or when-not-to-use, but the sibling context makes the usage scope clear. The note about historical events via recent_alerts provides useful after-effect 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?

Annotations already declare safety (readOnly, openWorld, idempotent, non-destructive), but the description adds critical behavioral context: the distinction between 'could_not_verify' (check did not happen, carries verification_error) and 'unsupported' (no source found), tolerance percentage behavior, and the percent-delta math for financial claims. This transparency is essential for correct interpretation of results and goes well 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 long but well-structured, front-loading purpose and triggers before explaining the verification paths and return values. Every sentence contributes operational meaning, though it could be trimmed slightly without losing value. It is not wasteful, but it is denser than necessary for a simple tool.

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

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

With no output schema, the description thoroughly explains the possible verdicts, what 'could_not_verify' and 'unsupported' mean, the two verification pipelines, and the efficiency benefit. It gives enough operational detail for an agent to use the tool correctly without additional documentation. The description is comprehensive given 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?

The input schema provides complete descriptions for both parameters (claim and tolerance_pct), covering 100% of parameters. The description adds context about claim natural-language format and default tolerance cap but does not introduce new parameter-level detail beyond what's in 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 defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…'). It distinguishes itself from siblings by detailing the SEC EDGAR financial path and the grounded fallback for all other claims, demonstrating a specific verb+resource purpose.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides natural-language triggers. It explains the two distinct verification paths and the fallback for non-financial claims. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools, 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.