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 read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context: it routes to 5,430 tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This 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 every sentence earns its place. It is front-loaded with the key preference statement and then provides examples and alternatives. A few phrases like 'START HERE' and 'default entry point' are slightly redundant, but overall it is well-structured and not wasteful.

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

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

Given the tool's complexity (routing across thousands of sources) and lack of output schema, the description covers return format (citations), examples, alternatives, and the tool's role as a default entry point. It is sufficiently complete for an agent to select and 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% with all six parameters being aliases for the same 'question' string. The schema already describes each parameter and provides examples. The description mentions examples too, but they are redundant with the schema and don't add constraints like length, format, or nuance beyond what's already there.

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

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

The description clearly states it is a natural-language question answering tool that routes to 5,430 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research for different use cases.

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

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

It explicitly says to prefer this over web search for a wide range of factual questions, provides example queries, and even gives step-up guidance: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. This is exemplary when-to-use/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?

Beyond annotations (readOnly, idempotent, etc.), the description adds crucial behavioral context: it discloses that candidate routing improvements are enabled live only when under test, that currently no candidate is active (retired 2026-07-26), and that behavior matches ask_pipeworx exactly. This is rich transparency about the experimental edge.

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 dense sentences pack necessary information without wasted words. The structure is front-loaded with the key identity, followed by current status and usage. It is slightly long but 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?

The description fully covers the tool's purpose, current live status, behavioral expectations, and relationship to the stable router. It mentions the same response shape as ask_pipeworx, compensating for the lack of an output schema. Even without output schema, the description is complete for a beta router.

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

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

The input schema provides 100% coverage with six parameters, all documented as aliases for 'question'. The description adds no additional parameter meaning, but the schema fully documents the sole semantic input, so the baseline of 3 is appropriate.

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

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

The description identifies the tool as a 'universal router' and a beta version of ask_pipeworx, clearly distinguishing it from the stable ask_pipeworx and grounded variant. However, it lacks a direct verb like 'routes' or 'answers' and instead relies on the instruction to use it like ask_pipeworx.

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

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

The description explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies it is not a fallback ('Falls back to nothing'). It does not mention when-not-to-use conditions or alternatives beyond 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/openWorld/idempotent annotations, the description discloses refusal behaviors with a full list of refusal_reason values, the return shape including verbatim evidence, and the operational detail of costing an extra LLM call. It also clarifies that it only uses the tool result content, preventing over-trust in the model's priors. No contradictions with annotations.

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

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

The description is dense but every sentence contributes: purpose, behavior, return schema, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the core value proposition and structured with clear lists for return/refusal fields. No filler or redundancy.

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

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

Despite lacking an output schema, the description fully documents the success and refusal shapes, including specific fields and values. Combined with the sibling differentiation, usage policy, and cost note, the description is complete 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?

The schema covers all 6 parameters (question and 5 aliases) with 100% description coverage, so the description does not need to add param details. It does not, but that is acceptable. The baseline of 3 applies because the schema already sufficiently explains the parameter semantics.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, describes its routing and extraction behavior, and distinguishes it from the sibling ask_pipeworx by emphasizing grounded answers with evidence. Specific verb ('EXTRACTS') and resource (answer from tool result) make 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also provides exclusions and alternatives: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This gives clear decision guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld, 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?

Annotations already declare readOnly/idempotent/safe, and the description goes beyond by disclosing account/payment requirements, latency expectations, gap[] behavior, no-invention guarantee, semantic excerpting, contradictions, and hop/citation fields. It enriches the agent's mental model without contradicting the annotations.

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

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

The description is long but packed with non-redundant information. However, it is a single dense paragraph with no structural breaks, which slightly impairs scannability. Every sentence earns its place, so it merits a 4 rather than a lower score.

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

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

Given the tool's complexity, the description covers all key aspects: authentication, pricing, use cases, alternatives, output format (findings packet, gaps, contradictions, hop, citation_uri), and latency. Since there is no output schema, this verbal specification is essential and fully provided.

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?

Input schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantics for `depth` by explaining standard/thorough gap-recovery and contradiction behavior, and for `question` via examples of broad/multi-part queries. This pushes it above the baseline but still relies fairly heavily on 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1408 STRUCTURED data sources' in ONE call. It also distinguishes itself from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and current news, making tool selection unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', plus the signed-in requirement. This is exemplary guidance with clear alternatives and exclusions.

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

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

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?

Annotations are all false-valued hints, so they say little about behavior. The description compensates by disclosing rate limits ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), and operational context ('team reads digests daily and signal directly affects roadmap'). It does not spell out whether submission is destructive, but the nature of 'telling' a team is low-risk and the rate-limit info is more valuable.

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

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

The description front-loads the purpose and uses paragraph breaks for readability. It contains eight sentences, all of which add value—scope, exclusions, content guidance, and rate limits. A slight amount of repetition exists ('Tell' and 'Use when' both imply submission), but nothing is wasted. It is denser than ideal but not bloated.

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 feedback tool with no output schema, the description is exceptionally complete: it specifies the exact trigger conditions, the system boundary (Pipeworx-only), content constraints (mention tools not user prompts), and operational details (daily digest, roadmap impact, rate limit, quota exemption). An agent can decide when to invoke it and what to provide without 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?

Schema coverage is 100%, so the baseline is 3. The description adds semantics by mapping type values to concrete scenarios ('returns wrong/stale data' → bug, 'wish existed' → feature/data_gap, 'worked surprisingly well' → praise). It also instructs how to phrase the message: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which enriches the message parameter beyond its schema description.

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

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

The description opens with a clear, specific purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It goes on to enumerate the feedback types (bug, feature/data_gap, praise), which maps directly to the tool's scope. This clearly distinguishes it from sibling tools like ask_pipeworx or research tools, none of which are feedback mechanisms.

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 'Use when' conditions are stated for each feedback category: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead,' plus a disambiguation rule for identifying Pipeworx tools.

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

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

Beyond 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral details: compatibility_warning conditions, temporal_alignment implications, skipped_cross_type counters, and the fact that pre-mapped shortcuts rarely yield tradeable spreads. This adds substantial context on edge cases and output interpretation.

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

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

Though lengthy, the description is efficiently structured with bold section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence contributes specific information about modes, output fields, or edge cases. It avoids fluff and is appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully defines the response structure: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross_type counters. It explains the meaning and conditions of each field, making the tool usable without additional documentation.

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 three parameters are already described in the schema (100% coverage), giving the baseline of 3. The description adds meaningful semantic context by explaining how the parameters interact (topic as a shortcut, explicit identifiers overrides) and what each identifier type represents (event ticker vs event slug), which goes beyond the schema descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by specifying two modes (topic shortcuts vs explicit event identifiers) and the unique risk of non-equivalent bet shapes.

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

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

It explicitly explains two usage modes (pre-mapped topics vs explicit tickers/slugs) and warns that most pre-mapped topics currently return compatibility warnings, implying when the tool's output should not be trusted. However, it does not explicitly name alternative sibling tools for similar tasks, so it misses the exclusion part of '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 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 read-only/idempotent behavior. Description adds valuable detail: return fields (ticker, CIK, RxCUI), sources (SEC EDGAR, RxNorm), citation URI format, auto-disambiguation, and internal cascading lookups. No contradiction with annotations.

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

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

The description is compact and front-loaded with user intent examples. Every sentence adds information about behavior, inputs, or outputs; no filler or redundancy.

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

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

Given no output schema, the description adequately explains return values for both entity types, including data sources and citation URIs. It covers auto-disambiguation and the fact that it replaces manual lookups. Minor gap: no error-case discussion, but not essential for a lookup tool.

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

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

Schema covers both parameters well (100%). Description adds extra meaning beyond schema: for 'type' it specifies per-enum outputs, and for 'value' it gives accepted input forms (ticker, CIK, name; brand/generic). This elevates it above the baseline 3.

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

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

The description clearly states the tool resolves names to canonical identifiers, with concrete example queries and explicit supported types (company/drug). It distinguishes from siblings by noting it produces IDs that other tools require as input.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' which is clear when-to-use guidance. However, it does not name alternative tools or explicitly state when not to use, so it stops short of a 5.

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

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the dual-path behavior (SEC EDGAR + XBRL fast path vs. grounded pipeline), exact percent-delta math for financial claims, the enumerated verdicts (confirmed/approximately_correct/refuted/inconclusive/unsupported), and that answers include citations and reasoning. No contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and organized logically from usage to routing to return fields. It is longer than minimal, but every clause carries information (routing, verdicts, citations, efficiency benefit), and there is no redundant 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?

With no output schema, the description must explain return semantics, and it does: verdict enum, actual value, citation, reasoning. It also covers the main branches of behavior (financial vs. other claims) and how tolerance defaulting works, making it complete for a complex claim-verification 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 both parameters in detail with 100% coverage, including examples and tolerance guidance. The description adds occasional context (e.g., 'exact percent-delta math' and hallucination-detection use case) but does not substantially extend beyond the schema, 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 uses explicit verbs like 'verify', 'fact check', and 'confirm or refute' tied to the resource 'natural-language claim verification against authoritative sources'. It clearly differentiates this tool from sibling search/ask tools by focusing on judging truthfulness of a claim rather than retrieving information.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives a routing rule for company-financial vs. other factual claims. However, it names no alternative tools or when-not-to-use scenarios, though the 'Replaces 4-6 sequential calls' note provides some context.

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