7timer

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the default model (Workers AI) is free, probing Anthropic requires a BYO key and incurs direct costs, and the return shape includes per-model score/confidence/signals/raw_response. This supplements the annotations well, though it could mention potential side effects like network latency or response variability.

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 purpose, followed by key operational details and use cases. Every sentence adds value—no fluff, no repetition. Ideal conciseness.

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 (4 params, no output schema), the description is largely complete. It explains inputs (entity, models, key, context), output structure, and practical use cases. Minor omissions like rate limits or response size are not critical for this read-only probe. The lack of an output schema is compensated by the explicit return format description.

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

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

The input schema already documents all parameters with descriptions, achieving 100% schema description coverage. The description reinforces the `_apiKey` behavior (pay Anthropic directly) and clarifies the default model in `models`, but it doesn't add substantial meaning beyond what the schema already provides. Baseline of 3 applies.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility 0-100. It has a specific verb ('probe') and resource ('one or more LLMs'). It doesn't explicitly distinguish from the sibling tool 'scan_competitor_ai_presence', but the described use cases (AI-marketing audits, pre-launch checks) differentiate it enough.

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

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

The description provides clear use-case context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default free model and optional paid Anthropic probing, giving practical guidance on when to include `_apiKey`. However, it doesn't explicitly contrast with alternatives or state when not to use this tool, so it's not a 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?

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond those: it discloses routing behavior across 5,529 tools, argument-filling, citation URI format, 'works on every tier, one fast call', and that it handles live news/breaking news. It does not describe failure modes or rate limits, but the annotation set already covers the safety profile well. 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 longer than two sentences but every sentence earns its place. It is front-loaded with 'PREFER OVER WEB SEARCH' to immediately convey the primary use. It includes a compact list of domains, examples, and explicit step-up alternatives. While slightly verbose, the structure (intro, when-to-use, examples, escalation path) is well organized and not redundant.

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

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

The tool is high-complexity with no output schema, but the description covers the key return value ('structured answer with stable pipeworx:// citation URIs'), domain coverage, default-entry status, and when to use alternatives. It lacks details about error handling or what happens if no source is found, but for a general-purpose router this is quite complete. The inclusion of examples further anchors the expected behavior.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, establishing a baseline of 3. The description goes further by explaining what constitutes a valid question: factual questions about real-world entities, with examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It clarifies that the parameter accepts natural language and mentions aliases. This adds real semantic guidance beyond the bare schema.

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

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

The description clearly states the tool's role: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It names concrete domains ('SEC filings, FDA drug data, FRED/BLS economic statistics, government records, USPTO patents...') and explicitly differentiates from siblings by telling when to use ask_pipeworx_grounded or deep_research instead.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current", or any factual question...' It provides examples and states 'START HERE for most questions'. It also gives clear exclusions and alternatives: 'Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research.'

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses its experimental nature, the current state (no active candidate), and that it 'IS a full working router'. This adds meaningful behavioral context about the tool's reliability and its role in testing routing improvements.

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

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

The description is front-loaded with the core purpose and each sentence contributes valuable information: beta status, identical router, current state, usage guidance, and confirmation it is a full working router. It is appropriately sized for the 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 lack of an output schema, the description compensates by stating 'same response shape' as ask_pipeworx. It also covers current state, usage, and experimental nature, providing sufficient context for an agent 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 input schema covers 100% of parameters with clear descriptions, including aliases for the 'question' parameter. The description adds no extra parameter meaning beyond referencing 'same arguments' as ask_pipeworx, so it does not exceed 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 it is the beta version of ask_pipeworx, a universal router with identical behavior and arguments, distinguishing it from the stable sibling. It explicitly says 'Beta version of ask_pipeworx' and describes its role, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also explains that results are compared against the stable router to decide merges, giving clear context for when this beta tool is appropriate versus the stable 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds significant context: refusal behavior with enumerated refusal_reason values, the output shape on success and failure, the constraint that answers use only tool result content, and the extra LLM call cost. No contradiction exists.

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

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

The description is dense but every sentence earns its place: core value proposition, routing behavior, output contract, refusal contract, use case, and cost comparison. It is front-loaded with the key differentiator and well-structured.

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

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

The description fully compensates for the absence of an output schema by specifying both the success response fields and the failure response structure with refusal reasons. It also contextualizes the tradeoff against the base mode, making it complete for an agent to decide and invoke.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the natural-language question. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb phrase 'extracts the answer using ONLY what the tool result contains' and clearly identifies the resource as a grounded variant of ask_pipeworx. It distinguishes itself from the sibling ask_pipeworx by explicitly naming it and contrasting the grounded extraction behavior.

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

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

It explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This provides clear when-to-use and when-not-to-use guidance, naming the alternative tool and the cost tradeoff.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes far beyond that. It discloses critical behavioral nuances: low-confidence matches short-circuit with status:"low_confidence_match", closed markets return status:"market_closed_or_inactive", wide-spread markets get tradeability:"illiquid_wide_spread", and it details cancellation-rule risk (e.g., refund_50_50) that could cause EV loss. It even explains news fallback mechanics with GDELT 429s. This is exceptional transparency.

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

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

The description is long and dense, but it is well-structured with capitalized section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value—there is no filler. It could be slightly more concise by trimming the exhaustive classifier list, but the organization makes the length acceptable.

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

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

For a complex tool with no output schema, this description is exceptionally complete. It covers input formats, fan-out behavior, response shapes (result.market, result.analysis, result.evidence), resolver contract (match_confidence, alternatives, suggestions), parent-event extraction, news fallback fields, safety short-circuits, and cancellation-rule risk. An agent would have everything it needs to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats what the schema already says about the market parameter (slug, URL, or question text) but adds no new parameter-level semantics. It does not elaborate on depth or include_raw beyond what is in the schema. Therefore it meets but does not exceed the baseline.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this tool from siblings by focusing on comprehensive bet research (resolving, classifying, fanning out to data packs, returning evidence + comparison) versus specialized tools like polymarket_edges or polymarket_arbitrage. The explicit 'Use for "should I bet on X"...' further nails the intended use case.

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

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

It explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples for different bet categories. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it earns a 4 rather than a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is dense yet well-structured, starting with easily recognizable query patterns, then explaining capabilities and data sources. Every sentence provides actionable information without redundancy, making it highly efficient.

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

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

For a 2-parameter tool with comprehensive schema and annotations, the description fully covers expected behaviors, data sources, return format, and scope. It even mentions the parallel-call benefit, making the tool's operational context complete without needing an output schema.

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

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

The schema already documents both parameters, but the description adds rich semantic detail: for type='company' it lists exact financial fields pulled, and for type='drug' it specifies FAERS/FDA/trial counts. It also confirms array size limits and provides examples, enhancing the agent's understanding of value selection.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with concrete verbs and scope. It explicitly mentions replacing 8–15 sequential lookups, differentiating it from alternative approaches and sibling tools like entity_profile.

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

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

It gives direct usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides multiple canonical query examples. It also explains type-specific behavior (company vs drug) and result sorting, clarifying when and how to invoke.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details account tier restrictions, depth-level behaviors (gap recovery, contradiction scans), return format (findings packet with evidence, confidence, source, fetched_at, citation_uri), performance expectations (15-60s, up to 90s), and handling of large records via semantic excerpts. 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?

Though lengthy, every sentence carries distinct value: account requirements, exclusions, examples, behavior, limitations, performance, and return format. The description is front-loaded with critical account requirement and immediate sibling differentiation, and structured into logical groups. No filler or redundant restatements.

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

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

For a tool with no output schema and moderate complexity, the description is exceptionally complete. It covers purpose, usage, alternatives, depth semantics, return values (gaps[], contradictions[], hop, citation_uri), edge cases (news topics yielding empty gaps), and performance. An agent can confidently select and invoke this tool across scenarios.

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

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

Schema coverage is 100%, but the description adds rich semantics: it explains the depth enum ('quick=3, standard=5, thorough=8') with behavioral consequences (single hop vs. gap recovery vs. iterative leads), and clarifies that question accepts broad/multi-part natural language. This goes well beyond the schema's 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 tool's function: grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources in one call, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and breaking news.

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 usage guidance: best for broad/multi-part questions over structured data, with concrete examples. It gives when-not-to-use conditions: for a single lookup use ask_pipeworx, and for breaking/colloquial current-news prefer ask_pipeworx. Also notes account requirements and fallback to ask_pipeworx for unsigned users.

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 signal read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it returns top-N relevant tools, includes full input schemas with curated examples, and states that results are ready to call directly without a second schema lookup. 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 efficient and front-loaded. The first sentence states the core purpose, followed by when to use it, return behavior, and a strong directive to call first. The domain list is informative without being verbose. Every sentence serves a distinct 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 adequately explains return values: top-N tools with names, descriptions, and full input schemas. It also covers usage context, scope, and the 'call first' directive. The tool's behavior is fully comprehensible from the description, schema, and annotations.

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

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

Schema description coverage is 100%, with all parameters (including aliases) fully documented in the schema. The description repeats that query is a natural-language description but does not add new meaning or clarify syntax beyond the schema. Baseline 3 is appropriate given the schema covers everything.

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 tools by describing the data or task.' It clearly differentiates from siblings by positioning this as a discovery/browsing tool (returns top-N tools with schemas), not a domain-specific tool. The list of covered domains further clarifies scope.

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

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

Explicit when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This contrasts with other tools that answer specific queries, making the decision context clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses specifics: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; details each return field; mentions the USPTO API sunset with soft-fail; and GDELT→GNews fallback. This gives the agent a clear model of what happens behind the scenes.

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

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

The description is dense but not overly verbose. It front-loads example queries and then summarizes the fan-out and return fields. Every sentence conveys necessary information, though it could be broken into more digestible parts. It earns a 4 rather than a 5 due to the wall-of-text style.

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

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

With no output schema, the description fully carries the burden of explaining return values. It enumerates the exact fields: cik, company_name, recent_filings, fundamentals, patents, news, and LEI, along with quirks like the patent API sunset and fallback behavior. This is complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% for the two parameters, so baseline is 3. The description adds value by providing concrete examples like ticker 'AAPL' and zero-padded CIK '0000320193', and reiterating that names are not supported. This extra context helps agents craft valid inputs.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' with the specific verb 'profile' and resource 'US public company'. It distinguishes from siblings by explicitly saying to prefer it over chaining single-pack SEC/XBRL/news lookups and noting that resolve_entity is needed for names.

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 usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and states names are not supported, directing users to resolve_entity first. This clearly delineates when to use this tool versus alternatives.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true, which the description supports. The description adds use-case context (clearing sensitive data) but does not reveal additional behavioral traits like irreversibility or effect on related memories. With annotations covering the key safety profile, this is adequate but not enriched.

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

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

Two concise sentences. The first states the core function; the second gives usage guidance. No redundant or filler content.

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

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

The tool is simple (one parameter), annotations are rich, and the description fully explains what it does, when to use it, and how it relates to siblings. No output schema is needed for a deletion action, and the description 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?

The schema has 100% coverage for the single 'key' parameter with description 'Memory key to delete'. The tool description does not add extra meaning 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 clearly states the action ('Delete'), the resource ('a previously stored memory'), and the means ('by key'). It also differentiates from sibling tools like 'remember' and 'recall' by explicitly naming the operation as deletion.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with related tools ('Pair with remember and recall'), giving 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavior details such as 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and clarifies output as 'a single text blob.' This goes beyond the annotations by explaining the underlying process and output packaging.

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

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

The description is compact and front-loaded, stating the main action first and then providing useful context. It covers the mechanism, output, and use cases in under 70 words without redundancy, making every sentence earn its place.

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

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

Given the tool's simplicity (2 params, no output schema, strong annotations), the description is complete: it explains the input (any URL), the process, the output format, and practical applications. The explicit statement that output is a 'single text blob' compensates for the lack of an output schema.

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

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

Schema coverage is 100% for both parameters ('url' and 'max_links'), so the structured data fully documents them. The description adds no extra parameter-level details beyond what the schema provides, thus meeting the baseline for high coverage without enhancing parameter semantics.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL' and explains the process (fetches, extracts, emits). This specific verb+resource combination distinguishes it from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check' which focus on broader AI visibility rather than producing a specific file 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 description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives contextual guidance on when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying the scope ('the caller's'), the returned fields, and the default exclusion of inactive subscriptions, which is useful behavioral context.

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

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

The description is extremely concise: two sentences clearly stating the function, return fields, and usage context. No unnecessary words or repetition of schema/annotation 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?

For a simple list tool, the description is complete. It lists return fields, the schema documents the only optional parameter, and annotations cover safety. No output schema is needed given the clarity of the return fields.

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 full coverage for the single parameter 'include_inactive' with a clear description. The tool description adds no additional parameter detail, so it meets 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 the tool's function: 'List the caller's active subscriptions' with a specific verb and resource. It also lists the returned fields, distinguishing 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 when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly mention when not to use or name alternative tools, but the context is clear.

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

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

Beyond the annotations (readOnlyHint=false), the description discloses rate limits ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token read-back workflow, and service-level expectations (daily digests, roadmap impact). It also imposes a privacy-like constraint: don't paste the end-user's prompt.

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 carries distinct operational information: purpose, scope exclusion, token mechanics, rate limit, and cost. It is front-loaded with the purpose statement, but the single unstructured paragraph makes it slightly harder to scan than a bulleted version; no content 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?

For a submission tool with no output schema and a nested context object, the description explains the full lifecycle: what to file, how to reference the correct tools, what filing returns (claim_token), how to later check resolution status, and service-level expectations. The exact return shape of a successful filing is not specified, but the claim_token workflow fully covers the post-condition behavior.

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%, setting the baseline at 3, but the description adds real value: it maps the purpose sentence to the type enum values and explains the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which the schema only names. It also adds message-length and specificity guidance beyond the schema, though the schema already documents each parameter well.

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

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

The opening sentence uses a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete trigger categories (bug, feature/data_gap, praise) and explicitly scopes itself to Pipeworx-served tools, distinguishing this feedback channel from the 30+ research/query 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?

Provides explicit when-to-use guidance (bug, missing capability, praise) and an explicit when-not-to: tools from a different MCP server should be filed with that vendor, 'reporting it here only delays you.' It also tells users how to verify scope ('Pipeworx tool names are the ones this connection lists') and what content to include (tool/pack terms, not end-user prompts).

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

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

The description discloses the data source (CF analytics-engine), privacy (no PII), output composition (pack, tool, count), and caching behavior (5min-1h). These details go beyond the annotations' readOnly/idempotent hints and provide useful behavioral context without contradicting any annotation.

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

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

The description is dense and well-structured: a direct answer to what it does, a numbered list of use cases, and a compact note on data provenance and caching. No sentence is wasted, and the most important information appears first.

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 read-only tool with no output schema, the description covers return values (top tools, top packs, call volume), explains the aggregate nature, and gives practical use cases. It is complete enough for an agent to decide whether 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?

The schema already fully describes the single 'window' parameter with enum values and their trade-offs, so the description adds little additional semantics. The main description only repeats the window options, yielding the baseline score for high schema coverage.

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

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

The description uses a specific verb phrase 'What other AI agents are calling on Pipeworx right now' and explicitly states it returns top tools, top packs, and total call volume over a window. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregate usage trends.

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

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

The description lists three specific use cases ('discovering what data sources are hot', 'confirming a popular tool is the canonical choice', 'seeing whether your use case aligns'), which gives clear guidance on when to use it. However, it does not explicitly name alternatives or state when not to use it, 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 already declare readOnly/idempotent, so the description adds context that annotations do not: the semantic similarity threshold (≥0.30 Jaccard), placeholder filtering, fill-check against live CLOB depth, and the rule that realizable_edge_pp ≤ 0 means do not trade. No contradictions.

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

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

The description is long but tightly organized: a summary sentence, mode breakdowns, filters, response format, and fill-check note. Every sentence contributes operational value, and the bolded labels front-load key 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?

With no output schema, the description compensates by detailing return fields (opportunities[].gap_pp, partition_check.sum_yes_prices, fill_check.realizable_edge_pp) and edge cases (thin_legs, placeholders_filtered, similarity threshold). It also covers the no-arg behavior, making it 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?

Schema descriptions cover event and topic, but the tool description adds significant meaning: it explains the no-arg mode, gives concrete slug/topic examples, and describes the analysis that each parameter triggers (partition_check, fill_check, etc.).

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+object: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes the tool from siblings like polymarket_fill_risk by explaining the analysis methods and offering concrete mode options.

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 guides mode selection: '`event` (recommended for a specific market)' and '`topic` (for cross-event scanning)', plus 'Call with NO args for a `trending_scan`'. It also names an alternative for sizing: 'For custom sizing use polymarket_fill_risk'.

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 is rich with behavioral detail beyond the annotations: caching (Cached 1h at KV level), the 24h-move warning, Kelly capping, per-sport alpha values, placeholder-slug filters, and the explanation that partition arbs always return kelly_fraction_half=0. It also discloses limitations (news_momentum soft signal, Fed bets unreliable). This far exceeds what annotations provide.

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

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

The description is front-loaded with the main purpose, but it is extremely long and dense. While each sentence is informative, the overall length is excessive and could overwhelm an agent. It is structured with paragraph breaks, but a more concise version would be more effective.

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

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

With no output schema, the description takes on the burden of explaining the response structure, including by_segment, fed_candidates, and _diagnostics. It also covers all major behavioral aspects, filters, and caveats. For a complex tool, the description is remarkably complete.

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

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

Despite 100% schema coverage, the description adds substantial meaning to parameters. It explains the TRADEABLE-EDGE KNOBS (min_liquidity, max_spread_pp) and their purpose, clarifies that min_kelly never filters partition arbs due to the parent-level kelly_fraction_half=0 design, and provides default-slippage rationale. This goes well beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose for edge discovery and differentiates itself from siblings by focusing on 'what should I bet on today' without paging hundreds of markets.

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

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

The description provides clear usage context: 'Built for "what should I bet on today"' and notes that Fed bets are excluded due to unreliability. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description richly discloses behavior: it explains the response structure (tracked, expired, snapshot_dates), the 60-day TTL limitation, that snapshots are written on cache-misses and gaps indicate no scan, and that decay is computed from daily closes of edge_pp_net net of slippage. This adds significant context and aligns 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 well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with a clear purpose. It is dense and information-rich without fluff, though slightly long for a tool description. Every sentence contributes unique value, so it earns a high score.

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

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

Given the complexity of the tool and the absence of an output schema, the description thoroughly explains the return format (tracked[] with fields, expired[], snapshot_dates[]), data source, TTL limitations, and how to interpret decay/trend numbers. It is complete enough for an agent to select and use the tool correctly without further clarification.

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

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

The schema already covers 100% of parameter descriptions, including defaults and allowed values. The description restates the defaults but does not add new semantic meaning beyond what the schema provides. Thus it meets the baseline but does not exceed it.

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

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

The description uses a specific verb+resource+scope: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_arbitrage by focusing on edge longevity and decay, and it answers a concrete trading question ('how long has this edge existed and is it shrinking?').

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 implicitly defines when to use this tool by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It explains the tool's unique value for evaluating edge persistence, but it does not explicitly name alternatives or provide explicit when-not-to-use guidance. Still, the context strongly implies its use case.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds mode-specific behavior, return fields, and risk disclosure (partial basket fills convert an arb into an unhedged directional position). 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?

It is long but front-loaded with the core purpose, and every sentence carries operational detail—mode requirements, defaults, output fields, and usage trigger. The length is justified by the tool's two-mode complexity; 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?

With no output schema, it enumerates all key return fields for both single-market and basket modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.). It also covers input requirements and failure/risk behavior, making it sufficient for an agent to invoke correctly.

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

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

Even though the schema covers all four params, the description goes beyond by explaining single-market vs basket semantics for size_usd (max spend vs target proceeds vs settlement notional), default side auto-detection, and return fields per mode. This substantially enriches parameter understanding.

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

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

The first sentence defines it as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource. It clearly distinguishes from siblings by covering fill-risk for Polymarket orders and explicitly contrasts with polymarket_arbitrage/polymarket_edges in the closing guidance.

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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' giving explicit when-to-use and alternatives. It also explains why via 'theoretical overround on thin books is not capturable' and the partial-fill danger.

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 and idempotent, and the description enriches this by detailing specific behavioral caveats: compatibility_warning conditions (two distinct cases), temporal_alignment, and skipped_cross_type/subtype counters. It discloses that most pre-mapped topics will return warnings, managing expectations about the tool's current reliability. No contradiction with annotations.

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

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

The description is long and dense, but every sentence carries information relevant to using the tool correctly. It is front-loaded with the core purpose, then structured by mode, response, and safety fields. The length is justified given the tool's complexity, though it could benefit from tighter formatting (e.g., bullet lists). Still, it remains focused and free of filler.

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

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

Given the tool's complexity (cross-venue comparison with safety warnings), the description covers all essential aspects: modes, response fields, safety conditions, temporal alignment, and caveats. With no output schema, it takes on the burden of explaining return values and edge cases, and it does so thoroughly. An agent can determine when to use it and how to interpret results.

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

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

Schema coverage is 100%, and the description adds meaningful semantics: it defines the two modes, explains that explicit ticker/slug override the topic-mapped side, and provides context on the relationship between parameters. It also clarifies that no parameters are required (both modes have defaults from topic). This goes beyond the schema's basic field descriptions.

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

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

The description opens with a clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by emphasizing the cross-venue aspect, the conditions for meaningful spreads, and the safety fields that indicate non-equivalent bet shapes. The two modes and response structure further clarify the tool's specific 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?

The description gives explicit usage guidance: two modes (topic shortcuts vs explicit pairings), and warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It explains when the spread is meaningful and when it is not. It doesn't explicitly mention alternatives like polymarket_arbitrage, but the safety-field explanation effectively tells the agent when not to rely on the result.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds valuable extra context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual retrieve/list behavior. 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, front-loaded with the action, then context, then scoping/pairing. Every sentence earns its place with 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?

For a simple tool with one optional parameter and no output schema, the description covers the core functionality, scoping, usage context, and relationships to sibling tools. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%: the sole parameter 'key' is fully described in the schema as 'Memory key to retrieve (omit to list all keys)'. The description reiterates the omit behavior but adds no new parameter-level detail, keeping this at 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 explicitly states the two modes: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This is a specific verb-plus-resource description that clearly distinguishes it from sibling tools like remember and forget.

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 usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives: 'Pair with remember to save, forget to delete.' It stops short of explicit when-not-to-use guidance, so not 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 discloses that mark_read:true mutates the read state of returned events, which directly contradicts the annotation readOnlyHint=true. This is a significant inconsistency because the annotation claims the tool is read-only while the description describes a state-changing side effect. Hence the contradiction forces a score of 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?

The description is three sentences, front-loaded with the main purpose, and each sentence adds necessary detail: payload contents, filtering options, and mark_read behavior. It is compact and free of fluff, achieving excellent conciseness and structure.

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

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

Even without an output schema, the description gives a solid picture of returned content and core behaviors, including filtering, polling, and an alternative access method. It omits mention of unread_only and limit semantics, but the schema fills those gaps, so the description is sufficiently complete.

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

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

With 100% schema description coverage, the baseline is 3. The description adds extra value by providing a concrete example type ('sec_8k') and explaining mark_read's behavior, thereby going beyond the schema's explanations and making key parameters more understandable.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It further specifies that events carry source, citation_uri, and raw payload, and allows filtering by type and since, which distinguishes it from siblings like recent_changes.

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

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

The description gives clear context: it is for pulling subscription alerts and notes that polling works fine, while also offering an external URL for scripts. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks 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?

Beyond annotations, it discloses the fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO with soft-fail behavior. It also describes the return shape (changes[], total_changes, citation URIs), which is not present in annotations.

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

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

The description is dense and information-rich with front-loaded usage triggers, but slightly long. Every sentence contributes, though the multiple 'what's new' examples could be trimmed without losing meaning.

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

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

For a multi-source aggregation tool with no output schema, it covers data sources, fallbacks, failure modes (USPTO sunset), parameter formats, output structure, and the key sibling alternative. No critical usage context is missing.

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

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

Schema coverage is 100%, but the description adds value with concrete formats for 'since' (ISO or relative shorthand), example values, and the distinction between ticker and CIK for 'value'. It also notes 'type' currently only supports 'company'.

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 immediately defines the tool as a change feed for a company in a specified time window, with concrete query triggers ('What's new with X'). It also distinguishes itself from the sibling tool entity_profile by explicitly directing users who want a static profile to that 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 provides explicit when-to-use guidance via natural language examples and states the window-based scope. It names entity_profile as the alternative for static profile needs, giving a clear exclusion criterion.

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 beyond annotations by explaining persistence semantics: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' It also discloses that storage is scoped by identifier and stored as a key-value pair. Annotations (readOnlyHint=false, idempotentHint=true) are consistent with the described write-and-overwrite 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 compact at three sentences, each carrying distinct and necessary information: purpose, usage scenario, and persistence behavior. It is front-loaded with the core purpose and ends with complementary tool references, using no redundant or filler words.

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

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

For a simple two-parameter tool with no output schema, the description fully covers what is needed: purpose, when to use, persistence details, and relationship to recall/forget. Combined with the accurate annotations, an agent has all essential context 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 input schema already describes both parameters (key and value) with examples and value format, giving 100% coverage. The description adds minimal new semantic detail beyond reminding that the value is 'any text', so it does not significantly 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 clearly states the tool saves data the agent will need to reuse later, with a specific verb 'Save' and resource 'data'. It distinguishes itself from sibling tools by explicitly naming complementary tools recall and forget, and provides concrete examples like 'resolved ticker' and 'user preference'.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward...' and explains the benefit ('so you don't have to look it up again'). It also names alternatives/companions: 'Pair with recall to retrieve later, forget to delete.'

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 meaningful context: each call cascades through multiple lookup endpoints, unresolved identifiers are explicitly listed under 'unresolved', and LEI/FIGI enrichment degrades gracefully. 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 long but every sentence contributes: examples establish purpose, usage guidance is explicit, supported types are elaborated, and caveats are stated. The structure is front-loaded with the core purpose and then elaborates on details, making it easy for an agent to parse.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, fallback behavior), the description covers inputs, outputs, and failure modes. Without an output schema, it clearly explains return values (identifiers labelled with source, explicit unresolved list). 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 both parameters with 100% coverage. The description adds value by explaining what the resolved output contains for each type (e.g., CIK/ticker/LEI/FIGI for company, RxCUI/ingredient/brand for drug) and how unresolved identifiers are handled, going beyond the schema's basic 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 explicitly states the tool resolves a user-spoken name to canonical/official identifiers, with clear examples and supported types. It distinguishes itself by focusing on ID resolution ('Use FIRST whenever you have a name but need an ID'), which is distinct from sibling tools like entity_profile or compare_entities.

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

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

Provides direct guidance with 'Use FIRST whenever you have a name but need an ID' and details what types are supported (company/drug), including accepted input formats. It also explains graceful degradation when enrichment sources are unavailable, clarifying when to rely on 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?

With annotations already declaring read-only, open-world, idempotent, and non-destructive behavior, the description adds context about the internal probing mechanism (ai_visibility_check), ranking logic, and output structure (score, confidence, signal density). This usefully extends beyond annotations without contradiction.

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

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

The description is three sentences, front-loaded with the core action, followed by mechanics and use case. Every sentence earns its place with no redundancy or filler.

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

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

The description covers the output format (ranked list with score, confidence, signal density) and use case, which is sufficient for a read-only tool with full schema coverage. It lacks details on model selection behavior or error handling, but these are not critical given the annotations and 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 description coverage is 100%, so the schema already documents all parameters. The description adds marginal context by clarifying 'entities' as 'your brand + N competitors' and the narrative subject, but this is also covered in the schema's 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes from siblings by explaining it probes each entity with ai_visibility_check and ranks results. The competitive audit use case further cements its unique purpose.

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

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

It explicitly frames the tool for competitive AI-marketing audits and provides an example query, giving clear context for when to use it. However, it does not mention when not to use it or alternatives like compare_entities, so it lacks explicit exclusions.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses latency and failure behavior: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns'. It also describes the output structure, which is critical since no output schema is provided.

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

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

The description is rich but every sentence carries distinct value. It front-loads the core purpose, then covers usage, output, ecosystem limits, and failure handling. No redundant or filler content is present.

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 (multiple data sources, no output schema), the description covers the main output fields, latency, failure modes, and ecosystem scope. It fully equips an agent to invoke and interpret results without needing additional documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'version' and 'package' in passing but does not add any meaning beyond the schema's own descriptions. For instance, the schema already states the version defaults to latest when omitted, and package accepts scoped names.

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 'Composite "should I add this npm package to my project" check in ONE call', clearly stating the tool's function as a dependency vetting aggregation. It names the specific data sources (deps.dev, bundlephobia) and output categories, making it distinct from any sibling 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which points to an alternative approach.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds significant behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. 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, each earning its place: purpose, usage guidance, technical implementation. Front-loaded with the main action, then contextual usage, then implementation details. 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?

Despite no output schema, the description explains return values ('top-N passages with character offsets and similarity scores') and limitations ('cap is 200K chars... truncated and flagged'). It also places the tool within a workflow (fetch → search → ground). Complete for a search tool with strong annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds illustrative context beyond the schema: for 'text' it provides concrete examples ('SEC 10-K body, an article, a long tool result'), and for 'query' it gives example queries. This enriches parameter understanding without being redundant.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings by emphasizing 'INSIDE' and explicitly pairing with ask_pipeworx_grounded, clarifying it operates on already-fetched text rather than external sources. Examples like 'SEC 10-K body' and 'article' further ground the purpose.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with the alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and how-it-fits guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable output context: human-readable labels, an observing_quality verdict, best_window summary, and 3-hour resolution up to 72 hours. This exceeds the minimum transparency bar and provides concrete behavioral details 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 concise and front-loaded, with the key purpose stated first, followed by metrics and output details. It uses efficient punctuation and includes only one minor extra ('Keyless') at the end. It is not overly verbose and every sentence contributes 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 adequately explains what the tool returns: metrics, human-readable labels, an observing_quality verdict, and a best_window summary. It also specifies time range and resolution. This is sufficient for an agent to understand the tool's full behavior and output.

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 all three parameters are already clearly described. The description adds no new parameter-level semantics beyond restating the 3-hour resolution and 72-hour max, which the schema already covers. The baseline of 3 applies because the schema carries the full burden.

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

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

The description clearly identifies the tool as an astronomy observing forecast from 7Timer! ASTRO, listing specific metrics (cloud cover, seeing, transparency) and differentiating it from generic weather forecasts. The verb 'forecast' plus resource 'astronomy observing' is specific and distinguishes it from sibling tools like weather_forecast.

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

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

The description clearly implies its intended use case: 'the metrics stargazers and astrophotographers use to decide if tonight is good for observing.' It also notes the tool is 'Keyless,' which is a practical usage detail. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

The description richly discloses behavioral traits beyond the annotations, such as return value ('Returns the new subscription id'), account prerequisites ('anonymous + BYO cannot persist subscriptions'), SMS limits ('10/day cap'), phone verification ('phone must be verified at /account first'), webhook security details ('signing secret returned once', 'HMAC-signed', 'Auto-disabled after 10 consecutive failing runs'), and feed consumption ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). These details address side effects, failure modes, and operational constraints, going far beyond the structured 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 starts with the core purpose and returns value, then efficiently covers requirements, supported types, and delivery channels. It is a single dense paragraph with no fluff, but it does duplicate some information already in the schema (e.g., type examples and delivery options). The length is justified for the tool's complexity, but a more structured layout (e.g., bullets) could improve scannability. Overall, it is well-organized and front-loaded.

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

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

For a tool with no output schema and nested objects, the description is highly complete. It covers the return value, all supported subscription types, required parameters, delivery channels, authentication prerequisites, SMS/phone verification, webhook signing and failure behavior, and how to consume the persistent feed. It also gives concrete examples for each type. This leaves little ambiguity about how to invoke the tool and what to expect.

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 itself already provides detailed descriptions for each parameter, including the type-specific params examples and delivery channel formats. The description adds a concise overview of supported types (e.g., 'sec_8k' ... 'items:["5.02"] = officer change') and clarifications like 'feed always on', but this mostly summarizes or restates what is already in the schema. It does not introduce materially new parameter semantics beyond the structured schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (create) and resource (subscription to a live-data event stream), and the return value is explicitly noted. It is easily distinguished from sibling tools like list_subscriptions and unsubscribe, which serve related but different functions.

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 use, including the OAuth requirement ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and available delivery channels with mechanisms ('feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)'). It does not explicitly name alternative tools for when not to use this one, but the constraints and channel guidance imply appropriate usage patterns. This is slightly above 'implied usage' but not fully explicit with exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description adds value beyond that by explaining the output is drawn from a live catalog of thousands of tools and organized into category buckets, plus how the optional topic parameter changes the result. This is useful additional context, though it does not cover every aspect of 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 longer than average but every section earns its place: example queries signal trigger phrases, then the core purpose, output structure, parameter behavior, and usage instruction are each addressed in a structured way. The initial list of example phrasings is slightly redundant but valuable for matching user intents, so it is reasonably concise for the content covered.

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 carries the burden of explaining return values. It specifies the return format (category-bucketed example questions with exact tool + argument shape), the data source (live catalog), the parameter toggle, and the intended first-use scenario. This is complete enough for an agent to invoke the tool correctly in context.

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

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

The schema already documents the topic parameter with a list of allowed values and meaning, giving 100% coverage. The description adds meaningful behavior beyond the schema: omitting the topic returns a cross-category spread while passing a topic focuses results, with concrete examples ('finance', 'pharma', 'betting'). This raises it above the baseline 3.

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

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

The description opens with concrete user prompts ('What can I ask Pipeworx?') and then clearly defines the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. This clearly distinguishes it from siblings like ask_pipeworx or discover_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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools (ask_pipeworx, entity_profile, compare_entities). This provides a clear when-to-use condition and names follow-up alternatives, satisfying the 5-point criterion.

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, the description discloses that the operation deactivates the row rather than deleting it, and that historical events remain available via recent_alerts. This adds significant behavioral context beyond what readOnlyHint and destructiveHint 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 two sentences, front-loaded with the primary action, and each sentence adds essential information (action, ownership, deactivation behavior). There is 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?

Given the simple one-parameter operation, the description is complete: it explains the effect, the ownership rule, and the retention of historical data via recent_alerts. Even without an output schema, the side effects are sufficiently disclosed for an agent 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 input schema already provides 100% coverage for the single parameter (id) with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb-resource pair ('Cancel a subscription by id') and clearly distinguishes from siblings like subscribe and list_subscriptions. It also adds the ownership constraint, making the purpose unambiguous.

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

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

The description clearly implies the usage context: when a user has a subscription id and wants to cancel it. It also states a key constraint (ownership is enforced) but does not explicitly name alternative tools or list when-not-to-use cases, which prevents a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: the meaning and implications of each verdict (especially that could_not_verify is not evidence), the structured SEC EDGAR path vs. grounded pipeline, and the inclusion of verbatim evidence with pipeworx:// citations. This goes far beyond what annotations 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 lengthy but well-structured: examples, usage directive, routing details, return format, and a caller warning. Every element contributes operational value; for instance, the 'IMPORTANT for callers' note is critical and not redundant. It is dense but not wasteful, so a 4 is appropriate.

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 provided, the description carries full responsibility for explaining return values. It enumerates verdict categories, the actual value with citation, reasoning, and clarifies the distinction between could_not_verify and unsupported. It also notes efficiency benefits (replacing 4–6 sequential calls). This is complete for safe and correct use.

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 descriptions. The description adds practical guidance on tolerance_pct (e.g., 'set 1–2 for hallucination detection') and clarifies that the default is implied by wording (capped at 5). This extra context helps an agent choose appropriate values, so it earns a 4.

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

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

The description opens with recognizable natural-language queries ('Is it true that...', 'fact check', 'verify the claim') and then explicitly defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes this tool from siblings like ask_pipeworx_grounded or bet_research by its specific fact-checking mandate.

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 an explicit when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates two use cases (company-financial claims vs. any other factual claim) and explains the routing logic, which is sufficient 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 readOnlyHint=true and destructiveHint=false, and the description adds valuable context: 'Keyless' (no authentication) and the specific 3-hour resolution up to 72 hours. The description also lists the exact data fields, providing behavioral expectations beyond the annotations. 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?

Single sentence that front-loads the tool's purpose ('General weather forecast from 7Timer! CIVIL') and efficiently lists the data fields and resolution. 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?

For a read-only weather forecast tool with no output schema, the description sufficiently enumerates the returned data types and time resolution. It lacks units or error conditions, but the annotations cover safety, making this adequate for selection.

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

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

The schema already describes all three parameters (latitude, longitude, hours) with 100% coverage, so the baseline is 3. The description reinforces the hours resolution ('3-hour resolution out to 72 hours') but does not add additional parameter semantics beyond the schema.

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

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

The description clearly states the tool provides a 'General weather forecast from 7Timer! CIVIL' with specific data fields (temperature, humidity, condition code, cloud cover, wind, precipitation). This is distinct from sibling tools like stargazing_forecast by explicitly focusing on weather conditions.

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?

No explicit alternative guidance is given. The phrase 'General weather forecast' implies this is the default weather tool, but it does not mention when to prefer sibling tools like stargazing_forecast or ai_visibility_check. Usage context is implied rather than stated.

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