Dados Pt

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

Beyond annotations (safe, idempotent), description adds that it makes external LLM calls, explains cost implications for Anthropic, and describes return structure (per-model score, confidence, signals, raw_response).

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 with no waste: first sentence defines purpose and output, second sentence covers configuration, third sentence lists use cases. Front-loaded and efficient.

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, description sufficiently details return format and covers all parameters. Context about use cases and required fields 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%, and description adds value by clarifying default model, API key purpose, and providing concrete examples (e.g., 'Pipeworx', 'Acme Corp pricing') that aid agent understanding.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, distinguishing it from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks) and explains when to use default vs Anthropic API key, but does not mention alternatives or 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the routing behavior, automatic argument filling, single-call latency, citation URI output, and live-news handling. It adds meaningful behavioral context without contradicting the annotations.

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

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

The definition is long but front-loaded with the most important instruction, followed by scope, examples, and escalation guidance. There is some repetition around citations/grounding and 'START HERE', but the density is warranted for a broad default tool.

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

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

With no output schema, the description still adequately covers output form, input expectations, scope, and when to choose alternatives. It does not clarify how ask_pipeworx_beta differs or what happens on unsupported queries, but an agent has enough information 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 six parameters are aliases and the schema already documents them at 100% coverage, so the baseline is 3. The description adds value by specifying the acceptable input style: natural-language factual queries with trigger phrases and domain examples, which helps an agent phrase the question correctly.

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: it accepts a natural-language question, routes it to one of 5,798 source-verified tools, and returns a structured answer. It also differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research and positioning itself as the default fast entry point.

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 preference rules over web search, lists trigger phrases and concrete example queries, and explains when to escalate to ask_pipeworx_grounded or deep_research. It even preempts the breaking-news case by noting that ask_pipeworx already routes to live news packs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds beta-status context, explains that results are compared to the stable router, and explicitly states it falls back to nothing and is a full working router rather than a stub. This is valuable beyond annotations, though it could still mention response shape or rate-limit implications.

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 information-dense, front-loading the beta relationship to ask_pipeworx and stating the current no-candidate state. Every sentence contributes either routing guidance or behavioral clarification without repetition.

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

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

For a router tool with a simple single-required-parameter schema and safety annotations, the description covers what an agent needs: beta status, identical interface, current equivalence to stable, experimental purpose, and fallback behavior. No output schema exists, but the description explicitly notes the same response shape as ask_pipeworx, which is sufficient context.

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 q, text, input, query, and prompt all explicitly described as aliases for question. The description adds the context that arguments are identical to ask_pipeworx, but since the schema already covers all parameter aliases, the marginal value is limited. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx with identical universal routing across 5,798 tools and the same arguments and response shape. However, it does not independently state what ask_pipeworx itself does for an agent that hasn't seen that sibling, leaning on the sibling comparison rather than standing alone.

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

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

The description is explicit about when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that it is an experimental edge being compared against the stable router, and clarifies that it currently matches ask_pipeworx exactly with no candidate active. This gives an agent a concrete decision rule.

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

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

Even though annotations already mark the tool readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral detail: exact success and refusal return shapes, refusal reason enums, evidence extraction from verbatim quotes, and extra LLM call cost. 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 purpose, then groups behavior, return contracts, usage, and cost in an efficient sequence. Every sentence adds a distinct fact needed for correct selection or invocation; there is no filler or tautology.

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

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

Given there is no output schema, the description fully specifies the return envelope and refusal reasons, which is critical for an agent acting on grounded answers. It also covers unique behavior, when to choose it, and operational cost, leaving no essential gap for this complex sibling.

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 parameter semantics, including aliases for the question field, so the description need not repeat them. It adds workflow context (the tool fills arguments internally) but no meaning to the question parameter itself, matching the baseline for high schema coverage.

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

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

The description opens with a specific, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads,' and explicitly contrasts itself with ask_pipeworx by explaining it extracts answers only from fetched tool results. This makes the verb and resource clear and distinguishes it from nearby siblings.

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

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

It gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and lists representative high-stakes domains. It also states the alternative ('prefer ask_pipeworx for casual lookups') and the tradeoff (one extra LLM call).

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 extensively covers behavioral traits beyond annotations, including fan-out logic per classifier, resolver confidence handling, parent event extraction, news fallback mechanisms, safety short-circuits, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds necessary context for a complex tool, though some redundancy exists (e.g., duplicate notes on closed markets).

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

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

Given the tool's complexity and lack of output schema, the description provides complete coverage: input handling, processing steps, output structure, edge cases (closures, low confidence, wide spreads), and resolution risks. No gaps remain.

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

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

All three parameters are documented in the schema (100% coverage). The description adds value by explaining how depth and include_raw affect fan-out and response size, and clarifies the market parameter's flexibility (slug, URL, text).

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifying inputs like slug, URL, or question text. It distinguishes from siblings by detailing the full research pipeline (resolve, classify, fan-out, compare), which is unique among tools like polymarket_edges.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), along with examples per category. While it doesn't list alternatives or exclusions, the context is clear enough for an agent to determine when to invoke.

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

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

Annotations already indicate readOnly/openWorld/idempotent/non-destructive. The description adds valuable context: for company, it pulls LATEST 10-K data with fiscal year handling, and for drug, FAERS data. It also mentions results sorted by primary metric and returns citation URIs, going beyond annotations.

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

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

The description is concise (~100 words), well-structured with front-loaded trigger phrases, and every sentence adds value. 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?

Despite no output schema, the description covers return format (paired data + citations), addresses complexity (off-calendar fiscal years), and explains when to use. It provides complete context for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptions for both params. The description enriches understanding by explaining what data each type pulls (e.g., company: SEC EDGAR/XBRL revenue, net income, etc.) and giving concrete examples like tickers for company values. This adds significant value beyond the schema alone.

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

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

The description starts with explicit trigger phrases ("Compare X and Y", "X vs Y", etc.) and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sequential single-entity lookups, making its purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also explains the two entity types (company and drug) and what data each pulls, helping the agent decide which to use.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description goes well beyond that by disclosing account/pricing requirements, structured-source scope, parallel decomposition, the findings packet shape, explicit gaps[] (never invented), contradictions[], citation URI fetchability, excerpting behavior, and expected latency. This is exemplary 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 the tool is genuinely complex and every major clause adds useful operational context. It front-loads the critical auth/pricing gate and then proceeds logically through scope, mechanics, output, depth modes, and timing. Slightly dense, 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?

There is no output schema, so the description properly explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, citation URI, gaps[], and contradictions[]. It also covers auth prerequisites, latency, and depth behavior. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains question and depth in detail, including paid status, hop counts, and contradiction scans. The description mostly recaps these details rather than adding new parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states this is a grounded multi-source research tool over structured data, and explicitly contrasts it with open-web search and single-lookup tools. It names concrete use cases like 'compare X and Y's regulatory + financial exposure', making the purpose immediately distinguishable from siblings 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 gives explicit when-to-use guidance: broad/multi-part questions over structured data. It also gives explicit when-not-to-use and alternative routing: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' This is clear, actionable steering.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral details: returns top-N relevant tools with full input schemas and curated examples, ready to call directly. This goes beyond annotations and clarifies the output 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?

Three sentences, each serving a clear purpose: (1) state what the tool does and list domains, (2) describe the return format and its readiness, (3) provide usage guidance. No wasted words; front-loaded with the core purpose.

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

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

Despite no output schema, the description thoroughly explains what is returned (tool names, descriptions, schemas with examples). It also addresses the high parameter count by listing aliases and explaining the main parameter's behavior. Complete for a discovery 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%, and the description adds meaning by explaining that 'query' accepts natural language and lists aliases (task, q, search, description). It clarifies the limit parameter's default and max. This adds significant value over the raw 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and explains the return format (top-N tools with full schemas). This distinguishes it from sibling tools like deep_research or search_within, which serve different discovery needs.

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 advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it. However, it does not explicitly state when NOT to use it or list alternatives, leaving minor room for improvement.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful runtime behavior: it makes one parallel call fanning out across multiple sources, reports sources_used/sources_failed, and explicitly notes that an empty section means 'no data' rather than a bug. It also explains name resolution and the resolved:false behavior for private companies, which is valuable context not available from 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 dense and front-loaded, opening with trigger phrases and the core positioning before diving into source and return details. Every clause adds behavioral or usage nuance, but its wall-of-text format and heavy parenthetical asides make it slightly harder to parse than an ideal structured description.

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

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

For a complex multi-source tool with no output schema, the description is remarkably complete: it lists input shapes, the exact source fan-out, the return fields and URIs, failure semantics, private-company behavior, and type flexibility. An agent has enough information to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by giving concrete examples for value ('AAPL', '0000320193', 'Moderna'), clarifying that type values are interchangeable, and noting that names resolve via SEC EDGAR's company-name match. This goes beyond the schema text, though the schema already covers the core parameter meanings.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' and enumerates exactly what it fans out across and returns. It also differentiates itself from chaining 'single-pack SEC/XBRL/news lookups', so an agent can tell it apart from more granular tools.

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

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

The description explicitly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a clear when-to-use condition. It also specifies the accepted input forms (ticker, CIK, company name) and how private companies are handled, removing ambiguity about invocation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not reveal any new behavioral traits 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 short sentences, no wasted words. Every sentence adds value: purpose, usage guidance, and pairing with siblings.

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 required parameter, no output schema, and no nested objects, the description is complete and sufficient given the complexity.

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

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

Schema coverage is 100% for the single parameter 'key', with a description 'Memory key to delete'. The description adds no additional meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key'. Verb and resource are specific, and the description distinguishes from sibling tools like 'remember' and 'recall'.

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 scenarios: stale context, task done, clearing sensitive data. Mentions pairing with remember and recall, but does not detail when not to use or alternatives beyond these.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds process details: fetches the page, extracts title/description/key links, and emits standard format. This goes beyond annotations by explaining the workflow and output 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?

Three sentences: first states purpose and audience, second explains process, third lists use cases. No redundant words, front-loaded with key 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?

Given no output schema, the description explicitly states output is a 'single text blob ready to drop at site-root/llms.txt'. Parameter count is low (2) with full schema coverage. The tool is simple and the description covers all necessary information for an agent to use 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?

Input schema covers 100% of parameters with descriptions. The description clarifies the overall purpose ('production-ready', 'standard format') but does not add significant new meaning to individual parameters 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 the tool generates a production-ready llms.txt file for any URL, with specific mention of target AI crawlers. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on generating the standard llms.txt markdown document.

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 lists three explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI crawler view. While it doesn't explicitly state when not to use it or name alternatives, the context 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 cover read-only, idempotent, and non-destructive behavior. The description adds value beyond these by disclosing the output contents (description, license, update frequency, tags, downloadable resources with formats and URLs) and the external source (dados.gov.pt), which matters because there is no output schema. It does not cover rate limits or errors, but that is less critical for a simple fetch.

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

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

One sentence that front-loads the action and resource, then compacts the returned fields into a readable list. Every part earns its place, with no filler or tautological restatement of the title.

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

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

This is a one-parameter, read-only lookup with rich annotations and no output schema, so the description's inclusion of expected return contents makes it functionally complete. An agent can call it correctly with only the id or slug, which is all the tool needs.

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

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

The sole parameter is already documented in the schema at 100% coverage as 'Dataset id or slug.' The description repeats this phrase without adding format, syntax, or value constraints, so it provides no additional semantic value beyond the baseline.

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

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

States a specific verb ('Fetch'), a specific resource ('a single dataset from dados.gov.pt'), and the retrieval key ('id or slug'). The word 'single' helps distinguish it from list/search siblings such as search_datasets and recent_datasets, even though it does not name them.

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

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

The phrase 'by its id or slug' gives a clear condition for when this tool is appropriate: when the agent already has a dataset identifier. However, it does not explicitly point to alternatives like search_datasets for cases where the identifier is unknown, so some exclusionary guidance is missing.

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, and non-destructive behavior. The description adds context beyond those annotations by indicating the result scope (dataset counts and portal pages) and the data source, which helps an agent understand what to expect from the call. No contradiction exists.

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

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

The description is a single, front-loaded sentence that wastes no words. It states the operation, the target entities, the scope, and the output content efficiently.

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 rich annotations, a fully documented parameter schema, and a description that specifies return content, the tool is largely complete for correct invocation. It could improve by mentioning pagination behavior or explicitly routing to sibling search tools, but nothing critical is missing.

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

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

Schema description coverage is 100%, with page, query, and page_size each documented. The tool description does not add parameter-level detail beyond the schema, but because the schema is complete, this is acceptable and matches the baseline.

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

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

The description uses a specific verb ('List or search') and clearly identifies the resource: organizations publishing open data on dados.gov.pt. It differentiates from dataset-focused sibling tools by emphasizing organizational scope and enumerates returned content (dataset counts, portal pages).

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 makes its subject clear, so an agent can infer it is the right tool for organizational lookups rather than dataset searches. However, it does not explicitly mention sibling alternatives like search_datasets or state when not to use this tool, leaving usage guidance implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying returned fields and default filtering to active subscriptions, enhancing transparency beyond annotations.

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

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

Two sentences with no wasted words. The purpose and return fields are front-loaded, followed by usage guidance. Extremely concise and well-structured.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context adequately. Missing details like pagination or rate limits, but acceptable given the tool's simplicity.

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

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

Schema description coverage is 100% for the one parameter. The description reiterates the parameter's effect ('include_inactive' for cancelled subscriptions) but does not add significant new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb 'list' and resource 'subscriptions' with scope. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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 advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use it. No explicit when-not or alternatives, but sufficient 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 are all false, so the description carries the burden. It discloses the claim_token return process, the follow-up workflow to check status, rate limiting (5/day), that it is free, and that the team reads digests daily. This goes far beyond what annotations provide and gives the agent important operational context.

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

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

Although the description is long, every sentence earns its place: scope, when-to-use, counter-example, claim_token mechanics, rate limit, and cost. The structure flows logically from what → when → what not → how to follow up. No redundant or filler content.

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

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

The tool has 4 optional parameters, no output schema, and a nested context object. The description fully covers purpose, scope, constraints, return behavior, and follow-up flow. Given the low complexity and rich description, there are no informational gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for the claim_token parameter (how to reuse it to read responses) and provides guidance for message content (specific, 1-2 sentences, 2000 char max). This lifts it above baseline but not to 5, as the schema already documents all parameters well.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb+resource phrasing that distinguishes it from sibling tools, which are mostly research/query tools. No ambiguity about what this 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 explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion rule: only for tools served by this Pipeworx connection, with a 'Not sure?' test. It also tells users to file with other servers for non-Pipeworx tools. This is excellent usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). This provides additional context beyond annotations but doesn't cover all potential traits like 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?

The description is well-structured with numbered use cases and dashes for additional info. It is fairly concise for the amount of useful detail, though slightly longer than strictly necessary. No sentence is wasted.

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

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

Given the tool's simplicity (one optional enum parameter, no output schema), the description covers purpose, use cases, caching, and data origin. It does not explicitly state return format (likely a list/JSON), but that's minor given the context.

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 description adds meaning to the single 'window' parameter by explaining 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Since schema coverage is 100% and the description provides interpretive guidance, it adds value beyond the schema.

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

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

The description uses a specific verb+resource: 'returns top tools, top packs, and total call volume' clearly stating what the tool does. It distinguishes from siblings by focusing on aggregate trending data rather than specific queries or entity profiles.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case) which provide good context. However, it does not explicitly state when not to use this tool versus alternatives like discover_tools or search_within.

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 confirm read-only, idempotent, non-destructive behavior. Description adds extensive details: internal checks (monotonicity, partition_sum, semantic anchor, partition filter, fill check), output structure, and disclaimers about thin legs. 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?

Description is long but well-structured, with clear sections for each mode and internal details. Front-loads main purpose and uses bullet-style explanations. Some redundancy (e.g., repeated mention of 'partition_check' specifics) but justified by 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?

No output schema, so description fully documents response structure: 'opportunities[]' fields and 'partition_check' in event mode. Covers edge cases (skipped_low_similarity, partition filter, fill check) and provides actionable trading guidance. Highly complete for the tool's complexity.

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

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

Input schema covers both parameters with descriptions (100% coverage). Description enhances by explaining parameter values ('event slug like "fed-decision-may-2026"'), providing examples, and clarifying behavior (e.g., 'Full Polymarket URLs also accepted'). Adds significant value beyond schema.

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

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

The description clearly identifies the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also advises against trading when realizable_edge_pp ≤ 0 and suggests polymarket_fill_risk for custom sizing.

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

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

The description discloses caching (1h at KV level), diagnostics so callers see why segments are empty, and detailed model behavior, including tradeable-edge knobs and 24h-move warning. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds rich behavioral context without contradiction.

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

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

The description is long but well-structured: purpose first, then segment details, tradeable-edge knobs, response top-level, and caching. Every sentence adds necessary detail for correct usage. While it could be slightly more concise, the thoroughness is justified by the tool's complexity (9 parameters, three models, diagnostic output).

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 9 parameters, no output schema, and complex behavioral details, the description is remarkably complete. It covers the three model families, all knobs with usage context, response structure including diagnostics, a Fed bets note, and caching policy. No obvious gaps remain for an agent to understand what the tool does and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value beyond schema: e.g., min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs, max_spread_pp gives concrete guidance ('Set to 2 to require tight books'), and slippage_pp clarifies Polymarket's fee structure and practical bid/ask impact. Each parameter has explanatory text that aids agent decision-making.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific purpose of 'what should I bet on today'. It details three distinct response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage, polymarket_edge_tracker, and polymarket_fill_risk by focusing on discovery and ranking.

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 sets context: 'Built for what should I bet on today' and 'agents discover opportunities without paging hundreds of markets'. It also explains that Fed bets surface under fed_candidates but are excluded from ranking due to unreliable signal. However, it does not explicitly mention when not to use this tool or compare to siblings like polymarket_arbitrage (for specific arbitrage) or polymarket_edge_tracker (for tracking edges over time), which would strengthen usage guidance.

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

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

Annotations already denote read-only, idempotent, non-destructive. Description adds context about snapshot gaps (cache-miss), negative edge_pp_net meaning, and 60-day TTL, enhancing transparency beyond annotations.

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

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

Front-loaded with purpose, then logically covers response fields and limitations. Slightly verbose but every sentence adds value; could trim some explanatory asides.

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

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

Given no output schema, the description explains all response fields (tracked, expired, snapshot_dates) and limitations (TTL, gaps). Lacks a precise definition of edge_pp_net but covers key aspects.

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

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

Schema coverage is 100% with descriptions. The description adds defaults and clamp for 'days', meaning of 'window' families, and detailed response structure, providing added value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' built from daily snapshots, answering specific questions about edge duration and trend. It distinguishes from sibling 'polymarket_edges' by focusing on historical persistence.

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 context on when to use (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). Implies usage for historical trend analysis, but does not explicitly state when not to use or list 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), warns about forced directional risk and thin legs. No contradiction with annotations; description adds value beyond them.

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

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

The description is lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence is informative, but some redundancy could be trimmed. Given the two-mode complexity, it's acceptable.

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 no output schema, the description thoroughly documents all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, capture_ratio, thin_legs for basket). It also covers edge cases and risks, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: explains default for side in basket mode, clarifies size_usd interpretation (spend vs target proceeds for single-market, settlement notional for basket), and details market vs event modes. This 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool.

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

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

The description provides explicit guidance on when to use this tool: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or any polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable, partial fills create directional risk), giving clear context for usage.

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

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

Beyond the readOnly/idempotent annotations, the description discloses many non-obvious behaviors: both modes use the same token-overlap matcher, compatibility warnings can coexist with returned pairs, null temporal alignment does not mean aligned, Kalshi fees are not modeled, and matching is by keyword overlap rather than a shared resolution source.

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 it is organized into labeled sections for modes, response, safety fields, codes, and fee disclosures. Each sentence carries substantive behavioral or usage information, so verbosity is justified even though the text could be tightened.

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 thoroughly by naming the key response elements: leg-by-leg prices, top_spreads_pp, compatibility_codes, temporal_alignment, skipped counters, and fees_note. It also covers failure and ambiguity semantics, making it complete enough for an agent to call and interpret the tool correctly.

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

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

The schema already fully documents all three parameters, and the description adds meaningful behavior: topic auto-fetches a matching event, explicit identifiers override the topic-mapped side, and both modes run the same matcher. It does not expand much on parameter formats beyond schema examples, but that gap is minor.

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

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

The description states a precise purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also distinguishes the tool from Polymarket-only siblings by naming both venues and emphasizing the same-event matching constraint.

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 clearly explains the two usage modes—topic shortcuts versus explicit ticker/slug pairing—and warns that pre-mapped topics often return warnings and are not automatically tradeable. It does not name sibling alternatives explicitly, but it provides strong context for when to use the tool and how to choose between its modes.

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=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. The description adds behavioral context: scoping to identifier, listing behavior when omitting key, and pairing with other tools. 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?

Three concise sentences, each adding value. First sentence states primary function, second provides usage context, third mentions pairing. No wasted words.

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

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

For a simple retrieval tool with no output schema, the description fully explains behavior (single vs list), scoping, and relationship to sibling tools. Agent has sufficient information to use 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?

Input schema covers the only parameter 'key' with a clear description. The tool description restates that omitting key lists all keys, but adds minimal extra meaning beyond the schema. Schema coverage is 100%, so baseline 3 applies.

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

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

The description clearly states the tool retrieves a value or lists all keys, with specific verb ('retrieve', 'list') and resource ('value', 'keys'). It distinguishes from sibling tools 'remember' and 'forget' by naming them directly.

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: 'look up context the agent stored earlier... without re-deriving it from scratch'. Implicitly advises against using when save/delete are needed, and explicitly mentions pairing with 'remember' and 'forget'. Scoping is also clarified.

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?

Describes important behaviors beyond annotations: the mark_read parameter flags events as read, affecting future calls. Also notes the alternative REST endpoint. No contradiction with the readOnlyHint annotation.

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?

Concise and well-structured: starts with the main purpose, details returned data, lists filter options, explains mark_read behavior, and ends with polling note and alternative. No unnecessary sentences.

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

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

Covers key aspects: what events contain, filtering options, side effects of mark_read, and alternative access. Lacks explicit mention of unread_only behavior, but schema covers it. Without output schema, the description provides sufficient context.

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

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

Schema coverage is 100%, and the description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the purpose of mark_read. Some parameters like limit and unread_only are not elaborated in the description but schema covers them.

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 pulls fired events from the subscription feed, with specific verb and resource. It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on alerts 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?

Provides context for usage: polling works fine, and the same feed is available via a REST endpoint for scripts. However, it does not explicitly compare against sibling tools or state when not to use this tool.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: fans out to multiple sources (SEC, GDELT, USPTO), fallback from GDELT to GNews, soft-fail for patents, structured return format, and citation URIs. This goes well beyond what annotations provide.

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

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

The description is relatively long but front-loaded with example queries. Each sentence adds value (sources, fallback, parameter format, alternative tool). It could be slightly trimmed without losing information, but it remains efficient.

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 three required parameters and no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers source fallbacks, parameter options, and sibling differentiation. The tool's complexity (multiple data sources, failure modes) is well documented.

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 parameter descriptions. The description adds extra clarification: explains `since` accepts ISO date or relative shorthand with examples, recommends '30d' or '1m', and notes `type` only supports 'company'. This adds meaningful guidance 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 starts with example queries like "What's new with X" and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes from sibling tool `entity_profile` which is for static profiles.

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 states when to use this tool vs `entity_profile`: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It does not provide explicit when-not-to-use scenarios, but the alternative is well-defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds behavioral details beyond those annotations: the result set is specifically recently published datasets rather than all datasets or recent changes, and results are sorted newest first.

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 one concise sentence that front-loads the action and resource, then adds the source and sort order efficiently. The parenthetical about the Portuguese government open data portal is slightly redundant but still compact.

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 no required parameters, the description plus schema fully characterize how to invoke it. There is no output schema, so a clearer statement of the returned fields would improve completeness, but the term 'datasets' conveys the essential return value.

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 page_size has 100% schema description coverage, including range and default value. The description itself adds no additional parameter semantics, which matches the baseline for fully documented schema parameters.

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

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

The description opens with a specific verb and resource: 'Get the most recently published datasets' from dados.gov.pt, and even states the sort order. It clearly differentiates this from search_datasets by emphasizing recent publication rather than query-based search.

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

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

The description implies the tool is for browsing the newest dataset publications, but it does not explicitly say when to choose it over siblings like search_datasets or recent_changes, nor when not to use it. No exclusions or alternatives are mentioned.

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

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

Discloses that data is stored as key-value pairs scoped by identifier, with persistence differences: authenticated persistent, anonymous 24 hours. Consistent with annotations (idempotentHint=true, not readOnly). Adds behavioral context beyond annotations.

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

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

Three sentences front-loaded with purpose, then usage, then behavior. No redundant information. Efficient and easy to parse.

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

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

Covers purpose, usage, persistence behavior, and pairing with siblings. No output schema, but for a write tool this is acceptable. Could mention return value (e.g., success confirmation) but not essential.

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

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

Schema has 100% coverage with descriptions. Description adds example keys and clarifies value can be any text. Provides extra context like 'findings, addresses, preferences, notes' beyond schema's concise 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?

Clearly states the tool saves data for reuse across conversations or sessions. Gives concrete examples like resolved ticker, target address, user preference. Distinguishes from siblings 'recall' and 'forget' by mentioning them.

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 when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Provides context on persistence for authenticated vs. anonymous users. Lacks explicit 'when not to use', but usage is clear.

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

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses cascading internal lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, explicit unresolved identifiers, figi_candidates behavior for ambiguous matches, and source labelling. This gives the agent a rich picture of how the tool behaves in edge cases 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 dense and long, but it front-loads trigger phrases and the core purpose before diving into details. Most sentences earn their place by clarifying edge-case behavior or input constraints, though some parentheticals could be trimmed without loss. For the tool's complexity, the length is largely justified.

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

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

There is no output schema, so the description must carry the burden of explaining return behavior. It covers ambiguity via figi_candidates, partial failure via unresolved, enrichment degradation, source provenance, and cross-entity resolution via ISIN-to-LEI. An agent has enough context to select and call this tool correctly across the described scenarios.

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

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

Although the schema already describes both parameters at 100% coverage, the description adds meaningfully: it defines enum semantics for type, gives accepted input forms for value (ticker, CIK, ISIN, name, brand/generic), provides examples, and crucially warns against passing full noun phrases for bonds. This substantially helps correct invocation beyond the raw 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 clear verb-and-resource statement: resolve a user-spoken name to the canonical/official identifiers other tools require as input. It enumerates supported types (company, drug) and explicitly positions itself as the first step when a name needs to become an ID, distinguishing it from siblings like entity_profile and compare_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?

The description gives strong when-to-use guidance with trigger phrases like "What's the ticker for…" and the directive "Use FIRST whenever you have a name but need an ID." It also specifies accepted input formats and warns against passing full noun phrases. However, it does not explicitly contrast itself with closely related siblings such as entity_profile or compare_entities, so the when-not-to-use guidance is implicit rather than explicit.

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

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

Annotations already declare safe/idempotent. Description adds that it probes each entity with ai_visibility_check and returns ranked results with metrics. No contradictions. Could mention rate limits or error handling.

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 that front-load purpose and behavior, then use case and output. Every sentence adds value.

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

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

Covers purpose, behavior, output format. Lacks explanation of confidence/signal density metrics but sufficient for agent to understand. No output schema, but description mitigates.

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

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

Schema covers all 4 parameters with descriptions. Description adds extra meaning: first entity treated as 'subject', models default behavior explained. Adds value beyond 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?

Specific verb 'compare' and resource 'AI visibility across entities'. Clearly distinguishes from single-entity sibling ai_visibility_check and generic compare_entities. Explicitly states ranking and output.

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 case for competitive AI-marketing audits, but does not mention when not to use or explicitly list alternatives beyond implied distinction from single-entity probe.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral context beyond annotations: the composite nature, sources used, return structure (summary block, advisories, links, alternative versions), and failure handling (sources_failed if bundlephobia times out). 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?

Description is a single paragraph but front-loads the purpose and key details. It is dense but not overly verbose; every sentence serves a purpose. Could be slightly more structured with bullet points for readability.

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

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

Covers all essential aspects: composite nature, sources, return data fields, failure behavior, ecosystem limitation, and fallback guidance. No output schema, so description compensates well.

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 clear descriptions for both parameters (package, version). Description does not add new semantics beyond restating scoped package acceptance and default version behavior, so 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 starts with a clear composite purpose: 'should I add this npm package to my project' check. It specifies the verb (composite check) and resource (npm package dependency), and distinguishes from sibling tools by focusing on npm package analysis, which no other sibling explicitly targets.

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

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

Explicitly states when to use: 'when an agent asks is X safe / popular / small' and provides constraints: NPM ecosystem only, with alternatives listed for other ecosystems (deps.dev:version directly). Also mentions graceful degradation for bundlephobia delays.

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 that the tool is read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds useful behavioral context by specifying the kinds of fields returned (title, description, publishing organization, downloadable-resource counts), which helps because there is no output schema. It does not disclose pagination or portal-specific quirks, but the annotation coverage keeps this at a solid 3.

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 tight sentences with no filler. It front-loads the portal scope and then delivers the return-field summary. Every sentence adds substantive information, making it an efficiently structured definition.

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 search tool with fully documented optional parameters and strong safety annotations, the description is nearly complete: it identifies the exact portal, the multilingual query nature, and the key return fields. The lack of an output schema is partially mitigated by the return-field list, but the description does not specify the response shape or how to distinguish this tool from the dataset-related siblings. That small gap keeps it from a 5.

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%: page, sort, query, and page_size all have inline descriptions. The tool description adds overall context (the Portuguese open data portal) but no additional parameter-level meaning beyond what the schema already provides. The baseline of 3 applies because the schema carries the full parameter-documentation burden.

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

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

The description clearly identifies the action ('Search') and the resource ('datasets on dados.gov.pt'), and it adds valuable output detail by listing the fields returned. However, it does not explicitly contrast this tool with sibling tools like get_dataset or recent_datasets, so it lacks the explicit differentiation that would justify a 5.

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 no guidance on when to use this tool versus alternatives such as get_dataset for retrieving a specific known dataset or recent_datasets for seeing new additions. An agent must infer usage from the name and sibling list, with no explicit when-to-use or when-not-to-use direction.

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 significant behavioral context beyond the annotations: it specifies the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and input size cap (200K chars with truncation flag). These details are not present in the annotations and are crucial for correct usage.

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

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

The description is a single well-structured paragraph. The main purpose is stated upfront, with every sentence adding essential information (use case, output, limitations, pairing). No redundant or verbose language.

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 explicitly mentions that returned passages include character offsets and similarity scores. It also covers input limits, truncation behavior, and relationship to a sibling tool. The description is complete and leaves no critical questions unanswered.

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

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

With 100% schema coverage, the baseline is 3. The description enriches the parameter understanding by providing examples for the query parameter and clarifying the text parameter's character limit. This extra context 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 clearly states that the tool performs semantic search inside a fetched record, giving concrete examples (SEC 10-K, article) and contrasting with using the whole document. It also hints at differentiation from sibling tools like ask_pipeworx_grounded.

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

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

The description explains when to use the tool (when the record is too big to fit in the prompt) and how it pairs with ask_pipeworx_grounded, but it does not explicitly state when not to use it or list alternative tools.

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

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

The description richly details behavioral traits: return value (subscription id), idempotent nature (implicit from creation), delivery channels with constraints (e.g., SMS 10/day cap, webhook auto-disable). These go well beyond the annotations, which only hint at idempotency and non-destructiveness. No contradictions with annotations.

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

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

The description is a single dense paragraph but front-loads the key action. It efficiently packs examples and constraints without being overly verbose. Could benefit from slight restructuring (e.g., bullet points for types) but is acceptably concise.

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

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

Given no output schema, the description mentions the return value (subscription id). It covers all parameter aspects, delivery options, and type details. It does not address error cases or idempotency behavior explicitly, but those are covered by annotations. Fairly complete for a creation 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?

With 100% schema coverage, the baseline is 3. The description adds significant value by giving concrete examples (e.g., items for sec_8k, topic for polymarket_edge) and clarifying delivery constraints (e.g., phone must be verified). However, it largely mirrors 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 verb 'Create' and the resource 'a proactive monitoring subscription to a live-data event stream'. It also mentions the return value (subscription id). The purpose is specific and distinguishes the tool from sibling tools like list_subscriptions and unsubscribe.

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 prerequisites (Pipeworx OAuth account) and mentions constraints (anon/BYO not supported). It does not directly compare to siblings, but the context of subscription creation is clear. It could be improved by stating when to use this vs. list_subscriptions or unsubscribe.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the tool returns dynamic example questions drawn from a live catalog, without contradicting any annotations.

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

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

The description is front-loaded with the purpose and includes a list of example natural language queries that make it clear how to invoke the tool. It is somewhat lengthy but every sentence adds value, and the structure is logical.

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 simple interface (one optional parameter, no output schema) and the annotations that cover safety and behavior, the description provides sufficient context about what the tool returns and when to use it. It explains the return format and the dynamic nature of the catalog.

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 a clear description for the topic parameter. The description adds extra value by explaining that omitting topic gives a full spread and providing example values, enhancing understanding beyond the schema.

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

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

The description explicitly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs and resources ('returns category-bucketed example questions... each with the exact tool + argument shape') and distinguishes from siblings by indicating it should be used first.

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

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

The description clearly states when to use the tool ('FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.') and how to call it (with or without the topic argument). It does not explicitly state when not to use it, but the context is sufficiently clear.

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

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

Adds details beyond annotations: ownership check, logical deactivation (not deletion), and preservation of historical events. Annotations already indicate idempotent and non-destructive, so description complements well.

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, no wasted words. All essential information is presented efficiently.

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

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

For a tool with one required param and no output schema, description covers purpose, ownership, side effects, and links to related tool ('recent_alerts'). Complete.

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

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

Schema coverage is 100% with clear description of 'id' parameter. Description does not add new meaning beyond what schema already provides for the parameter.

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

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

Clearly states 'Cancel a subscription by id.' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_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?

Provides context on ownership enforcement, implying when to use (own subscriptions). No explicit exclusions or alternatives, but sufficient for a simple tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the critical caller warning that could_not_verify means the check did not happen and must not be treated as evidence (with verification_error{stage,detail}), the difference between could_not_verify and unsupported, the verdict vocabulary, and the structured vs. grounded pipeline routing. It loses one point because it doesn't discuss rate limits, latency, or cost for the fallback grounded pipeline, which could affect agent decisions, but the core behavioral nuance is well disclosed.

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

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

The description is long but information-dense and front-loaded with trigger phrases. Every sentence earns its place: trigger examples, routing logic, verdict list, citation format, caller warning about could_not_verify, and replacement value proposition. It loses one point for being somewhat long and for the parenthetical list of verdicts being a bit heavy; a tighter version could trim the trigger-phrase list without losing meaning. Still, it is well-structured and avoids 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 the tool has no output schema, the description compensates fully by enumerating the exact verdict vocabulary, the citation format (pipeworx://), the reasoning inclusion, and the error-state semantics. For a 2-param tool with 100% schema coverage and readOnly/idempotent annotations, the description covers functionally everything an agent needs to select and invoke the tool, interpret results, and avoid misuse (could_not_verify warning). The only minor gap is cost/latency of the fallback pipeline, but that is not essential for correct invocation. This is a complete, production-grade description.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly: claim with natural-language examples, tolerance_pct with range, override semantics, and default behavior. The description adds value by explaining how tolerance_pct interacts with claim wording ("Overrides the tolerance implied by the claim wording") and by tying the claim parameter to the tool's overall routing logic. It doesn't add much beyond the schema, but the schema already carries the heavy lifting, so a 4 is fair (baseline 3 for full coverage, plus the added semantic framing of the tolerance override and claim verification pipeline).

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

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

The description starts with natural-language trigger phrases ("Is it true that…", "fact check", etc.) and states a specific verb+resource: 'natural-language claim verification against authoritative sources'. It clearly distinguishes from siblings like resolve_entity, search_within, compare_entities, and deep_research by naming its unique job (verify claims, return verdicts) and by explicitly noting it replaces 4–6 sequential calls. The scope is concrete (company-financial via SEC EDGAR/XBRL fast path; everything else falls through to grounded pipeline).

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides negative guidance by enumerating trigger examples and by distinguishing structured vs. unstructured fallback paths. Sibling differentiation is implicit through tool name ('validate_claim' vs 'resolve_entity' vs 'search_within') and explicit in the 'Replaces 4–6 sequential calls' note, which tells agents this is the consolidated alternative to a multi-step pipeline.

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