L2beat

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds that data comes from L2BEAT, UOPS is only sometimes available, and it returns a time series. This extra context about data source and optional fields is valuable beyond annotations.

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

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

The description is a single sentence of 18 words, efficiently conveying core functionality and parameters. It is front-loaded and every word serves a purpose.

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

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

With an output schema present, the description focuses on input parameters and data source. It covers essential aspects: data returned (transaction count, UOPS if available), scope (L2 project or all), and accepted parameters. It could mention daily granularity more explicitly, but overall it is adequate.

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 with 100% coverage. The description adds default values for range (30d) and slug (all), which are not present in the schema. It also reiterates allowed range values, reinforcing the schema. These additions enhance clarity.

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 returns 'Daily transaction count (and UOPS where available) time series', specifying the resource and action. It distinguishes from siblings like list_projects or get_project, which focus on static project data, and tvs_history, which is about TVS. The scope (L2 project or all projects) is defined.

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

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

The description provides no explicit guidance on when to use this tool over alternatives. It does not mention when not to use it or any prerequisites. The context of siblings implies it is for transaction count, but without explicit direction, an agent may misuse it for other metrics.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about cost implications (BYO key for Anthropic) and default model, which goes beyond annotations.

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

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

The description is concise with four focused sentences, front-loaded with the core purpose. Every sentence adds unique value without redundancy.

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

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

For a tool with 4 parameters and no output schema, the description adequately explains required inputs, optional parameters, and the structure of the return value (per-model fields and combined view). Use cases are also provided.

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

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

Input schema covers all parameters with 100% description coverage. The description adds meaning beyond schema by explaining default model, key usage for Anthropic, and the purpose of the 'context' parameter.

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

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

The description clearly states the tool probes LLMs for knowledge of an entity and returns a visibility score. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by specifying multi-model probing and scoring.

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

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

The description provides clear use cases (AI-marketing audits, brand checks, monitoring) and explains when to use optional parameters like '_apiKey'. However, it does not explicitly mention when not to use this tool or alternative tools.

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

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

Annotations already declare readOnlyHint and openWorldHint. Description adds that it is a fast single call, works on every tier, and returns structured answers with citation URIs. No contradictions; the description enriches the behavioral model without repeating annotations.

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

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

The description is somewhat lengthy but well-structured with clear sections, examples, and comparisons. It is front-loaded with the key directive. A slight reduction in verbosity would make it a 5.

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 (many sources, 33 sibling tools), the description fully explains the tool's role, when to use alternatives, and what output to expect. Without an output schema, it adequately describes the return as structured answers with citations.

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 all parameters are documented. The description adds value by explaining that the tool accepts natural language and multiple aliases (query, q, prompt, etc.), and that it automatically routes to the right source and fills arguments.

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

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

The description clearly states the tool routes questions to 4,945 tools across 1,300 sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded (more rigorous) and deep_research (broad multi-part questions).

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides when-to-use (factual questions) and when-not-to (alternatives named), includes examples and a clear directive: 'START HERE for most questions'.

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 are false. The description adds value by explaining source-preference ranking, fallback behavior ('falls back to nothing'), and that it is a full working router. No contradiction with annotations.

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

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

The description is somewhat lengthy but packs essential information upfront (identity, behavior, usage context). Every sentence adds value, and it avoids redundancy. Could be slightly trimmed but remains 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?

Given the tool's complexity as a beta router with many underlying tools, the description covers experimental nature, comparison to stable router, source-preference logic, and fallback behavior. Required parameters are documented with aliases. No output schema but behavior sufficiently explained.

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

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

Schema coverage is 100% with all parameters described. The description adds no additional meaning beyond noting alias parameters, which is already in the schema. Baseline score of 3 appropriate.

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

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

The description clearly identifies it as a beta version of ask_pipeworx with identical functionality but experimental routing improvements. It specifies the verb/action ('ask'), the resource (Pipeworx), and distinguishes it from siblings by highlighting its experimental edge.

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 instructs to use it like ask_pipeworx when wanting the newest routing, and implies that for stable results, the non-beta version should be used. It mentions source-preference ranking behavior. Could be more explicit about when not to use, but provides sufficient context.

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

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

Reports extra LLM call cost, describes return structure with answer/evidence/refusal reasons, and aligns with annotations (readOnlyHint etc.). 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?

Well-structured and front-loaded with key info, though slightly verbose; every sentence adds value for a complex tool.

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

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

Comprehensive for a tool with 4,991 sources and refusal handling; describes return values despite no 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% with clear parameter descriptions; the description adds no additional parameter-level detail beyond usage context.

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

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

Clearly describes a hallucination-resistant answer mode for high-stakes reads, distinguishing from ask_pipeworx by noting extra cost and 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?

Explicitly states when to use (quoted/cited answers, high-stakes) and when not to prefer ask_pipeworx for casual lookups.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, confirming safe read operations. The description adds extensive behavioral details: resolution process, classifier fan-out, response shape fields, safety short-circuits for low-confidence matches, closed markets, wide spreads, resolution-rule risk, and parent event extraction. It explains edge cases and data sources, far exceeding annotation-provided info.

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

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

The description is long but well-structured and front-loaded with the main purpose and usage. Each section (classifiers, fan-out examples, response shapes, safety) earns its place. While dense, it avoids redundancy. A slightly more concise summary at the start could improve, but the detail is justified given the tool's complexity.

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

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

Despite no output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence, parent_event, news fields) and special cases (low confidence, closed markets, wide spreads, resolution-rule risk, cancellation rules). It provides enough detail for an agent to fully understand tool behavior and outputs.

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 three parameters described. The description adds significant meaning beyond the schema: for 'market' it explains accepted formats (slug, URL, question) and shows examples; for 'depth' it clarifies quick vs thorough and default; for 'include_raw' it explains summarized vs full payloads and use cases. This enriches the agent's understanding of parameter usage.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), the resource (Polymarket bet), and the scope (one call). It distinguishes from siblings like 'polymarket_edges' and 'polymarket_arbitrage' by focusing on a comprehensive single-bet research call with fan-out and evidence packet.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also discusses the 'depth' parameter for quick vs thorough analysis. However, it lacks explicit when-not-to-use or comparisons to sibling tools for exclusion. The intended use cases are clear but not exhaustive.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by specifying data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), mention of off-calendar fiscal year handling, and sorted results. However, it omits potential limitations like data freshness or error handling.

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

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

The description is concise for the amount of information conveyed, with clear structure and examples. It is slightly lengthy but every sentence adds value, avoiding redundancy.

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

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

Given no output schema, the description adequately explains return values (financial metrics for companies, adverse events/trials for drugs, sorted results, citation URIs). It is sufficiently complete for a comparison tool with good 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%, but the description enriches semantics: for 'type' it explains data source differences, and for 'values' it gives examples and constraints (tickers vs drug names, 2-5 items). This adds context beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and 'side-by-side', and distinguishes from siblings like 'entity_profile' by emphasizing parallel lookup over sequential single-pack lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. It gives context for when to use, though it lacks explicit when-not-to-use scenarios.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds extensive behavioral details: account requirement, free vs paid, parallel execution, facet decomposition, hop iteration (gap recovery, leads chasing), contradictions scan, semantic excerpting, timing estimates. 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 lengthy but each sentence serves a purpose: account requirement, alternative tool, core functionality, depth behaviors, return format, timing. It is front-loaded with critical usage constraints. Could be more structured (e.g., bullet points for depth options) but is dense and well-organized.

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

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

Given 2 parameters with full schema coverage, no output schema, and annotations present, the description covers all essential aspects: what it does, how it works (parallel facets, hops), return structure (findings packet with evidence, confidence, source, citations, gaps, contradictions), timing, and edge cases (breaking news yields empty gaps). It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% for both parameters. The description adds significant value beyond schema: explains depth values (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative chase), and clarifies that question can be broad/multi-part. The schema only lists enums and types, so the description enriches the 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 it performs grounded multi-source research across structured data sources, decomposing questions into facets and routing to many tools in parallel. It distinctly separates from sibling ask_pipeworx by specifying it's for broad/multi-part questions over structured data, not single lookups or open-web search.

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

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

Provides explicit guidance: best for broad/multi-part questions over structured data, not for breaking news or single lookups. Recommends ask_pipeworx as alternative for those cases, and mentions account tiers and depth options. No ambiguity about when to use versus siblings.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds useful output details: returns top-N tools with names, descriptions, full schemas, and examples. Adds value beyond annotations.

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

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

Concise and well-structured: starts with clear purpose, provides examples, explains use case, and details output. Every sentence adds value without redundancy.

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

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

Covers main use case, output format, and when to use. Missing details on pagination or error handling, but given no output schema, this is adequate for a discovery tool.

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

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

Schema coverage is 100% and schema descriptions already explain each parameter and aliases. Description does not add new parameter-level meaning beyond what schema provides.

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

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

Clearly states the tool's purpose as discovering tools by describing data or task. Includes specific examples (SEC filings, FDA drugs) and distinguishes from sibling tools by being a meta-search/discovery tool.

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

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

Explicitly advises to use when browsing or searching for tools, and to call FIRST when many tools are available. Provides clear context for when to use vs. other tools.

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

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

Describes multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), return fields (cik, company_name, filings with URIs, fundamentals sorted, patents soft-fail, news fallback), and caveats. Annotations already indicate readOnlyHint=true and idempotentHint=true, so description adds valuable behavioral context without contradiction.

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

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

Description is dense and informative, front-loaded with example queries. However, it could be more structured (e.g., bullet points for return fields) rather than a single paragraph. Still, every sentence adds value.

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

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

Given no output schema, the description fully describes what is returned (filings, fundamentals, patents, news, LEI) and includes fallback behaviors and limitations. It references sibling tool 'resolve_entity' for name resolution, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds meaning by explaining that 'type' is only 'company', 'value' must be ticker or zero-padded CIK (names not supported), and provides examples like 'AAPL' or '0000320193'. This goes beyond schema to clarify usage constraints.

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 returns a 'full cross-source profile of a US public company in ONE parallel call', using specific verbs like 'research', 'brief me', and 'tell me about'. It distinguishes from sibling tools like 'resolve_entity' and from chaining single-source lookups.

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)' and gives clear input requirements (ticker or zero-padded CIK).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms action but adds no new behavioral information beyond annotations.

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

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

Three sentences with no wasted words. Action stated first, then use cases, then sibling references.

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

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

For a simple 1-parameter tool with no output schema, the description sufficiently covers purpose, usage, and relationships to siblings.

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

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

Schema has 100% coverage with parameter description 'Memory key to delete'. Description does not add extra meaning beyond schema.

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

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

Description explicitly states 'Delete a previously stored memory by key' which is a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall'.

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

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

Provides explicit conditions for use: stale context, task done, clearing sensitive data. Mentions pairing with remember and recall for 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it fetches the page, extracts title/description/links, and emits standard markdown format. It does not contradict annotations and provides extra 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 three sentences, front-loaded with the main purpose, and no unnecessary words. It is concise and well-structured.

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

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

Despite no output schema, the description explains the output format (single text blob, markdown). Parameters are covered, and annotations provide safety info. The tool is sufficiently documented 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% with good parameter descriptions. The description does not add significant parameter-level semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description exactly states what the tool does: generate a production-ready llms.txt file for any URL. It uses a specific verb 'generate' and resource 'llms.txt file', and distinguishes its purpose from the unrelated 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?

The description provides clear use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not explicitly state when not to use, but the use cases are specific enough to guide selection.

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, idempotentHint=true, destructiveHint=false, so description adds value by stating what fields are returned. 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?

Single, front-loaded sentence with no waste. Directly states purpose and contents.

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 output schema exists, description sufficiently covers return fields. For a simple retrieval tool, it is complete.

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

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

Schema coverage is 100% with a clear description of 'slug' parameter. Description adds that it returns 'full project record' but no additional parameter-level detail, meeting 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?

Clear verb and resource: 'get' a project by slug returning full record. Lists specific fields (risks, stage, milestones, contracts). Differentiates from sibling 'list_projects' which returns list, not full record.

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?

Implicitly indicates use when needing detailed info for a specific project, as opposed to listing all projects. No explicit when-not or alternatives, but context with siblings makes it 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so description adds value by specifying the scope (L2BEAT-tracked projects) and types. No behavioral 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, clear sentence with zero wasted words. Perfectly concise 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?

Given the tool's simplicity (no parameters, has output schema), the description fully covers the necessary context. No gaps identified.

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 zero parameters, so description need not add parameter info. Baseline score of 3 is appropriate as no additional semantics are required.

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

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

Clearly states the verb 'List' and the resource 'all L2BEAT-tracked projects' with specific types (rollups, validiums, etc.), effectively distinguishing it from sibling tools like 'get_project' which retrieves a single project.

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 guidance on when to use this tool vs alternatives. The description only states what it does without mentioning any exclusions or preferred contexts, leaving the agent to infer usage implicitly.

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

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

Annotations already declare readOnly, idempotent, openWorld, not destructive. Description adds return fields and default active-only behavior. No contradictions.

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

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

Two sentences: first states purpose and returned fields, second provides usage context. Every word earns its place; no waste.

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

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

No output schema, so description lists all return fields. Covers purpose, usage, and parameter context. Complete for a simple list tool with one optional parameter.

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 only parameter. Description mentions 'active subscriptions' default, but parameter description already covers include_inactive. Adds no new semantic value beyond schema.

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

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

Clearly states verb 'list', resource 'subscriptions', and specifies 'caller's active'. Differentiates from subscribe/unsubscribe siblings by mentioning use for reviewing before adding or finding id to cancel.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel', implying alternatives of subscribe and unsubscribe.

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

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

Annotations are all false, providing no behavioral hints. The description compensates by disclosing rate limits (5 per identifier per day), cost (free, no quota impact), and how feedback is processed (daily digests, affects roadmap). This adds significant value beyond annotations, though it could mention idempotency or side effects more explicitly.

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

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

The description is a single focused paragraph with no wasted words. It front-loads the core purpose and immediately provides usage guidance. Every sentence adds value: purpose, when to use, how to format, and process notes.

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 (3 parameters, nested objects, no output schema), the description is comprehensive. It covers purpose, usage scenarios, format expectations, rate limits, and system impact. The lack of output schema is not a gap since feedback submission likely returns a simple confirmation.

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 three parameters. The description further clarifies the 'type' enum values and provides examples of what to include in 'message' (specific tool, error, missing data). It also notes the 2000 char max. This adds meaning beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and it is distinct from sibling tools like 'ask_pipeworx' or 'discover_tools' which serve 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 explicitly lists when to use the tool: bugs, feature requests, data gaps, and praise. It also provides guidance on what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and mentions rate limits. This covers both usage context and format.

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

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

Description reveals data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. Annotations already declare read-only and idempotent. No mention of rate limits or potential staleness, but core behaviors are covered.

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?

Extremely concise: two short paragraphs covering purpose, contents, use cases, and source info. Every sentence adds value. No redundancy or fluff.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers return values, caching, use cases, and data origin. Minor gap: not specifying how many top tools are returned, but the 'top' qualifier implies a limited set.

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 a detailed description for the 'window' parameter. The tool description echoes the window options but adds no new semantic value beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it returns trending calls on Pipeworx, including top tools, packs, and volume, with a verb implied ('return' or 'get'). It distinguishes itself from sibling tools like activity, discover_tools, or validate_claim by focusing on aggregated popularity metrics from other agents.

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

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

Explicitly lists three concrete use cases (discovery, confirmation, alignment) and mentions caching windows. Does not specify when to avoid or list alternatives, but the context is sufficient given the tool's niche.

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 details all behavioral traits beyond annotations: it walks child markets, computes partition checks, applies semantic anchor filtering, partition filter, and fill check. It explains how cross-event mode works and what happens when signals fire. Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description agrees with these.

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

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

The description is long but well-structured with clear sections for each mode, semantic anchor, partition filter, response, and fill check. It is front-loaded with the main purpose. While dense, every sentence adds value. A slight reduction due to length, but it earns its place given 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?

Despite no output schema, the description thoroughly explains the return structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check in event mode. It covers fill check, when not to trade, and directs to another tool for custom sizing. All essential aspects are covered.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds significant meaning: explains the difference between event and topic, provides examples, and describes the logic behind each mode. It also clarifies the impact of passing no arguments.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) and specifies the resource and verb. It also differentiates from sibling tools by mentioning polymarket_fill_risk for custom sizing.

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 guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends event mode for specific markets and explains when cross-event mode is beneficial. It also advises against trading when realizable edge is non-positive and directs to polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations, including caching behavior ('Cached 1h at the KV level keyed on all knobs'), model details (e.g., 'lognormal barrier from 90d FRED log-returns'), filtering logic, and response structure. Annotations already indicate readOnly and idempotent, and the description aligns 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 lengthy but well-organized with clear sections for segments, knobs, and response structure. It is front-loaded with purpose and uses bullet-like formatting. While verbose, every sentence adds substantive information, justifying its length for such a complex tool.

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

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

Given the tool's complexity (9 parameters, no output schema, nested response), the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), why fed bets are excluded, and the purpose of each segment. Without an output schema, this description fully equips an agent 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% with all parameters described. The description adds valuable context beyond schema, such as explaining 'slippage_pp' with Polymarket fee details and 'min_partition_leg_kelly' with precise filtering rationale. Some parameter descriptions are already thorough in schema, so the description supplements rather than substitutes.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan' and 'return', the resource 'Polymarket markets', and the unique value proposition of surfacing discrepancies. It differentiates from siblings like 'polymarket_arbitrage' by focusing on Pipeworx data divergence and providing a high-level overview of the three opportunity segments.

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 sets context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies when to use (discovery) but does not explicitly state when not to use or provide direct comparisons to siblings. The detailed breakdown of segments and knobs gives clear guidance for usage scenarios.

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

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

Annotations already declare the tool read-only, idempotent, etc. The description adds rich behavioral detail: it reads from daily snapshots, computes trends and decay rates, notes TTL and snapshot gaps, and explains the response structure. No contradictions with annotations.

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

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

The description is long but efficiently structured: starts with purpose, then response structure in caps, then args, response fields, and limitations. Every sentence adds value, though an AI might benefit from slightly more concise phrasing for the response section.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, non-intraday decay). It is fully self-contained for an agent to understand what the tool returns and how it works.

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

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

Input schema already describes both parameters (days, window) but the description adds crucial context: defaults (14 days, 1wk window), clamping behavior (2-30), and how they affect which snapshots are read. This adds meaning beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, and answers a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis of edges.

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

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

The description explains when to use the tool (to assess edge persistence and decay, contrasting fresh wide edges with old wide edges) but does not explicitly exclude use cases or mention alternative sibling tools. Provides good context for usage.

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

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

Annotations (readOnlyHint, idempotentHint, not destructive) are complemented by description detailing that it walks the ladder, clamps size_usd (10-1,000,000), and returns specific fields including risk warnings. No contradiction.

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

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

Description is lengthy but well-structured with capitalized headings (SINGLE-MARKET, BASKET) and lists return fields. Every sentence adds value, though some technical density could be streamlined slightly.

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

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

With 4 parameters, no output schema, and no nested objects, the description comprehensively covers all aspects: parameter usage, return values for both modes (listing each field), and edge cases like forced directional risk. No gaps.

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

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

Schema coverage is 100%, but description adds significant meaning: explains interpretation of size_usd per mode, default side logic for baskets, and that market/event are mutually required. This goes beyond the schema's basic 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 starts with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the core function. It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying that this tool checks fill risk before acting on arb signals.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb to directional position) and implies smaller trades may not need 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, openWorldHint, idempotentHint, destructiveHint. The description adds significant context beyond annotations: compatibility_warning conditions (two cases), temporal_alignment, skipped_cross_type/subtype counters, and explanation of why most pre-mapped topics are not tradeable. 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 relatively long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, though minor trimming could improve conciseness. It is front-loaded with the core purpose.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Parameters are fully covered, and the tool is complex; the description leaves no significant gaps.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining the two modes and the effect of each parameter (e.g., overriding topic-mapped sides). It also provides examples in the schema. This adds value 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 explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing two modes (topic shortcuts and explicit tickers) and clarifying when spreads are meaningful. This is specific and differentiates from sibling tools like polymarket_arbitrage.

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 guidance on when to use topic vs explicit modes and warns that most pre-mapped topics return compatibility_warning, so pre-mapped ≠ tradeable. It also explains conditions when the tool should not be used (e.g., when compatibility flags indicate non-equivalent bet shapes or no common outcomes).

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, non-destructive. The description adds value by explaining scoping (by identifier) and mentioning listing behavior, going 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?

Three concise sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

No output schema exists, but the description explains what happens (value or list). Scoping, pairing, and use cases are covered, making it sufficiently complete for the tool's simplicity.

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

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

Schema has 100% coverage with description for the 'key' parameter. The description adds meaning: 'omit to list all keys' and provides examples, which enhances understanding beyond the schema.

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

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

The description explicitly states the tool retrieves a value saved via 'remember' or lists all keys when omitted. It clearly identifies the resource (saved memory) and distinguishes from sibling tools '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?

The description provides clear use cases (looking up stored context like ticker, address, notes) and pairs with remember/forget. It mentions scoping but does not explicitly exclude when not to use.

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

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

Annotations already indicate safety traits (readOnly, idempotent, non-destructive). The description adds behavioral details: returns most recent alerts with specific fields, explains mark_read flag behavior, and confirms polling is acceptable. 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 a single paragraph of 4 sentences, front-loaded with purpose, then details. Every sentence adds value with no redundancy or fluff.

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

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

No output schema exists, so the description must explain return values—it does: 'each carries source, citation_uri... and the raw event payload.' It also covers filtering, mark_read, and alternative access. A minor gap: does not explain pagination or limit behavior beyond the schema.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds examples for type and since, and explains the effect of mark_read. This adds some value but doesn't go far beyond the schema.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and action (pull fired events), distinguishes from siblings by detailing what each returned event contains and filtering 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?

The description provides guidance on when to use this tool ('Polls work fine') and points to an alternative endpoint for scripts/dashboards. It also hints at filtering but doesn't explicitly state when not to use it or contrast with siblings like 'activity' or 'recent_changes'.

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 (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral details: fan-out to multiple APIs, fallback from GDELT to GNews, soft-fail for USPTO due to sunset, and the return structure (changes grouped by source, citation URIs). No annotation 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 a single, moderately long paragraph but front-loaded with practical examples and covers all critical aspects. It is concise enough for quick reading, though some whitespace or bullet points could improve scanability slightly.

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

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

Despite no output schema, the description explains the return format (changes grouped by source, count, citation URIs). It also covers fallback behaviors, parameter constraints, and the alternative tool. Everything needed for correct tool usage is present.

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 value by explaining accepted formats for `since` (ISO or relative shorthand like '7d', '1y') and providing typical usage ('30d' for monitoring). This extra context justifies a 4.

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

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

The description clearly states the tool provides a change feed for a company in a recent time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and giving example queries like 'What's new with X'. It distinguishes itself from the sibling tool entity_profile, which is for static profiles.

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

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

The description explicitly instructs to use entity_profile instead for static profile queries, providing a clear when-not-to-use criterion. It also gives example queries (e.g., 'what happened to Z this week') that illustrate appropriate use cases.

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

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

Annotations indicate idempotent and non-destructive; description adds useful persistence details: authenticated users get permanent storage, anonymous sessions last 24 hours.

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?

Clear, front-loaded purpose and efficient word choice; slightly verbose with 'stored as a key-value pair' but overall 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?

Covers purpose, usage, parameter hints, and storage lifetime; no output schema needed for this write operation.

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

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

Schema covers both parameters with descriptions; description adds usage examples but no additional semantics beyond what schema provides.

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

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

The description clearly states it saves data for reuse, identifies it as a key-value store scoped by identifier, and directly distinguishes it from sibling tools recall 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?

Explicitly says 'Use when you discover something worth carrying forward' with concrete examples, and advises pairing with recall and forget for lifecycle management.

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

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

The annotations already indicate safe, read-only, idempotent, and non-destructive behavior. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' and details the exact return format per entity type, including citation URIs. This exceeds the information provided by annotations alone.

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: it starts with intuitive example queries, states the core purpose, then lists supported types with detailed outputs. Every sentence contributes useful information. While it is relatively long, it is not verbose or redundant, earning a high mark for 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?

Although there is no output schema, the description thoroughly explains the return values for both entity types (e.g., ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It also covers auto-disambiguation and the internal cascading behavior, making the tool fully understandable without additional documentation.

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

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

The input schema already has 100% coverage with clear descriptions. The description adds extra context beyond the schema, such as acceptable inputs for each type (ticker, CIK, name for company; brand/generic for drug) and mentions auto-disambiguation. This adds meaningful value, justifying a score above 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 specifies the tool resolves a name to an official identifier, provides example queries like 'What's the ticker for...', and explicitly distinguishes it from siblings by stating 'Use FIRST whenever you have a name but need an ID.' It enumerates supported entity types (company, drug) and their outputs, leaving no ambiguity about its 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 explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID') and implies when not to (when an ID is already available). It mentions that the tool replaces 2-3 manual lookups but does not explicitly exclude alternative tools, leaving minor room for improvement.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it treats the first entity as the 'subject' for narrative and returns a ranked list with score, confidence, and signal density. 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 concise (4 sentences) and well-structured: first sentence states purpose, second explains mechanism, third gives usage example, fourth summarizes output. No fluff; every sentence adds value.

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

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

Given 4 parameters, no output schema, but comprehensive annotations, the description covers the tool's operation, output fields, and usage context. It could detail the return structure more but suffices for a comparison tool.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds nuance: entities first entry is treated as subject, models default to workers-ai, and apiKey is only needed if anthropic is included. This extra context improves 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 compares AI visibility across multiple entities, using ai_visibility_check for each, and provides a ranked comparison. The verb 'scan' and resource 'competitor ai presence' are specific, and it distinguishes from the per-entity sibling ai_visibility_check.

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 a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use this tool over the per-entity ai_visibility_check. However, it does not explicitly state when not to use or list alternative tools, but the sibling context helps.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant context: fans out across sources, graceful degradation, return structure, and timing issues for bundlephobia. 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?

Description is moderately concise (6 sentences) but each sentence adds value. Front-loaded with purpose. Could trim slightly but no waste.

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 complexity (composite, external sources, partial failures), the description covers purpose, usage, return structure, ecosystems, and failure behavior. No output schema, but return values are detailed sufficiently.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal extra meaning beyond confirming scoped packages and default version. Baseline of 3 is appropriate.

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

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

The description clearly states it is a composite check for evaluating npm packages, specifying the verb (scan/composite check) and resource (npm package). It distinguishes from siblings by stating it's a composite and noting 'NPM ecosystem only in v1'.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also provides exclusion criteria: other ecosystems fall under different tools. Notes partial failure behavior and timing caveats.

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 (readOnlyHint, etc.), description discloses key behaviors: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, offset for verification. Adds significant 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?

Single paragraph with front-loaded purpose, then usage, then technical details. Every sentence adds value, no redundancy. Efficient and 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?

Despite no output schema, description fully explains return format (passages, offsets, scores), limitations (cap, truncation), and retrieval method. Pairs with sibling tool, making it complete for the task.

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 description adds meaning: 'text you already pulled', 'natural-language query', and explains output as top-N passages with offsets and scores. Examples for query enhance 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?

Description uses specific verb 'search inside' and resource 'fetched record', clearly distinguishing from sibling tools like 'ask_pipeworx_grounded'. It explains the function and use case: semantic search within large text, returning relevant passages.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides alternative pairing with 'ask_pipeworx_grounded' and implies when not needed (e.g., small text). Clear guidance.

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

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

The description provides extensive behavioral details beyond annotations: returns id, requires OAuth, details on subscription types and parameters, delivery channels with constraints (phone verification, 10/day cap, webhook signing and auto-disable). 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 well-structured, starting with the core purpose and output, followed by requirements, types, and delivery channels. Every sentence adds value without redundancy.

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

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

Given the complexity (nested parameters, no output schema), the description covers all necessary aspects: purpose, prerequisites, types, parameters, delivery options, and edge cases. It is fully complete 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 schema coverage is 100% and the description adds significant meaning beyond the schema, with concrete examples for each type and detailed explanation of delivery options including webhook HMAC and auto-disable. This exceeds the baseline for high-coverage cases.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and distinguishes from sibling tools like list_subscriptions and unsubscribe. It also mentions the return value (new subscription id).

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

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

The description explicitly requires a Pipeworx OAuth account, indicating when this tool can be used. It does not explicitly contrast with alternatives, but the context of sibling tools (list_subscriptions, unsubscribe) helps differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the return format (category-bucketed example questions with tool+argument shape) and that it draws from a live catalog, which is additional 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 front-loaded with alternative phrasings and is well-structured. It is relatively long but each sentence adds information. Slightly verbose with the list of examples, but not excessive.

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

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

There is no output schema, so the description compensates by explaining the general structure of the output. It covers purpose, usage, and parameter behavior. However, it could describe the format of each example question more precisely.

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 coverage is 100% for the single optional parameter. The description adds value by listing possible values for topic ('finance', 'pharma', etc.) and explaining that omitting it gives a full spread, going beyond the schema's minimal description.

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

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

The description clearly states it is the onboarding entry point that returns categorized example questions. It uses specific verbs ('return', 'draws from') and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by targeting the 'what can I ask' scenario.

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

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

Explicitly advises to use this FIRST when the agent does not know what Pipeworx can do. It also explains the topic parameter for narrowing. However, it doesn't specify when NOT to use it or compare to siblings like discover_tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds useful context: returns today's snapshot from L2BEAT, clarifying data freshness and source.

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

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

Description is a single, front-loaded sentence with no waste. Every part is necessary.

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 one optional parameter and existence of output schema, the description sufficiently explains input and output. No additional details needed.

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

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

Schema coverage is 100% and description of 'slug' parameter is already clear in schema. Description restates 'for a specific L2 project slug or all projects', adding minimal extra value.

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?

Description clearly states verb (returns breakdown), resource (TVS by token category), scope (for a specific L2 project slug or all), and source (today's snapshot from L2BEAT). It differentiates from sibling tools like tvs_history.

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?

Description explains when to use: for a specific L2 project slug or all projects. It implies usage context but doesn't explicitly state when not to use or name 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral traits beyond parameter details. With rich annotations, a score of 3 is appropriate.

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

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

The description is a single sentence that is front-loaded with the core purpose. Every word adds value, with no extraneous information. It defines acronym TVS and covers parameters and defaults efficiently.

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

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

Given the output schema exists, the description does not need to explain return format. It fully covers purpose, parameters, defaults, and aggregate behavior. For a simple historical data tool, this is complete.

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

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

Schema coverage is 100% with adequate property descriptions. The description adds value by explaining the default range ('range (7d/30d/90d/180d/1y/max, default 30d)') and that slug is optional (default aggregate). This provides clarity 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 time series of historical TVS for an L2 project or all projects. It uses a specific verb ('Historical... time series') and resource ('TVS'). While it doesn't explicitly distinguish from sibling 'tvs_breakdown', the purpose is distinct and 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 specifies acceptable range values and the optional nature of the project slug. It implies when to use the tool but doesn't provide explicit guidance on when not to use it or suggest alternatives. This is a minor gap.

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

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

Description adds context beyond annotations: explains row is deactivated not deleted, preserving historical events. This aligns with destructiveHint=false and openWorldHint=true. No contradiction.

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

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

Two sentences, zero waste. Purpose and key constraints are front-loaded and efficient.

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

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

For a simple tool with one parameter and no output schema, the description covers cancellation, ownership, and impact on history. Missing error behavior (e.g., invalid id) but adequate overall.

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?

Only one parameter (id) with schema description already clear. Description notes id is uuid from subscribe, which is consistent with schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Clear verb+resource: 'Cancel a subscription by id.' Distinguishes from siblings like subscribe and list_subscriptions by specifying cancellation and ownership enforcement.

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?

States ownership enforcement ('you can only cancel your own subscriptions'), giving clear context. No explicit when-not-to-use or alternatives, but the condition is sufficient for basic guidance.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, etc.). The description adds meaningful behavioral context: the two routing paths (structured vs. grounded pipeline), the use of 'exact percent-delta math' for financial claims, and the return format (verdict, actual value, citation). This goes beyond annotations.

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

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

The description is front-loaded with synonyms and usage context, then efficiently explains the two pipeline paths and return value. Every sentence serves a purpose, though the length is moderate. No wasted words, but could be slightly tightened.

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

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

Given no output schema, the description adequately covers return structure (verdict, actual value, citation, reasoning) and the two processing modes. However, it omits edge cases like source unavailability or error handling, which are relevant for completeness.

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 value by explaining the 'tolerance_pct' parameter's default behavior and override use cases (e.g., 'set 1–2 for hallucination detection'). This additional context helps an agent choose the correct value.

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 using multiple synonyms and explains it verifies factual claims against authoritative sources. It describes two distinct pipelines (company-financial vs. other claims). However, it does not explicitly differentiate from sibling tools like 'deep_research' or 'ask_pipeworx_grounded', which could also handle fact-checking.

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

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

The description provides a clear when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two processing paths. However, it lacks explicit guidance on when NOT to use the tool and does not mention alternative tools among the siblings.

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