Tatoeba

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b, free), the BYO-key cost model for Anthropic, and the exact return shape (per-model score/confidence/signals/raw_response plus a combined view). No contradiction with annotations.

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

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

Three sentences with no wasted words. The main action and output are front-loaded, the default model and cost nuance are stated efficiently, and 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?

Even though there is no output schema, the description explains the return format and combined view, covers the default model and API key handling, and lists concrete use cases. It could elaborate on what 'signals' contains or how the score is computed, but for a tool of this complexity it is nearly 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?

With 100% schema coverage, the baseline is 3. The description adds meaning beyond the schema by clarifying the default behavior of the 'models' parameter (free Workers AI by default) and the purpose of '_apiKey' (pass-through, direct billing). It also reinforces the 'context' parameter's disambiguation role.

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 action ('Probe one or more LLMs') and specifies the resource (business/brand/product/topic) and the measurable outcome (visibility score 0-100 per model). It distinguishes itself from sibling tools like scan_competitor_ai_presence by covering any entity, not just competitors, and by returning per-model scores.

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

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

Explicitly names use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to supply an API key (to also probe Anthropic, with cost implications). It does not explicitly mention alternatives, but the use-case framing gives clear contextual guidance.

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

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

Beyond the read-only and non-destructive annotations, the description discloses routing behavior, argument filling, and the stable pipeworx:// citation URIs in results. It doesn't mention rate limits or auth, but annotations already cover safety, so the added context earns a 4.

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

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

Though long, the description is front-loaded with 'PREFER OVER WEB SEARCH' and each sentence adds distinct value: scope, alternatives, examples, and escalation paths. No filler or repetition of schema info.

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 default entry-point tool with no output schema, the description covers what it does, when to use it, result format, source coverage, and when to step up to alternative tools. This is 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?

The input schema already documents the main 'question' parameter and aliases with 100% coverage. The description adds examples and scope but no additional parameter-level semantics, so it stays at the baseline of 3.

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

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

The description clearly states what the tool does: routes factual questions to the right one of 5,344 tools across 1,393 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them as alternatives.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specific when-not-to-use instructions via 'Step up only when needed' for grounded and deep_research. It also lists many example triggers and question types.

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 meaningful behavioral context beyond the annotations: it reveals the tool's beta nature, that candidate routing improvements are enabled live, and that results are compared against the stable router. It also clarifies current equivalence to ask_pipeworx. While annotations already cover read-only/idempotent safety, this extra context about the experimental edge is valuable.

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

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

The description is concise and front-loaded, with the beta status stated immediately. Each sentence adds relevant information about the routing improvements, current state, and usage. The final sentence 'Falls back to nothing — this IS a full working router' is slightly redundant but reinforces the tool's completeness.

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

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

The description conveys the essential context: it is a beta router with identical tools/arguments/response shape, currently matching the stable version, and to be used for the newest routing. It relies on the sibling ask_pipeworx for full understanding of what the router does, but given that sibling exists, it is sufficiently complete for an agent to make an informed choice.

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

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

The input schema has 100% coverage, describing question and its aliases clearly. The description only says 'same arguments' without adding further detail, so it does not compensate or enhance beyond an already complete schema. Baseline 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router with the same 5,344 tools and arguments. It explicitly distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded siblings by highlighting its experimental routing improvements, making its purpose and differentiation unambiguous.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and specifies the condition for use. However, it does not state an explicit when-not (e.g., when stability is critical), so it falls slightly short of a 5.

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

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

The description adds rich behavioral detail beyond the annotations: it explains the grounded extraction using "ONLY what the tool result contains", the success return shape with evidence, and the explicit refusal reasons. It also discloses the additional cost. This goes well beyond the readOnly/idempotent hints and does not contradict them.

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

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

Three sentences, front-loaded with the core purpose, then mechanics, then usage guidance. Every sentence carries necessary information without redundancy. The description is information-dense yet 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?

Since there is no output schema, the description fully explains both the success and refusal return formats, including specific refusal reasons. It also covers routing behavior, grounding guarantee, and cost tradeoff, making the tool's behavior and use case self-contained.

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

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

Schema coverage is 100% with all six properties being aliases for the same 'question' parameter, which is already described in the schema. The description adds no parameter-specific detail, but it also doesn't need to. Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a "hallucination-resistant answer mode for high-stakes reads" and differentiates it from the sibling ask_pipeworx by stating "Same routing as ask_pipeworx" but with extraction and refusal behavior. It uses specific verbs like "extracts" and specifies the resource (the tool result).

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

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

Explicit when-to-use guidance is given: "Use whenever an answer will be quoted, cited, or acted on...". It also provides when-not-to-use via "prefer ask_pipeworx for casual lookups" and names the alternative tool. The cost tradeoff (extra LLM call) further clarifies the decision boundary.

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, destructiveHint=false, and the description goes far beyond them. It discloses blocking behaviors (low_confidence_match, market_closed_or_inactive), safety mechanisms (suppressed fields, illiquid warnings), news fallback flags (_fallback_attempted), and resolution-rule risk (cancellation_rule parsing). 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 exceptionally long and not concise, though it is well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). The first sentence front-loads the purpose, but the volume of detail may impose a parsing burden, making it less than ideal for brevity.

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, no output schema, and 3 parameters, the description is remarkably complete. It explains response shapes (result.market, result.analysis, result.evidence), resolver contract (match_confidence, match_score, alternatives, suggestions), parent_event extraction, news fields, safety statuses, and resolution-rule risk. Every edge case seems covered.

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

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

The input schema already covers all 3 parameters with detailed descriptions (market, depth, include_raw), so baseline is 3. The description adds some context about how market input is interpreted (slug, URL, or question text) and provides fan-out examples that inform depth, but it does not materially expand beyond the schema's 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 opens with a specific verb+resource combination: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings by focusing on research of a single bet with data fan-out, and provides concrete usage examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 the tool via 'Use for...' examples and provides extensive context on how it behaves (classifiers, fan-out, safety). It does not explicitly name alternative tools or state when NOT to use it, but the usage context is clear and the resolver contract gives conditions for caution.

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 substantial behavioral context beyond the read-only/open-world/idempotent annotations: it details data sources (SEC EDGAR/XBRL, FAERS/FDA), off-calendar fiscal year handling, sorting by primary metric, and return format with citation URIs. There is no contradiction with the annotations.

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

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

The description is dense but structured, opening with trigger phrases, then outlining the core function, type-specific details, sorting behavior, and return data. While slightly long, every sentence provides necessary information and the formatting with quotes and em-dashes keeps it readable.

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

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

For a complex tool with two entity types, the description covers core functionality, data sources, sorting, return format, and scale (replaces multiple lookups). There is no output schema, so the description's explanation of paired data and citation URIs fills that gap. It is complete for an agent to select and invoke correctly.

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

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

Even though schema coverage is 100%, the description enriches both parameters: for 'type' it explains what each enum value pulls (revenue/net income for company; adverse-event counts for drug), and for 'values' it details the accepted formats (tickers/CIKs, drug names) and limits. This adds significant meaning beyond the terse 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 a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It lists trigger phrases and distinguishes the tool from single-entity lookups, making its purpose unambiguous and differentiating it from siblings like entity_profile or 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?

It explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and outlines when to use it (comparisons, rankings, head-to-head). It also mentions it replaces 8–15 sequential lookups, providing clear context for choosing this tool over alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior; the description adds rich behavioral detail: account/paid-tier requirements, latency ranges, decomposition/routing mechanics, findings packet structure, gaps[], contradictions[], citation_uri/hop fields, and semantic excerpting. There is 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 information-dense, with the critical account caveat and sibling differentiation front-loaded. Every sentence contributes operational value, though some depth-related details duplicate what the schema already specifies, adding modest redundancy.

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

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

With no output schema, the description thoroughly explains the return format: findings packet, verbatim evidence with confidence/source/fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers performance expectations and failure modes (e.g., empty gaps for non-structured current events), making the tool's behavior fully comprehensible.

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

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

The input schema already provides 100% coverage with detailed descriptions of `question` and `depth` (including defaults and per-depth behavior). The description mostly reinforces these details rather than adding new parameter-level meaning, though it does append account-tier and latency context tied to depth.

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: grounded multi-source research over 1393 structured data sources, decomposing questions into facets and routing to 5,344 tools in parallel. It explicitly contrasts itself with ask_pipeworx and open-web search, making it distinct from siblings.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, and names ask_pipeworx for single lookups or breaking/current-news topics. It also states the account prerequisite and the fallback tool if not signed in, covering both use and exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds valuable behavior: returns top-N results, includes ready-to-call schemas, and saves a second lookup. It does not cover edge cases like empty results, but the added context goes beyond the annotations.

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

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

The description is three sentences: what it does, when to use, and what it returns. Every sentence adds useful information, no filler or repetition. Front-loaded with the 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?

With no output schema, the description explains return value (tool names, descriptions, schemas) and the 'ready to call' property. It covers domain scope and usage context. It could mention error behavior or empty result handling, but for a simple discovery tool this is sufficient.

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

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

Schema description coverage is 100%, so the schema fully documents 'query' and its aliases plus 'limit'. The description adds no extra parameter semantics beyond repeating that the task should be described naturally. Baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Find tools by describing the data or task.' It explicitly lists the types of data/tasks covered and states it returns tool names, descriptions, and full input schemas, making it distinct from the sibling data-search tools like 'search' and 'search_within.'

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 direct guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly indicates when to use it, though it does not explicitly name alternatives or exclusion cases.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, GDELT/GNews, GLEIF), mentions the PatentsView API sunset and soft-fail behavior, and notes the GDELT→GNews fallback. This exceeds annotation coverage without contradicting it.

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

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

The description is longer than ideal but front-loaded with user intents and a strong directive. Each detail (return fields, soft-fail notice, name unsupported) serves a purpose for a complex tool. Slightly verbose but well-organized.

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

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

Despite no output schema, the description enumerates all return sections (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and includes operational caveats (patent API sunset, name unsupported). This fully compensates for the missing output schema.

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

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

Schema covers both parameters with descriptions, including the enum for type and value format. Description reiterates the ticker/CIK format and name restriction, but adds little beyond schema examples. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states it creates a 'full cross-source profile of a US public company' with examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for name-only queries.

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

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

Provides explicit when-to-use guidance: holistic company information in one call. It contrasts with chaining single-pack lookups and instructs to use resolve_entity first if only a name is available, naming the alternative 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 include destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds useful context beyond that: it clarifies the target as 'previously stored memory' and the rationale for clearing 'sensitive data the agent saved earlier.' This provides extra behavioral context without contradicting the annotations.

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

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

The description is two sentences long and front-loaded with the action verb ('Delete'). Every sentence contributes: the first defines the operation, and the second provides usage context and sibling relationships. There is no redundancy or filler.

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

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

For a simple one-parameter tool with annotations and no output schema, the description adequately covers the purpose, usage timing, and relationship to sibling tools. It does not mention return behavior or edge cases (e.g., nonexistent key), but the tool's simplicity makes this acceptable. A higher score would require explicit handling of such details.

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 'key' parameter, which is described as 'Memory key to delete.' The description's mention of 'by key' and 'previously stored memory' adds only slight semantic enrichment. Since the schema already fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description opens with the specific verb+resource: 'Delete a previously stored memory by key.' It clearly distinguishes the tool from siblings like 'remember' and 'recall' by specifying the delete operation and key-based targeting. This leaves no ambiguity about what the tool does.

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

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

The description provides concrete when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also positions the tool relative to siblings with 'Pair with remember and recall.' However, it does not explicitly state when *not* to use the tool, so it falls short of the full 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains the workflow: fetches the page, extracts title/description/key links, emits standard llms.txt markdown, and produces a single text blob. This adds valuable behavioral detail that annotations do not convey.

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

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

The description is three sentences, front-loaded with the primary action. Each sentence earns its place: purpose, process, and use cases. No filler or repetition.

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

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

Given the simple 2-parameter schema and absence of an output schema, the description covers the process, output format, and use cases comprehensively. It is self-sufficient for an agent to decide when and how to 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%: both url and max_links have clear descriptions in the input schema. The tool description mentions 'any URL' but does not add extra meaning about max_links or parameter interaction, so the baseline of 3 is appropriate.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL,' which is a specific verb+resource pairing. It clearly distinguishes this tool from siblings by focusing on generation rather than scanning or checking, and mentions the output format.

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

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

The 'Useful for' clause lists concrete scenarios (client indexing, own project, competitor audit), providing clear usage context. However, it does not explicitly state when not to use the tool or name alternative sibling tools, so it stops short of full exclusion guidance.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds only the scope ('all languages') and the output content, but no additional behavioral details like pagination or error cases. It does not contradict annotations, but also doesn't go beyond them significantly.

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 sentence that front-loads the core action and includes a crucial usage hint. Every word earns its place; no fluff or redundancy.

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

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

For a parameterless list tool with an output schema and strong annotations, the description is complete. It tells the agent what it returns and how to apply the results. No additional context is needed.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. Per the baseline for 0 params, this scores 4. The description does not need to explain parameters, and the mention of 'codes' is a return-value reference, not a parameter.

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

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

The description states a specific verb ('List'), a clear resource ('all languages supported by Tatoeba'), and the key data returned ('ISO 639-3 codes and sentence counts'). It clearly distinguishes itself from siblings by explaining how the codes are used in the 'search' 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 a direct usage directive: 'use codes as `from`/`to` values in `search`.' This implies when to use the tool (to obtain valid language codes) and connects it to a sibling tool. It does not explicitly state exclusions, but the guidance is clear and useful.

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 the tool as read-only and non-destructive. The description adds context by specifying that only active subscriptions are listed by default and detailing the return fields, which goes beyond the annotation hints. It does not explain every edge case, but given the strong annotation coverage, a 4 is appropriate.

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 at two sentences, with the first stating the action and return fields and the second giving usage guidance. Every sentence earns its place, with no fluff or repetition.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the purpose, return fields, and usage context. Combined with the annotations (read-only, idempotent, non-destructive) and full schema coverage, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema fully documents the only parameter (include_inactive) with a clear description, so schema coverage is 100%. The tool description adds no parameter-specific detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the exact returned fields (id, type, params, created_at, last_fired_at, fire_count). This specific verb+resource phrasing distinguishes it 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 provides explicit use cases: reviewing current monitoring before adding more subscriptions and finding an id to cancel. It does not explicitly mention alternatives or exclusions, but the context is clear, so it earns a 4 rather than a 5.

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

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

Annotations are all false and provide no specific safety cues, so the description carries the burden. It adds concrete behavioral details: rate-limited to 5 per identifier per day, free and not counted against tool-call quota, and that the team reads digests daily. This goes beyond what annotations convey and gives the agent actionable constraints.

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

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

The description is a single, compact paragraph that front-loads the core action in the first sentence, then efficiently covers usage, constraints, and impact in two more sentences. No wasted words; every sentence earns its place.

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

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

For a feedback submission tool with no output schema, the description provides all needed context: what to include, when to use it, and what happens after submission (digests and roadmap impact). It covers edge cases like the 'other' type via the schema enum, and the requirements are fully described. No 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?

While the schema already has 100% coverage of parameters, the description augments it with practical guidance: describe issues in terms of Pipeworx tools/packs, avoid pasting end-user prompts, and keep message to 1-2 sentences with a 2000-char max. This adds context that helps the agent compose a useful feedback message 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 uses the specific verb 'Tell' with a clear resource (the Pipeworx team) and states the exact purpose: report something broken, missing, or needed. It also names concrete feedback types (bug, feature, data_gap, praise) which distinguishes it from sibling research/search tools.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a negative guideline ('don't paste the end-user's prompt'), which clarifies boundaries versus alternatives.

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

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

Annotations already state readOnlyHint=true and idempotentHint=true, and the description adds non-redundant behavior: caching ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). This gives the agent a fuller model of what to expect.

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: a lead sentence, a bulleted use-case list, and a terse note on aggregation and caching. No filler; each sentence adds information.

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

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

The tool has a simple invocation (one optional parameter) and complete annotations; the description covers return content, time frames, caching, and data limitations. The lack of an output schema is compensated by the explicit 'Returns the top tools...' and 'just (pack, tool, count)'.

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

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

The only parameter 'window' is fully documented in the schema with enum values and meaning, showing 100% coverage. The description merely restates the window options without adding new parameter details, so it doesn't elevate beyond the schema baseline.

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

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

The description opens with 'What other AI agents are calling on Pipeworx right now' and explicitly lists the outputs ('top tools, top packs, and total call volume'), making the resource and scope clear. It distinguishes from sibling tools by framing this as an aggregated usage signal rather than a search or discovery tool.

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

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

The description gives three numbered use cases ('discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice', 'seeing whether your use case aligns with what most agents need'). These provide clear situational guidance, though it doesn't explicitly name alternatives or when not to use the 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, openWorldHint, idempotentHint, and destructiveHint=false. The description richly supplements this with concrete behavioral details: partition placeholder filtering, semantic similarity threshold (≥0.30 Jaccard), fill-check pricing against live CLOB depth, and explicit advice ('realizable_edge_pp ≤ 0... do not trade it'). 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 longer than average but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence carries substantive information. It is front-loaded with the core purpose and mode overview, though some detail could be trimmed without losing value.

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

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

Despite having no output schema, the description explicitly lists response fields (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check fields) and covers edge cases like skipped_low_similarity, placeholder fraction limits, and fill-check realizable edge caveats. This is fully complete for a tool with this complexity.

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

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

Schema coverage is 100% and both parameters have helpful base descriptions. The description adds meaning beyond the schema: 'event' is recommended for specific markets and accepts slugs or full URLs, while 'topic' is for cross-event scans with seed-question examples. It also explains how each parameter changes the mode and checks performed.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly explains the two detection mechanisms and distinguishes the tool's scope from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique modes and outputs.

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

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

The description gives explicit usage scenarios: 'Call with NO args for a trending_scan... pass event... or topic.' It also explains when to use alternatives, e.g., 'For custom sizing use polymarket_fill_risk.' This is strong when-to-use guidance with named 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?

Discloses extensive behavioral details beyond annotations: caching at KV level for 1 hour, five model families with specific methodologies (e.g., 'lognormal barrier from 90d FRED log-returns'), gate thresholds, placeholder-slug filters, and diagnostics for why segments may be empty. This exceeds what annotations alone convey.

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

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

The description is very long and dense, but every sentence carries substantive information. It is front-loaded with purpose and then systematically covers model families, response fields, and knobs. However, the wall-of-text format with nested parentheses and semicolons could be better organized with bullets or headings for easier consumption.

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 absence of an output schema, the description thoroughly explains the response structure (top-level by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction), and rationale for exclusions. It even includes tuning thresholds and edge cases, making it self-sufficient for an agent.

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

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

Although the schema already documents all 9 parameters with 100% coverage, the description adds crucial semantics: it explains tradeable-edge knobs like min_liquidity/max_spread_pp, clarifies that partition_overround returns kelly_fraction_half=0, and details how min_partition_leg_kelly filters per-leg Kelly. This goes well beyond the schema.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the tool's purpose and includes concrete output details like response segments and candidate fields, distinguishing it from general market 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?

Explicitly positions the tool for 'what should I bet on today' and notes agents can 'discover opportunities without paging hundreds of markets.' It also excludes Fed bets from ranking with a rationale, but it does not explicitly name alternative sibling tools or state when not to use this tool versus them.

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 explains snapshot gaps, TTL limits, decay calculation from daily closes, signed edge values, and the meaning of expired opportunities. This gives substantial behavioral transparency that annotations alone would not 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 long and dense, but every sentence carries meaningful information. It is structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. Slight verbosity prevents a 5, but there is no filler.

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

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

There is no output schema, yet the description fully specifies the response shape (tracked[], expired[], snapshot_dates[]), their fields, and important limitations such as TTL and gap behavior. This is complete for a telemetry-focused tool.

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

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

The input schema already documents both parameters with descriptions and defaults (100% coverage). The description repeats the defaults and adds the 'max 30' clamp for 'days', but does not significantly extend the semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states this is edge persistence and decay telemetry built from daily polymarket_edges snapshots, with a specific question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges tool by focusing on time-series behavior rather than a current edge snapshot.

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

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

The description implies when to use the tool: when you need to understand edge persistence/decay over time, contrasting fresh vs. old wide edges. It does not explicitly name alternatives or exclusion criteria, but the emphasis on snapshot history and decay makes the use case 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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: it explains the tool walks the order book, returns a verdict (clean|degraded|cannot_fill), and highlights the risk of partial fills converting arbs into unhedged directional positions. This is significant beyond what annotations provide, with no contradiction.

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

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

The description is long but every section earns its place. It opens with a precise one-sentence purpose, then uses uppercase labels (SINGLE-MARKET, BASKET) to structure the details, and ends with actionable usage guidance. Given the tool's complexity, the length is appropriate and information-dense, not padded.

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

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

There is no output schema, so the description carries the burden of explaining return values—and it does thoroughly, listing all output fields for both modes. It also covers prerequisites, defaults, and risk warnings, making the tool fully understandable for an agent without needing additional 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%, so the baseline is 3, but the description adds deep meaning: it explains how `market` vs `event` selects modes, how `side` defaults differ in single-market vs basket, and how `size_usd` is interpreted (max spend on buys, target proceeds on sells, settlement notional in basket). This far exceeds the schema's brief 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 states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and execution feasibility, and enumerates the two modes (single-market and basket) and their outputs.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It implies when-not (below $500 or non-arb trades) but does not name an alternative tool for those cases, so it lacks a fully explicit alternatives statement.

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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context beyond them. It discloses the existence of compatibility warnings, explains the semantics of matched_pairs vs skipped_cross_type, describes temporal_alignment and its meaning, and provides a candid limitation warning about how rare real cross-venue spreads are. This goes far beyond annotation-specified behavior.

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

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

The description is long but every sentence earns its place. It is structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. There is no redundancy or filler; the density is justified by the tool's complexity.

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

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

Given the tool has no output schema, the description compensates by explaining the response structure: leg-by-leg prices, matched spread, top_spreads_pp, and safety fields. It also covers failure modes (compatibility, temporal misalignment) and the meaning of skipped counters. This is a comprehensive description 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 description coverage is 100%, providing a baseline of 3. The description elevates this by explaining the relationship between the parameters: it introduces the two modes (topic vs explicit) and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. This adds meaningful context not present in the schema's individual parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison. It also clearly states two operating modes, leaving no ambiguity about what the tool does.

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

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

The description explains when to use the tool (for cross-venue spreads) and when results are not meaningful (compatibility_warning conditions, temporal misalignment). It explicitly warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return a warning. However, it does not name specific alternative tools to use instead, so it stops short of fully explicit exclusion guidance.

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

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

The annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is clear. The description adds valuable behavioral context beyond annotations: the scoping 'to your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of omitting the key to list all keys. This enriches understanding 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 three sentences long, front-loaded with the primary function in the first sentence, followed by a usage example and scoping detail. Every sentence adds distinct value with no redundancy or fluff.

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

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

For a simple single-parameter tool with comprehensive annotations and no output schema, the description fully covers the behavior (retrieve or list), scoping, and relationship to sibling tools. The 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?

Schema description coverage is 100%, and the schema property description already states 'Memory key to retrieve (omit to list all keys).' The tool description repeats the omit-key behavior but does not add further parameter semantics. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It names the specific resource (saved memory) and the verb (retrieve/list), and distinguishes itself from sibling tools like 'remember' and 'forget' by explicitly mentioning them in context.

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

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

The description provides clear context for when to use the tool: 'Use to look up context the agent stored earlier' and explains the benefit 'without re-deriving it from scratch.' It also mentions pairing with 'remember' and 'forget,' but does not explicitly state when not to use it or list alternative tools (e.g., search), so it misses the threshold for a 5.

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

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

The description contradicts annotations: readOnlyHint is true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which implies a state-changing write to the persisted feed. This is a clear annotation contradiction, thus the score is 1.

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

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

Four sentences with front-loaded main action. Each sentence provides distinct useful information: return payload contents, filtering options, mark_read behavior, and alternative endpoint. 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?

Covers purpose, return payload, filtering, mark_read semantics, and polling/script access. The limit and unread_only parameters are only in the schema, but the description is otherwise complete for a list tool. The contradiction slightly detracts from overall completeness, but the main functional behavior is well explained.

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 5 parameters with descriptions (100% coverage), but the description adds beyond schema by giving a concrete type example ('sec_8k'), clarifying since as an ISO timestamp, and explaining the downstream effect of mark_read. This exceeds the baseline 3.

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

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

Clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes itself from sibling tools like recent_changes and list_subscriptions by focusing on alert events from the persisted subscription feed.

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

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

Provides clear context for polling ('Polls work fine'), filtering by type and since, and the effect of mark_read. It also mentions an alternative access method via GET registry.pipeworx.io/alerts.json, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Discloses fan-out to SEC EDGAR, GDELT→GNews fallback (with rate-limit/5xx conditions), and USPTO soft-fail due to PatentsView sunset. This goes beyond the readOnly/idempotent annotations, providing valuable runtime behavior 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?

Front-loaded with natural-language queries and dense with functional detail. The multiple query phrasings are slightly redundant, but every sentence contributes to understanding the tool's scope.

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

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

Given no output schema, it specifies returned fields (changes[], total_changes, pipeworx:// citations), source behavior, fallback logic, and parameter options. This is comprehensive for a 3-parameter 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 by clarifying `since` accepts ISO or relative shorthand and `value` accepts ticker or CIK. It also gives a typical monitoring recommendation.

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

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

The description precisely identifies a change feed for a company over a time window, with concrete examples of user intents. It explicitly distinguishes itself from entity_profile, which is the static-profile alternative.

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 names entity_profile as an explicit alternative for static profiles and recommends '30d' or '1m' for typical monitoring. It lacks a broader when-not-to-use comparison against recent_alerts or search, but the intended use case is well-scoped.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds valuable context: persistence varies by auth status ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and key-value storage scoping. It doesn't contradict annotations and discloses behavioral traits 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?

Four sentences, front-loaded with the core action, then usage guidance, then persistence details. Every sentence earns its place; no redundant filler.

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

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

For a two-parameter, no-output-schema tool, the description covers what it saves, when to use it, storage model, durability, and sibling relationships. It's complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with examples for key ('subject_property') and value ('any text'). The description adds no additional parameter semantics beyond the schema, 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 opens with 'Save data the agent will need to reuse later', a specific verb+resource statement. It explicitly contrasts with siblings 'recall' and 'forget' by mentioning pairing, and clarifies scope ('scoped by your identifier'), distinguishing it from other tools.

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

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

It provides explicit guidance: 'Use when you discover something worth carrying forward...' and gives concrete examples. It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This satisfies the when/alternatives criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: it specifies return details (10-digit CIK, RxCUI, citation URIs), notes auto-disambiguation, and reveals internal cascading behavior. It does not discuss error cases or rate limits, but for a read-only lookup with strong annotations, this is adequate.

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 thorough but well-organized: it starts with user-phrased examples, states the purpose, then breaks down supported types with return details. Every sentence adds information (input variations, citation URIs, internal efficiency), and there is no filler or repetition.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description fully covers what it does and what the agent can expect: exact return fields for each type, citation URIs, input format flexibility, and the internal cascade. No critical information is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and both parameters are clearly described in the schema. The description adds further value by giving concrete examples (AAPL, 0000320193, 'ozempic', 'metformin') and explaining that company input is 'auto-disambiguated,' which enriches the schema's basic type definitions.

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

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

The description opens with concrete examples ('What's the ticker for…' / 'find the CIK for…') and states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It clearly identifies the resource (company → ticker/CIK, drug → RxCUI) and distinguishes itself from siblings by being the prerequisite ID lookup step.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is a strong usage condition. It also explains what each type accepts and returns, and states that it 'replaces 2-3 manual lookups,' giving context for when it is beneficial. However, it does not explicitly name alternative tools or give when-not-to-use scenarios, so it misses the full 'when-not/alternatives' bar.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a specific output structure (score, confidence, signal density). It also reveals that the first entity is treated as the 'subject' for narrative. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences long, front-loaded with the main purpose, followed by method, use case, and output. Every sentence provides distinct value with no redundancy or fluff. Structure is excellent for quick comprehension.

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 moderate complexity (4 params, no output schema), the description covers the 'what', 'why', 'how', and return format effectively. It explains the ranking output and the entity subject semantics. The schema handles constraints like entity count, and annotations handle safety, making this description complete enough for an agent 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?

Schema description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by specifying that the first entity is the 'subject' and the rest are competitors, and it notes the default model ('workers-ai') and the _apiKey requirement for 'anthropic', though these are also in the schema. The entity-ordering semantic adds value beyond the structured definition.

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

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

The description clearly states the tool's function with a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It explicitly differentiates from the sibling ai_visibility_check by emphasizing side-by-side comparison of multiple entities and competitors, making the purpose unambiguous.

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

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

It provides clear context on when to use the tool ('Useful for competitive AI-marketing audits') with a concrete example query. However, it doesn't explicitly mention alternatives or when not to use it, though the naming and reference to ai_visibility_check imply a contrast. This is good but not fully 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?

Description goes well beyond annotations by disclosing partial failure degradation, bundlephobia's 5-30s first-measurement latency, and the sources_failed field. This gives agents realistic expectations of behavior without contradicting the readOnly/idempotent annotations.

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

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

Though long, the description is densely informative and well-structured: purpose, usage, return summary, ecosystem caveat, failure behavior. Every clause contributes meaning; no filler or redundancy.

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

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

Given a complex composite tool with no output schema, the description fully enumerates return values (summary block fields, per-advisory detail, links, alternatives), constraints (NPM-only), and edge cases (timeout behavior). It is self-sufficient for an agent to predict 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% and both parameters (package, version) are fully described there. The description reinforces defaults ('latest') and scoped package acceptance, but adds no new semantic detail beyond schema, matching the baseline for high 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?

Purpose is exceptionally clear: 'Composite "should I add this npm package to my project" check in ONE call' immediately identifies the tool's function. It specifies the verb (scan), resource (dependency), and distinct data sources (deps.dev, bundlephobia), distinguishing it from all sibling 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes NPM-only scope and directs users to deps.dev:version for other ecosystems, effectively naming an alternative.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds the language code format instruction, which is a useful parameter-level disclosure, but no further behavioral traits (e.g., result ordering, pagination defaults) are mentioned.

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

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

The description is two short sentences and wastes no words. It immediately names the action and provides the essential parameter convention.

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 presence of an output schema and extensive annotations, the description covers basic parameters but leaves unclear the exact semantics of the search (e.g., does it return translations?) and when to use it. This is acceptable for a simple tool but could be more complete.

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

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

The schema covers 80% of properties, but the description adds crucial format information for 'from' and 'to' by specifying ISO 639-3 codes. It does not explain 'query', which lacks a schema description, so there is a small gap.

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 'Search sentences' which gives a verb and resource, but does not clarify the domain, the nature of the search, or how it differs from siblings like 'search_within' or 'sentence'. The ISO 639-3 hint hints at translation, but the overall purpose remains ambiguous.

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 only usage guidance is 'Use ISO 639-3 codes for from/to', which is a parameter formatting instruction. No context is given for when to choose this tool over alternatives like 'search_within' or 'translations'.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description adds valuable behavioral context: the embedding model ('BGE-base-en embeddings'), windowing ('500-char overlapping windows'), and input limits ('cap is 200K chars (longer inputs are truncated and flagged)'). This helps the agent understand exact operation and edge cases. 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 somewhat longer than typical but each sentence adds important information: purpose, usage, output, and technical specifics. It is front-loaded with the core purpose. The sentence 'search_within saves context' is slightly redundant with the preceding phrase, but overall the structure is effective and not bloated.

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

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

No output schema exists, so the description appropriately explains the return format: 'top-N passages with character offsets and similarity scores.' It also covers input constraints (200K cap, truncation flag) and associates with a sibling tool for broader workflow. For a read-only search tool with a clear use case, this is 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% and each parameter already has a clear description in the schema (e.g., text mentions max ~200K chars, query gives examples). The tool description reinforces these meanings (e.g., 'natural-language query', 'top-N passages') but does not significantly add new information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a provided text ('Semantic search INSIDE a fetched record'), with a specific verb and resource. It distinguishes from siblings like 'search' (external search) and 'ask_pipeworx' (Q&A) by emphasizing the input is already-fetched text. The mention of returning passages with offsets further specifies the function.

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 provides when to use: 'Use when the record is too big to cram into the prompt' and why (saves context, returns only relevant passages). It also names a complementary tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear usage guidance and an alternative.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the return metadata (text, language, author, audio/translation links), which is useful but does not disclose behavior for missing IDs or other edge cases. It does not contradict annotations, but adds limited extra behavioral context beyond what annotations offer.

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 sentence with two clear clauses, front-loading the action and resource. Every word earns its place, with no fluff or repetition of schema details.

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

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

For a simple single-ID fetch tool with good annotations and an output schema, the description covers the essential purpose and return values. It does not mention error handling, but the output schema likely covers that. The description is complete enough for the tool's simplicity, though it could note behavior for non-existent IDs.

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 0%, so the description must compensate. It states 'by numeric ID', which reinforces the schema's type and required flag but adds minimal semantic meaning. It does not explain where the ID comes from or any constraints, so it only partially compensates for the lack of parameter 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 'Fetch', the resource 'single Tatoeba sentence record', and the method 'by numeric ID'. It also lists the return contents, making the tool's purpose unambiguous and distinguishable from siblings like 'translations' or '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 should be used when a numeric sentence ID is known, but it does not explicitly mention when to use it over alternatives or provide exclusions. Context signals show many sibling tools, yet no guidance is given on when to choose this one, so usage is only implied.

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

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

The description goes well beyond the annotations, revealing that subscriptions require an OAuth account, that sms has a 10/day cap and must be verified, that webhook signing secrets are returned once, and that webhooks auto-disable after 10 consecutive failing runs. These operational details are not available from annotations or schema.

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

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

The description is dense but well-structured: it opens with the primary purpose, then prerequisites, then supported types with examples, then delivery options. Every sentence carries useful information with no filler or repetition.

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

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

For a creation tool with three parameters and nested objects, the description covers prerequisites, return value, all supported types, delivery mechanics, limits, and failure behavior. It is complete enough for an agent to invoke correctly without ambiguity.

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

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

While the schema already has thorough descriptions, the tool description adds concrete examples for each subscription type (sec_8k, polymarket_edge, fred_series) and elaborates delivery semantics with webhook HMAC signing and SMS verification. This adds meaning beyond the raw schema fields.

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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It uses specific verbs and resources, and is immediately distinguishable from siblings 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 strong usage context: it warns that anonymous and BYO accounts cannot persist subscriptions, so OAuth is required. It also names the feed delivery alternative (recent_alerts) and explains optional delivery channels, making it clear when to use this tool versus other methods.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds context by describing the output (category-bucketed questions with tool+argument shapes drawn from a live catalog) and how call patterns affect results (no args vs topic). This goes beyond the annotations without contradicting them.

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

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

The description is rich but efficiently structured: it opens with example user phrases, states the tool's purpose, describes the output, gives usage instructions, and ends with a clear 'use this FIRST' directive. Every sentence contributes meaningful information without redundancy.

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

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

Despite having no output schema, the description fully explains what the tool returns (category-bucketed questions with tool+argument shapes) and how to invoke it. It also mentions meta-tools it can teach about, which is important context for onboarding. Given the tool's simplicity (one optional param), the description is 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% and already documents the single 'topic' parameter with examples. The description adds value by explaining the semantic difference between omitting the parameter (full spread) and focusing it, and provides additional examples like 'betting'. This enhances but does not replace 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 that the tool returns category-bucketed example questions with the exact tool and argument shape for each, acting as an onboarding entry point. It uses a specific verb ('returns') and resource ('example questions') and distinguishes itself by emphasizing it's the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly tells when to use it ('Use this FIRST when you do not yet know what Pipeworx can do'), and explains how to adjust behavior via the optional 'topic' parameter. It does not explicitly state when not to use it or contrast with sibling tools like discover_tools, but the clear 'first-use' guidance provides strong context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false, but the description adds no behavioral details beyond those. It does not disclose output format, pagination, or any additional traits, and it does not contradict the annotations either—it simply provides nothing.

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

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

The description is very short but under-specified rather than usefully concise. It uses only a noun phrase and could easily include a verb and parameter explanation in the same space. It lacks the completeness needed for a helpful 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?

Despite having a single parameter, an output schema, and many sibling tools, the description is inadequate. It does not explain the output, the meaning of the id, or the scope of 'translations', leaving the agent without enough information to invoke the tool correctly.

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

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

The schema has a single 'id' parameter with no description. The phrase 'of a sentence' hints that the id likely identifies a sentence, but it does not explicitly define the parameter or expected values. This is minimal added meaning, insufficient to compensate for the 0% 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 'Translations of a sentence.' identifies the resource (sentence) but lacks an explicit verb (e.g., 'get' or 'retrieve'), making the action implicit. It provides a vague purpose rather than a clear directive, but it is not a pure tautology since it adds the 'of a sentence' context.

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

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

The description gives no guidance on when to use this tool or how it relates to alternatives like 'sentence' or 'languages'. There is no mention of use cases, exclusions, or preferred alternatives, leaving the agent without any decision-making support.

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 non-destructive and idempotent behavior. The description adds valuable behavioral details: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This is consistent with the annotations and goes 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?

Three short sentences, each adding essential information with no redundancy. The purpose is front-loaded in the first clause, and the rest of the description provides focused behavioral context.

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

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

For a simple 1-parameter tool, the description covers the core action, ownership constraint, and persistence behavior (deactivation with historical availability). This is sufficient for an agent to understand when and how to use it, especially alongside sibling tools.

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

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

The input schema fully documents the single parameter (id as subscription id returned by subscribe). The description reinforces this but adds no additional semantic detail beyond the schema, so the score matches 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 clearly states the action ('Cancel a subscription by id') and specifies the resource (subscription). It differentiates from siblings like subscribe and list_subscriptions by emphasizing cancellation and noting that events remain available via recent_alerts.

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

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

It provides clear context that this tool cancels subscriptions and enforces ownership (only your own). It indirectly points to recent_alerts for historical events after cancellation, but it does not explicitly name alternatives like list_subscriptions 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond this by disclosing the internal routing logic (SEC EDGAR + XBRL vs. grounded pipeline), the exact percent-delta math, and the behavior of returning verbatim evidence with a pipeworx:// citation. It also explains that it replaces 4–6 sequential calls, adding valuable context without contradicting annotations.

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

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

The description is moderately sized but densely informative. It includes trigger phrases, two pathway descriptions, return values, and efficiency benefits—all in a readable block. A slightly tighter structure (e.g., bullet points for verdicts) could improve scannability, but 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?

With no output schema, the description adequately covers return values (verdicts, actual value with citation, reasoning). It also explains the two processing paths and claim scope. It does not explicitly address failure cases (e.g., unavailable sources) or edge cases like unsupported claims, but for a verification tool it provides sufficient context for an agent to select and call it appropriately.

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 only two well-described parameters. The description adds context about the claim-verification intent and the tolerance behavior ('exact percent-delta math', 'capped at 5'), but this is more behavioral context than parameter semantics. The schema already handles parameter meaning thoroughly, so the description offers marginal additive value, hitting the baseline of 3.

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

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

The description clearly identifies a specific verb+resource: 'natural-language claim verification against authoritative sources', with concrete trigger phrases. It distinguishes this tool from siblings by focusing on fact-checking claims, and explicitly states what it returns (verdict, value, reasoning), 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 provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), which helps decide when to invoke. However, it does not explicitly mention when NOT to use or name alternative sibling tools, so it falls just short of a 5.

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