Wakatime

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds meaningful context: the default free model (Workers AI Llama-3.3-70b), the optional Anthropic probe with BYO key and direct billing to the user, and the return structure per-model. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the core action and output, then cost note, then use cases. Every sentence earns its place; no fluff.

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

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

The tool has 4 params (1 required) and no output schema; the description covers the return shape explicitly, explains the free/default vs paid/optional path, and states when it is useful. This is sufficient for an agent to select and invoke correctly.

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

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

Input schema already covers all 4 parameters with 100% description coverage. The description reiterates the default model and the _apiKey behavior, but adds no new semantic details beyond what the schema already provides; thus baseline 3 applies.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business/brand/product/topic'), and clarifies the scoring output (0-100 per model). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on LLM knowledge probing rather than broader AI presence scanning.

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 closing sentence names three concrete use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not enumerate exclusions or direct alternatives, but the context is clear enough to guide when to invoke this tool. Since it doesn't explicitly compare to scan_competitor_ai_presence, it misses the top tier.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat that. It adds valuable behavioral context: it routes across 5,000+ tools, fills in arguments, and returns stable pipeworx:// citation URIs. It doesn't discuss error or latency behavior, but that is a minor gap given the annotation coverage.

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 it is packed with useful selection criteria, examples, and explicit alternatives. It front-loads the strongest direction ('PREFER OVER the tool') and uses the rest of the length for real disambiguation value rather than filler.

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

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

Given the tool's high route complexity and lack of an output schema, the description gives enough to let an agent invoke it correctly: natural-language input, scope, expected output of citation URIs, and sibling routing decisions. It doesn't spell out return formatting or edge cases, but that is not essential for correct selection and invocation.

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

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

The input schema already fully covers all parameters: six aliases for the request, all with descriptions, giving 100% schema_description_coverage. The description does not add deeper parameter behavior, and it doesn't need to; the baseline 3 applies because the schema carries the parameter expertise completely.

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

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

The description clearly states that ask_pipeworx answers factual, current or historical data questions by routing to many internal data tools and returning a structured answer with citations. It uses strong verbs like 'routes', 'fills arguments', and 'returns', and separates itself from siblings with the 'START HERE' framing.

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

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

It explicitly identifies when to use the tool: factual questions, real-world entities, events, numbers, even when web search could answer. It also names alternatives such as ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, and search_within, so the agent knows when not to use it. The distinction is specific and operational.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: it is a live beta with experimental routing candidates, currently has no active candidate, and falls back to nothing—it is a genuinely working router. This gives the agent a realistic behavioral model without contradicting annotations.

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

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

The description is information-dense and front-loaded, immediately distinguishing the beta from the stable router. Some minor redundancy exists between 'identical universal router', 'same arguments', and 'use it exactly like ask_pipeworx', but each sentence still contributes useful context about the experimental status and fallback behavior.

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

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

The description covers all important use-context dimensions: current behavior, experimental risks, equivalence to ask_pipeworx, argument compatibility, response shape, and fallback reality. Given the schema fully documents parameters and there is no output schema, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with each parameter already documented as an alias for question. The description adds only that the arguments are the same as ask_pipeworx, but does not need to elaborate because the schema already defines all six parameters and their aliases clearly. This is the baseline case where the schema carries the parameter-semantics burden.

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

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

The description clearly identifies the tool as the beta/experimental version of ask_pipeworx, a universal router with 5,596 tools, same arguments, and same response shape. It distinguishes this tool from the stable ask_pipeworx by the live candidate-routing behavior, so an agent can tell them apart.

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

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

It explicitly says to use it like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It does not fully spell out when NOT to use it in favor of ask_pipeworx, but the current 'no candidate active' state makes that distinction less critical.

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 readOnly/idempotent hints, the description discloses a refusal behavior with specific reasons (`not_in_source`, `no_tool_match`, `tool_error`, etc.), the extra LLM call cost, and the strict use of only tool-result content. It also clarifies the success/output object structure, offering substantial transparency.

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

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

The description front-loads the core capability and then packs each subsequent sentence with high-value details: output structure, refusal reasons, use cases, and cost trade-off. Every sentence earns its place without repetition or tangents.

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 deceptively complex tool, it covers the routing mechanism, the grounded extraction behavior, the refusal contract, and the cost tradeoff. Combined with the provided annotations and schema, an agent has everything it needs to call this correctly and interpret the response.

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

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

Schema description coverage is 100%, and the schema already documents the `question` parameter and its aliases thoroughly. The description adds no extra semantic nuance about the parameters beyond saying 'question in natural language', so a 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 is explicit about the tool's purpose: it is a 'hallucination-resistant answer mode' that 'picks the right tool, fetches the data, then EXTRACTS the answer using ONLY what the tool result contains.' This clearly distinguishes it from the sibling ask_pipeworx with the 'grounded' capability.

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

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

It provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on', and warns against casual use: 'prefer ask_pipeworx for casual lookups.' It also gives concrete examples of high-stakes contexts such as financial verdicts, legal claims, medical lookups, and public statements.

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 cover readOnly/openWorld/idempotent/non-destructive. The description goes far beyond by detailing the resolver contract (market_match_confidence, alternatives, suggestions), parent_event extractor, news fallback fields, and resolution-rule risk parsing (refund_50_50, etc.). It also documents status values like 'low_confidence_match' and 'market_closed_or_inactive'. This is rich behavioral disclosure.

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

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

The description is long but every section adds critical information for a tool with this complexity. It starts with a clear one-line summary, then systematically covers classifiers, fan-out examples, response shapes, resolver contract, safety mechanisms, and resolution-rule risk. While not terse, the structure is logical and there is no redundancy with the schema or annotations.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It explains return values (result.market, result.analysis, result.evidence), the resolver contract, parent event handling, news fallback, safety statuses, and rule-based risks. It also includes concrete fan-out examples for different bet types, making it self-sufficient for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage for all three parameters with clear descriptions. The description adds value by providing concrete examples of market inputs (slug, URL, question text) and contextualizing depth/include_raw within fan-out behavior and response sizes. It also explains how the market parameter is resolved and matched, which goes beyond the schema's basic type.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this tool from sibling Polymarket tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on evidence gathering and market-model comparison.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides safety guidance such as 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing sports/esports/event-occurrence bets.' This gives clear context without naming 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 agent knows it is a safe read operation. The description adds context by disclosing the return fields and clarifying that it reports WakaTime-attributed coding time per commit, going beyond the annotation flags. 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 two sentences, front-loaded with the core action and parameters, then providing return value details. Every clause 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?

For a read-only listing tool with five parameters (two required) and an output schema, the description covers key elements: parameters, required/optional status, special values, and return fields. It omits pagination details (e.g., page size, sorting) but that is not critical given the output schema exists. It is adequately complete for safe invocation.

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

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

Schema coverage is 0% (no property descriptions), so the description carries the burden. It identifies user_id and project as required (given user_id or 'current' and project name), spells out optional author, branch, and page, and explains user_id accepts the special value 'current'. This adds practical meaning beyond the bare schema types.

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

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

The description opens with 'List the commits WakaTime has recorded for one project,' clearly specifying the verb (List), resource (commits), and scope (one project per user). It distinguishes from sibling tools like 'durations' or 'heartbeats' by focusing specifically on commit records with their associated coding time.

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 context by stating the tool returns commit hashes, messages, authors, branches, timestamps, and coding time, and answers what has been committed and how much editor time went into it. However, it does not explicitly mention when to prefer this over sibling tools or exclude alternatives, so some guidance is implied but not fully explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS, FDA), fiscal-year handling, sorting by primary metric, and citation URIs. This goes well beyond the annotations without contradicting them.

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

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

Every sentence earns its place. The description is dense but not wasteful: trigger phrases, purpose, preference rule, per-type data details, sorting behavior, and output format. Any reduction would lose critical decision-making information for the agent.

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

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

With no output schema, the description covers return type ('paired data + pipeworx:// citation URIs per entity') and sorting, which is adequate. It could be more specific about the response structure per type, but the description is still sufficient for an agent to understand the tool's behavior and 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%, but the description enriches both parameters. For 'type', it explains what company vs drug pulls (10-K metrics vs FAERS/FDA/trials). For 'values', it provides concrete examples (['AAPL','MSFT'], ['ozempic','mounjaro']) and reinforces min/max constraints. This adds meaningful semantic detail beyond the schema.

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

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

The description opens with clear trigger phrases and a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It explicitly distinguishes from sibling single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential 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?

Explicit usage guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists concrete example queries and differentiates between company and drug use cases, making it clear when this tool should be selected over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. It does add the context that the profile is 'authenticated,' implying it depends on the current auth state, but it doesn't disclose behavior like error cases or rate limits. The description is consistent with annotations, so no contradiction.

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

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

The description is extremely concise with only three words, which is good for front-loading, but it's under-specified. It's a fragment rather than a complete sentence, and while it doesn't waste words, it might omit essential information for clarity. For a tool this simple, the brevity is acceptable but not exemplary.

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 minimal complexity (0 params) and the presence of annotations and an output schema, the description could be sufficient. However, it lacks usage guidance and doesn't explicitly state the operation or distinguish from similar tools. The description is complete enough for a simple retrieval but leaves some contextual 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter meaning, and the empty schema already provides full coverage. No additional semantic value is required here.

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 'Authenticated user profile' is a noun phrase rather than a clear verb+resource statement. It implies the tool returns the profile of the authenticated user, but it doesn't explicitly state what action is performed. It also doesn't differentiate from the sibling tool 'user', which may cause confusion.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, contexts, or exclusions. With siblings like 'user' and 'entity_profile', an agent needs more direction to select the right tool.

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

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

Beyond the read-only/idempotent annotations, the description discloses account and plan requirements, parallel decomposition, verbatim evidence with confidence/source/fetched_at, explicit gaps[] so answers are never invented, contradiction[] behavior, citation_uri fetchability conditions, semantic excerpting, and expected latency. The openWorldHint is not contradicted; the description scopes the world to Pipeworx's structured catalog.

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

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

The description is long but every sentence adds value: authentication, alternatives, source scope, output packet structure, iteration behavior, latency, and citation guarantees. It is dense but appropriately sized for a tool with this complexity, and key routing and usage constraints are 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?

There is no output schema, so the description properly explains return contents, gaps, contradictions, citation_uri behavior, and timing. It also covers auth tiers, second-hop recovery, source selection, and when to use an alternative. Nothing needed for safe and correct invocation is missing.

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

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

Schema coverage is already 100%, and the description adds meaningful use-level semantics beyond it: question is well-specified for broad/multi-part research and specifically not single lookups, and depth gets behavioral meaning around gap recovery, contradictions, and paid plan requirements. It does not fully re-document each pass count, but the schema already covers that.

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

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

The description states a specific verb and resource: "Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources", explicitly differentiating itself from open-web search. It also names ask_pipeworx as the single-lookup alternative, so an agent can distinguish deep_research from siblings immediately.

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?

Gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, e.g. comparing regulatory and financial exposure. It also gives exclusions: use ask_pipeworx for single lookups, for breaking/non-Pipeworx topics, and when not signed in.

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 known. The description adds valuable behavioral context: it returns top-N most relevant tools with names, descriptions, and full input schemas, and notes that results are ready to call directly without a second schema lookup. It also instructs to call this tool first, which is an important behavioral trait. No contradiction.

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

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

The description is well-structured: it opens with a clear purpose, lists the domains it covers, explains the return format, and gives a usage directive. While it contains a lengthy list of data types and domains, every sentence carries useful information and the structure helps skimming. It earns a 4 rather than 5 due to slight verbosity.

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 meta-tool with no output schema, the description is exceptionally complete. It specifies the input format (natural language), the output format (top-N tools with names, descriptions, full schemas, curated examples), the direct-call readiness, and the recommended usage scenario. This is sufficient for an agent to invoke and interpret results correctly.

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

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

The input schema has 100% coverage with descriptions for all properties, including aliases for the query parameter and limit. The description mentions 'top-N' and natural-language input, but does not add meaning beyond what the schema already provides. Since the schema handles parameter semantics, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb ('find') and identifies the resource (tools) and mode (describing data/task). This distinguishes it from sibling tools, which are domain-specific, while discover_tools is a meta-tool for locating other tools.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies a when-not-to-use (when you already know the specific tool) but doesn't name particular alternatives or exclusions beyond that. Still, the context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is a safe read operation. The description adds useful behavioral context by noting the returned data (start/end timestamps with project and file) and the optional slice_by parameter. However, it does not disclose rate limits, authentication prerequisites, or how errors/missing data are handled.

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

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

The description is a single well-structured sentence that front-loads the purpose and key parameters. It is concise with no redundant words, though splitting into two sentences could slightly improve readability.

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

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

Given 8 parameters and 0% schema description coverage, the description covers only date and slice_by, leaving other optional filters and the required user_id unexplained. The existence of an output schema covers return values, but the parameter semantics gap makes the description incomplete for an agent to use the tool effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the required date parameter with format (YYYY-MM-DD) and the slice_by parameter with possible values (entity/language/branch), but it leaves project, branches, timeout, timezone, user_id, and writes_only unexplained. Even the required user_id is not mentioned, leaving a significant semantic gap.

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

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

The description clearly and specifically states the tool fetches WakaTime coding durations for a single day, including start/end timestamps and project/file data. It distinguishes itself from sibling tools like heartbeats by explicitly focusing on daily durations and optional slicing by entity/language/branch.

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

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

The description implies the intended use case: retrieving daily coding durations with a required date. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or recommended conditions. The single-day scope and required date provide clear context, but no comparative guidance is given.

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 that the data is public, aggregated across all users, and measures relative popularity, which goes beyond the annotations. No contradiction.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning.

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

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

With an output schema present, no parameters, and comprehensive annotations, the description fully covers the tool's scope (public editor usage statistics). There are no missing pieces 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?

The tool has zero parameters, so parameter semantics are not applicable. Per the rubric, 0 parameters receives a baseline of 4.

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

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

The description uses a specific verb ('Fetch') and resource ('WakaTime's public editor usage statistics'), and clarifies the metric ('relative popularity of code editors and IDEs across all WakaTime users'). This clearly distinguishes it from sibling tools like stats or user.

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

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

It clearly indicates the data scope (public editor usage across all WakaTime users), which implies when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Although annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral detail: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists the exact returned fields, notes the patent API sunset with soft-fail behavior, and describes the GDELT-to-GNews fallback. These details go beyond what annotations provide.

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

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

The description is longer than minimal but front-loaded with user-facing examples and the core purpose. Each subsequent sentence adds value (output fields, fallbacks, input requirements) rather than being filler. It is dense but not padded, earning a 4.

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

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

Even with no output schema, the description enumerates the return fields: cik, company_name, recent_filings with URIs, fundamentals (specific fields, sorted), patents, news with fallback, and LEI. It also covers input limitations and caveats like the patent API sunset, making the tool's behavior fully transparent.

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: type has an enum with a note that only 'company' is supported, and value specifies ticker/CIK format and the unsupported name case. The description restates the value parameter guidance but does not add new semantic meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with natural-language examples and clearly states 'full cross-source profile of a US public company in ONE parallel call.' This specifies the action (profiling), resource (US public company), and distinguishes it from siblings like resolve_entity or compare_entities.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns 'names not supported (use resolve_entity first if you only have a name).' This gives both when-to-use and when-not-to-use guidance, including a specific alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to reassert deletion. It adds context about sensitive data and pairing, but doesn't disclose additional behavioral traits like error handling or behavior for missing keys. Given annotation coverage, this is adequate but not rich.

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 with clear action-first phrasing. No filler or repetition. Every sentence contributes to usage understanding, making it efficient and well-structured.

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

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

For a simple one-parameter tool with strong annotations (destructive, idempotent), the description covers purpose and usage sufficiently. It doesn't explain return values or edge cases, but given the tool's simplicity and schema coverage, this is not a significant gap.

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

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

Schema coverage is 100% and the 'key' parameter is clearly described in the schema as 'Memory key to delete'. The description's mention of 'by key' adds no new information beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating the action and target. It also distinguishes itself from siblings by referencing 'remember' and 'recall', making its unique role clear.

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 scenarios (stale context, task done, clearing sensitive data) and mentions pairing with remember and recall, which helps the agent decide between tools. It doesn't explicitly state when not to use it, but for a simple delete operation this is sufficient.

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 that the tool fetches the page, extracts title/description/key links, and outputs a text blob in standard llms.txt markdown, providing useful behavioral context beyond the annotations.

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

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

The description is succinct, front-loaded with the action ('Generate a production-ready llms.txt file'), and uses a clear structure with a use-case list. Every sentence earns its place with no fluff.

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

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

With high schema coverage and annotations, the description provides enough context: process steps, output format, and use cases. It could mention potential network failures or the exact llms.txt specification, but the standard is well-known. Overall complete for the tool's complexity.

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

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

The schema covers both parameters fully (100% coverage), so the baseline is 3. The description adds little beyond the schema, mentioning 'for any URL' (matching the url parameter) and the output format, but not elaborating on max_links.

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

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

The description clearly states the tool generates an llms.txt file for any URL, and explains the process (fetches, extracts, emits). This distinguishes it from sibling tools like ai_visibility_check, which audit AI visibility rather than generate the file.

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 specific use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor') but does not explicitly mention alternatives or when-not-to-use. It gives clear context but lacks exclusions, so it earns a 4.

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, open-world, idempotent, and non-destructive behavior. The description adds nothing beyond that—it does not disclose pagination, default behavior, or any other operational detail. While there is no contradiction, the description fails to add value beyond the annotations, leaving the agent with no additional transparency.

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

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

The description is short, but this is under-specification rather than conciseness. A single noun phrase without a verb or any explanatory context does not earn its place; it fails to provide needed information in a structured way. It is not 'waste-free' but simply inadequate.

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 that this is a read-only data retrieval tool with two parameters and an output schema, the description should at least indicate that it retrieves goals for a user. Instead, it only states 'User's goals' without context on the operation, pagination, or what the results represent. The tool is significantly incomplete for an agent trying to understand its behavior.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter usage. It does not. It only says 'User's goals', which does not clarify the meaning of 'user_id' or the 'page' parameter. No parameter semantics are conveyed beyond what is already evident from the property names, and even those are left entirely implicit.

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 'User's goals' is essentially a noun phrase that restates the tool name 'goals' with a possessive modifier. It does not specify any verb or action (e.g., retrieve, list, create), nor does it distinguish the tool from siblings like 'stats' or 'summaries'. This is a tautology rather than a clear purpose statement.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of contexts, prerequisites, or exclusions. It is a single noun phrase with no operational context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'raw' and 'for a date', but does not disclose additional behavioral details like pagination, rate limits, or return format. It provides modest value beyond the annotations.

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

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

The description is a single concise sentence with no wasted words. It is front-loaded and clear, though it lacks a verb and is somewhat under-specified for full clarity.

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, an output schema, and strong annotations, the description is minimally adequate. However, it omits usage context and parameter semantics, leaving clear gaps for an agent trying to decide when to invoke it.

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

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

Schema description coverage is 0%, and the description only hints at the date parameter without explaining its format or the user_id parameter. The tool has 2 required parameters, and the description fails to compensate for the lack of parameter documentation in the schema.

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

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

The description 'Raw heartbeats for a date' clearly indicates the tool retrieves raw heartbeat data filtered by date. The resource is specific, but it lacks an explicit verb and does not differentiate from sibling tools like durations or summaries beyond the term 'raw'.

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

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

The description provides no guidance on when to use this tool versus alternatives such as durations or summaries. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent to infer usage from the schema.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: 'public' implies no auth, and it discloses filtering/pagination behavior and the return content (ranked users, display names, weekly totals). It does not mention rate limits or potential network behavior, but the annotation coverage plus description is strong.

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, tightly packed sentence with no filler. It front-loads the main purpose and conveys all essential information: resource, filters, pagination, and return type. Every phrase earns its place.

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

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

For a simple read-only leaderboard-fetching tool with an output schema, the description is fully sufficient. It covers the purpose, all parameters (filtering and pagination), and summarizes the return data. The annotations and output schema handle safety and response details, so no critical gaps remain.

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

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

Schema description coverage is 0%, but the description explicitly names 'language', 'country_code', and 'paginate' (which maps to the 'page' parameter), giving high-level semantics for all three parameters. It does not provide formats or allowed values, but it compensates well for the schema's lack of descriptions.

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

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

The description clearly states the action ('Fetch'), the specific resource ('WakaTime's public coding leaderboard'), and includes the scope ('public') and what it returns. This distinguishes it from sibling tools, none of which appear to be leaderboard-related. The verb+resource combination is unambiguous.

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

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

The description provides clear context for use: it is a public leaderboard, and it explains optional filtering and pagination. However, it does not explicitly state when to use this tool versus alternatives or include any exclusions (e.g., 'use X instead for private data'). Given the sibling list has no directly competing leaderboard tool, this is acceptable.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by listing the exact return fields (id, type, params, timestamps, fire_count) and clarifying that only active subscriptions are returned by default, complementing the annotation coverage.

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

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

The description is two concise sentences. The first states the purpose and return fields, the second gives practical usage guidance. Every word earns its place with no redundancy.

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

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

For a simple list tool with one optional parameter, the description covers purpose, output fields, and usage scenarios. It does not address potential error conditions or pagination, but given the minimal parameter surface and strong annotations, it is sufficiently complete.

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

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

The schema for include_inactive is fully self-explanatory, including the default false value. The description's mention of 'active' subscriptions aligns with the schema but does not add new meaning beyond what is already documented, earning the baseline score for full schema coverage.

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

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

The description clearly states it lists the caller's active subscriptions, using the specific verb 'list' and identifying the resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reading existing subscriptions.

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

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

The description provides explicit use cases: reviewing what you're monitoring before adding more subscriptions and finding an id to cancel. While sibling alternatives are not named directly, the context strongly implies when to use this tool versus subscribe/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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the specific behavioral trait that it returns server time and timezones, which is useful context beyond the annotations. It doesn't contradict any annotation.

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

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

The description is a single sentence, front-loaded with the verb 'Fetch', and every phrase serves a purpose—naming the resource, contents, and a concrete use case. There is no redundancy.

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

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

Given the simplicity (0 params), strong annotations, and presence of an output schema, the description is complete. It tells the user what the tool returns and why they might need it, without omitting critical details.

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

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

The tool has zero parameters, and the schema coverage is 100% (since there are no params). Per the rubric, the baseline score is 4; the description doesn't add parameter semantics because none exist.

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

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

The description uses the specific verb 'Fetch' and identifies the resource as 'WakaTime API metadata', explicitly listing the contents (server time, timezones). This clearly distinguishes it from sibling tools like summaries or durations, which are focused on data retrieval rather than metadata.

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 use context: 'useful for validating timezone strings before passing them to summaries or durations.' This indicates when to use the tool, though it doesn't mention when not to use it or alternative tools for metadata retrieval. It names the consumer tools (summaries/durations) as context.

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

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

Annotations provide no safety hints (readOnlyHint false, destructiveHint false), so the description carries the burden. It discloses behavior beyond the schema: filing without an account returns a claim_token and how to use it later, rate limiting ('5 per identifier per day'), free usage with no tool-call quota charge, and that the team reads digests daily. 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 (~180 words) but front-loaded with the main purpose in the first sentence. Every section earns its place (use cases, exclusion, claim_token flow, rate limit); the only mild redundancy is the 'Not sure?' clarification after the 'ONLY for tools served by this Pipeworx connection' sentence. Overall it is 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 having no output schema, the description explains the return behavior (claim_token), the full lifecycle (initial filing and later retrieval), the intended audience (Pipeworx team), and constraints (rate limit, quota). It also addresses alternative routing for non-Pipeworx tools, making it complete for a feedback tool with moderate complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token round-trip flow ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:...})') and by adding content constraints ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') that clarify the message and context parameters beyond their schema descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise), clearly distinguishing this feedback tool from sibling tools by restricting to 'tools served by this Pipeworx connection.'

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 a tool returns wrong/stale data... when a tool you wish existed... when something worked surprisingly well.' It also provides a direct exclusion: if the tool came from a different MCP server, 'file it with that server instead.' Additional guidance includes what to include (describe in terms of Pipeworx tools/packs) and what to avoid (don't paste the end-user's prompt).

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds valuable context: caching window (5min-1h), derived from CF analytics-engine, no PII, and exact output shape (pack, tool, count). This goes beyond annotations and helps the agent set expectations.

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 front-loaded with the core 'what other agents are calling right now', immediately states the return type, then provides the 'useful for' list and behavioral notes. Each sentence earns its place; no redundant fluff. Well-structured for an agent to parse quickly.

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

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

Despite having no output schema, the description explicitly lists return contents (top tools, top packs, total call volume) and mentions the data format '(pack, tool, count)'. It also covers caching, data source, and use cases. For a simple read-only tool with one optional parameter, this is fully complete.

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

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

Input schema already fully describes the single 'window' parameter with enum values and semantics ('Shorter windows... longer windows...'). Tool description largely repeats this without adding new meaning. Since schema coverage is 100%, 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?

Description clearly states the tool returns top tools, top packs, and call volume over a recent window. It distinguishes itself from siblings like discover_tools or stats by focusing on aggregate agent usage trends. The verb 'returns' and specific output items make the purpose unambiguous.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning with agent needs), giving strong contextual guidance. However, it does not explicitly name alternatives or state when not to use this tool versus siblings like discover_tools or stats.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses the exact arbitrage detection logic, the 3pp deviation threshold, the ≥0.30 Jaccard semantic anchor, the placeholder filter (20% threshold), and the fill check behavior with realizable_edge_pp ≤ 0 meaning don't trade. It even explains how to interpret the response fields.

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?

At roughly 300 words, the description is long but heavily structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. The content is dense with necessary technical details, though it could be slightly tightened without losing value.

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

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

This is a complex tool with two modes, no output schema, and several edge-case behaviors. The description covers all of them: mode selection, detection logic, response format, failure conditions (placeholder slugs), fill check integration, and cross-mode alternatives. It even explains the semantic anchor and provides concrete examples, making it fully self-contained.

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

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

The input schema already covers both parameters with 100% coverage, including examples. The description adds further context: event is 'recommended for a specific market' and topic is for cross-event scanning, plus the detailed behavior of each mode (e.g., walks child markets, checks date-axis ordering). This enriches the schema semantics, but the schema already provides solid groundwork.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly distinguishing this from sibling tools like polymarket_edges or polymarket_fill_risk. It further details two distinct operational modes (event vs topic) and a no-arg trending scan.

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 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 also recommends event for a specific market and topic for cross-event scanning, and directs custom sizing to polymarket_fill_risk, naming an alternative tool.

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

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

Annotations already declare read-only and non-destructive behavior, but the description adds significant context: a 1-hour cache keyed on all knobs, a 24h-move warning, Kelly caps, per-sport α values, placeholder-slug filters, and diagnostics for empty segments. It also explains why some signals are soft or unreliable, which goes well beyond the annotation cues.

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 wall of text with no paragraphs or bullet points, making it difficult to scan. Every sentence contains relevant detail, but it is over-specified and does not front-load the most essential information; the core purpose is followed immediately by dense model-family details. It could be significantly restructured to improve readability without losing substance.

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

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

There is no output schema, so the description must explain the response shape. It does this thoroughly: top-level by_segment, fed_candidates/fed_note, _diagnostics with funnel counters, and per-opportunity fields including edge_pp_net, kelly_fraction_half, and liquidity. It also covers why segments may be empty, the caching behavior, and the unreliability of Fed signals. This is complete for a complex tool.

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

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

The input schema has 100% coverage of all 9 parameters with descriptive text, so the baseline is 3. The description adds operational nuance such as how slippage_pp interacts with real market spread, why min_partition_leg_kelly is necessary because parent-level Kelly is always zero, and how the filters drop unrealizable edges. This slightly exceeds the schema's own explanations.

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

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

The description states a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes the tool from siblings by naming three model families and the 'what should I bet on today' use case, making it clearly separate from arbitrage or fill-risk tools.

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

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

It provides clear usage context with 'Built for "what should I bet on today"' and explains when to adjust knobs like slippage and liquidity filters. It also warns about Fed bets being excluded due to unreliable signal. However, it does not explicitly name alternative tools for different use cases, so it lacks the explicit 'when not to use' that would merit a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial beyond that: snapshot TTL (60-day history bound), snapshot gaps due to cache misses, daily-close computation rather than intraday, and the meaning of the response fields. This is exemplary transparency.

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

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

The description is well-structured with 'Args', 'RESPONSE', and 'LIMITS' sections, and it front-loads the core purpose. While somewhat lengthy, every sentence carries useful information—particularly the response semantics—so the length is justified. Not a model of brevity, but cleanly 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?

There is no output schema, so the description takes full responsibility for explaining return values. It details the tracked[], expired[], and snapshot_dates[] arrays, including edge semantics (signed, negative = SELL YES), trend categories, median lifespan as a 'competition clock,' and limitations. With only two optional parameters, this is comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the defaults and briefly labels window as 'snapshot family,' but adds no meaningful semantic beyond what the schema already provides. It does not compensate for any gaps because there are none.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the question 'how long has this edge existed and is it shrinking?' which clearly differentiates it from sibling tools like polymarket_edges (current edges) and 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 strong contextual guidance, contrasting a fresh wide edge with a 3-week-old wide edge to indicate when the tool is valuable. It implies use cases (assessing edge age/decay before trading) but does not explicitly name alternative tools or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond these: it walks the order book ladder, returns specific fields like slippage_pp and a verdict, and warns about partial basket fills converting arbs into directional positions. 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 dense, structured paragraph that front-loads the core purpose and then details modes. While every sentence adds value, the length and single-paragraph format could be improved with line breaks or bullets for readability, but it avoids waste and is efficient for the complexity.

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

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

Despite having no output schema, the description enumerates all significant return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict; theoretical_sum, capture_ratio, thin_legs[], etc.). It also explains failure modes and interpretation, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains how size_usd is interpreted differently in single-market vs basket mode (spend vs target proceeds vs settlement notional), clarifies default behaviors (e.g., side auto for basket), and mentions clamping (10–1,000,000). This enriches the parameter understanding.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly defines two modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation or edge detection.

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

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

Explicit guidance is provided: '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 not capturable on thin books, partial fills create unhedged directional risk), giving clear when-to-use context.

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

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

Beyond the read-only annotations, the description reveals critical behavioral nuances: two distinct conditions for compatibility_warning, the meaning of temporal_alignment when aligned:false, and the semantics of skipped_cross_type/subtype counters. It also discloses that 'the two venues sometimes price the same outcome 2-25pp apart' and that real spreads are rarer than the macro-shortcut list implies. This is far richer behavioral context than 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses examples and semicolon-separated clauses to pack information efficiently. No sentence is redundant; the length is justified by the tool's complexity. However, a more compact layout or bullet lists would improve scannability for an AI agent.

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

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

With no output schema, the description carries the full burden of explaining return values—and it does so by specifying leg-by-leg prices (0-1), matched spread arrays with top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases like non-equivalent bet shapes and temporal misalignment. The tool's 3 optional parameters, two modes, and built-in safety checks are all sufficiently contextualized.

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

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

The schema already provides 100% parameter descriptions, and the description adds conceptual depth: it explains how `topic` auto-fetches matching events, explicitly states that `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped side, and gives concrete examples like 'fed' and 'KXFED-26OCT'. This clarifies parameter interactions beyond what the schema states.

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

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

The opening sentence—'Cross-venue spread between Kalshi and Polymarket for the same resolving question'—states a specific verb-like action (comparing spreads) and a distinct resource (two prediction-market venues). It further clarifies via two operational modes (topic shortcuts vs. explicit tickers) and explains the response fields, making its purpose unmistakable relative to siblings 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 gives explicit 'TWO MODES' usage instructions, using `topic` for pre-mapped shortcuts or supplying explicit tickers for custom pairings. It also includes a strong caution that most pre-mapped topics return compatibility warnings and that 'pre-mapped ≠ tradeable,' guiding when to trust outputs. However, it does not name alternative tools or state when NOT to use this tool, so the guidance lacks direct sibling 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, but the description adds no behavioral context such as data scope, filtering, pagination, or response format. It fails to add any value beyond the structured annotations.

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

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

The description is a single fragment 'User's projects' that is under-specified. While short, it omits crucial information, so it is not effective 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?

Despite having an output schema and annotations, the description is too vague to be useful. The agent is left without understanding what constitutes a 'project' or how to correctly invoke the tool.

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

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

Schema description coverage is 0% and the description does not explain the purpose of 'q' or 'user_id' parameters. The schema only shows types and required status but no semantic meaning.

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 'User's projects' is a noun phrase that restates the tool name without a verb indicating the actual operation (e.g., list, get, retrieve). It does not distinguish this tool from sibling tools like 'commits' or 'durations'.

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 is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds meaningful behavioral context not captured in annotations: scoping to 'anonymous IP, BYO key hash, or account ID' and the dual behavior of retrieving a specific key vs. listing all keys. It does not contradict any annotation.

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

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

Three sentences, each earning its place: the first states the primary action and alternative mode, the second provides use-case context, and the third adds scoping and sibling relationships. The text is front-loaded with the core function and contains no redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers all necessary aspects: what it does, when to use it, scoping, and its relationship to remember/forget. The behaviors for both retrieve and list modes are fully explained, making the tool self-contained.

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

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

The schema already provides 100% coverage for the single 'key' parameter. The description enriches the semantics with concrete usage examples (target ticker, address, research notes) and explicitly describes the omit-to-list behavior, adding value beyond the raw schema description.

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

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

The description opens with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by explicitly referencing remember (save) and forget (delete) as counterparts, establishing recall as the retrieval operation.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also instructs on the two modes (omit key for listing) and names the companion tools remember and forget, making the choice between alternatives 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?

The description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a persistent side effect. However, annotations declare readOnlyHint=true and idempotentHint=true, directly contradicting this behavior. This is a serious inconsistency.

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 compact paragraph with no filler. It front-loads the action and then packs in output description, filtering, state-change behavior, and polling guidance in a way that earns each sentence.

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

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

With no output schema, the description helpfully lists the fields returned (source, citation_uri, raw payload). It also covers polling and the alternative feed URL. It does not explicitly mention the unread_only or limit parameters, but the schema already explains those, so this 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 schema already documents all five parameters (100% coverage), but the description adds valuable context by giving an example type ('sec_8k'), explaining the semantics of mark_read, and noting that since takes an ISO timestamp. This goes beyond the schema.

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

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

The description uses a specific verb ('Pull') and names the resource ('subscription feed'), clearly distinguishing it as an alert-retrieval tool. It also sets expectations about return content and filtering, making the tool's purpose unambiguous.

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

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

It states 'Polls work fine' and describes filtering options, implying usage for recurring checks. It also points to an alternate URL for scripts/dashboards, but it does not explicitly compare itself to sibling tools like list_subscriptions.

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

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

The description discloses extensive behavioral traits beyond annotations: parallel fan-out to multiple APIs, rate-limit fallback logic, an API sunset affecting USPTO, and accepted date formats. It adds context like soft-fail behavior and citation URI returns, which annotations do not cover. No contradiction with readOnly/idempotent hints.

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?

Despite its length, the description is tightly packed with value: examples, fan-out details, fallback logic, return format, and an alternative pointer. Every sentence earns its place, and the structure is logical and front-loaded.

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

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

For a complex tool lacking an output schema, the description fully covers return structure (changes[], total_changes, pipeworx:// URIs), input formats, data sources, fallback behavior, and an alternative. It is remarkably complete for the complexity involved.

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

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

Schema descriptions already cover all parameters with 100% coverage, including type enum, since formats, and value examples. The description reiterates these details without adding new semantic information, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool as a change feed for a company over a time window, with examples like "What's new with X". It explicitly lists the data sources (SEC, GDELT/GNews, USPTO) and distinguishes itself from entity_profile by specifying when to use the alternative.

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

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

It provides explicit usage guidance: when to use this tool for recent changes and when to use entity_profile for static profiles. It also explains fallback behavior (GDELT preferred, GNews on rate limits) and soft-fail conditions, clarifying tool 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds scoping ('scoped by your identifier') and retention details ('persistent memory' vs '24 hours'), which are not in annotations. It does not explicitly state overwrite semantics, but idempotency is already hinted, so the added context is valuable and non-contradictory.

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

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

The description is front-loaded with the core action, then usage condition, storage details, retention, and companion tools. Every sentence contributes distinct information without redundancy or filler. It is dense but well-organized.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, storage semantics, scoping, retention, and relationship to sibling tools. No critical gaps 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% and both key/value have descriptions. The description adds a bit of semantic context ('key-value pair scoped by identifier') and gives examples of keys in the usage text, but it largely restates 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes this from companion tools by naming recall and forget, and gives concrete examples of what to store (ticker, address, preference, research subject). Purpose is unambiguous.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward...' Provides examples of suitable content and names alternatives: 'Pair with recall to retrieve later, forget to delete.' Also explains persistence differences for authenticated vs anonymous sessions, giving clear context for usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes further by explaining internal behavior: the tool 'cascades through several lookup endpoints' and replaces '2-3 manual lookups'. It also discloses graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return') and explicit handling of unresolved identifiers under an 'unresolved' field. This adds significant behavioral context beyond the annotations.

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

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

The description is moderately long but highly informative. It opens with example queries and a clear directive ('Use FIRST'), then organizes details for each entity type in readable paragraphs. Every sentence adds value, though a slightly tighter structure (e.g., bullet lists for types) could improve scannability without losing content.

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

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

For a complex multi-source entity resolution tool with no output schema, the description covers all critical aspects: supported entity types, input formats, identifier sources (EDGAR, GLEIF, OpenFIGI, RxNorm), enrichment degradation, and explicit unresolved reporting. It explains the scope enough for an agent to understand what it returns and how it behaves, despite lacking an explicit 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?

Input schema coverage is 100%, so the baseline is 3. However, the description enriches both parameters: for 'type' it details what each entity source provides (e.g., '10-digit CIK + ticker + company_name from SEC EDGAR' for 'company'). For 'value', it specifies acceptable formats like ISIN-to-LEI mapping and mentions 'unresolved' handling. This goes well beyond the schema's brief descriptions.

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

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

The description clearly identifies a specific verb ('resolve') and resource ('entity identifiers'), listing concrete example queries like 'What's the ticker for…' and 'find the CIK for…'. It covers exactly two entity types ('company' and 'drug') and explicitly contrasts with sibling tools like 'compare_entities' and 'entity_profile', making the scope unambiguous.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also enumerates the input forms accepted ('ticker, CIK, ISIN, or company name') and supported entity types. While it does not list when to avoid this tool or name direct alternatives (e.g., 'search_within' for different lookups), the context is clear enough for an agent to decide.

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

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

Beyond the read-only/idempotent annotations, the description discloses that it probes each entity via ai_visibility_check, implying multiple internal calls, and describes the ranked output with score, confidence, and signal density. This adds useful behavioral context without contradicting annotations.

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

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

The description is three sentences, front-loaded with the primary function, then use case, then return details. Every sentence earns its place with no fluff or repetition, making it highly efficient.

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

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

With no output schema, the description explains the return format (ranked list with score, confidence, signal density), covers purpose and usage context, and references the underlying tool. It provides enough information for an agent to invoke the tool correctly and understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by noting that the first entity is treated as the 'subject' for narrative and the rest are competitors, which is not in the schema. This extra semantic clarifies 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 a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It also distinguishes from the sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, showing a clear scope.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query, indicating when this tool is appropriate. However, it does not explicitly state when not to use it or name an alternative (e.g., ai_visibility_check for single entity), so it lacks that direct contrast.

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

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

Beyond the read-only/idempotent annotations, the description discloses failure behavior (partial failures degrade gracefully), performance (bundlephobia's first measurement can take 5-30s), and that sources_failed will list timeouts. It also clarifies the ecosystem limitation, adding valuable context not implied by 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?

Although longer than a typical description, every sentence adds essential information: purpose, use cases, output fields, failure modes, and ecosystem scope. The structure is front-loaded with the main composite nature and then logically flows to return format and caveats. No redundancy.

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

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

With no output schema, the description fully carries the burden of explaining return values. It explicitly lists the summary block fields, per-advisory details, links, and alternative versions. It also covers partial failure behavior and ecosystem scope, making the tool's behavior and results complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates that 'package' accepts scoped names and 'version' defaults to latest, but does not add new semantic nuance beyond what the schema already provides. No additional elaboration on parameter use or 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's purpose: a composite check for deciding whether to add an npm package, aggregating deps.dev and bundlephobia data. The verb 'scan' and resource 'npm package' are specific, and the description distinguishes it from siblings by detailing the data sources and the question it answers.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions, stating NPM-only in v1 and directing other ecosystems to 'deps.dev:version directly', offering a clear alternative.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals internal mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. It also describes the return format (top-N passages with character offsets and similarity scores), which is essential given there's no output schema. This is transparent and useful.

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

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

The description is four sentences, each adding essential information: what it does, how to use it, when to use it (and alternative), and technical constraints. It's front-loaded with the core purpose and includes no filler. Every clause earns its place, making it appropriately concise yet complete.

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

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

Given there's no output schema, the description fills that gap by specifying what the response contains (passages, offsets, similarity scores). It also covers edge cases (truncation at 200K chars), explains the technical approach, and situates the tool within a larger workflow (pairing with ask_pipeworx_grounded). For a tool with three simple parameters and rich behavioral nuance, this description is fully complete.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds extra meaning by framing 'text' as 'the text you already pulled' and giving examples of sources (SEC 10-K, article, long tool result), plus reinforcing the query as natural-language. This enriches the agent's understanding beyond the schema, especially for the 'text' parameter, though limit is less elaborated.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which precisely identifies the verb, resource, and scope. It clearly distinguishes itself from siblings like ask_pipeworx_grounded by explaining its role as a focused search within already-fetched text, and it describes the output (passages with offsets and scores) so there's no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also explains how it pairs with ask_pipeworx_grounded, giving a concrete workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'), which serves as an alternative/complement path. This is clear, practical usage guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context by enumerating allowed range values and specifying that results include totals and rankings, which goes beyond the structured fields. No contradiction exists.

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

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

The description is a single, front-loaded sentence that efficiently conveys the resource, the range values, and the result structure. Every clause adds meaningful information with no repetition 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?

Given the schema's lack of parameter descriptions, the description covers the core purpose and primary parameter well, but does not address optional parameters. The existence of an output schema reduces the need to explain returns, but overall completeness is moderate for a tool with this complexity.

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

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

Input schema has 0% description coverage, so the description must compensate. It explains the 'range' parameter with valid values and implies 'user_id', but leaves 'project', 'timeout', and 'writes_only' unexplained. This is insufficient for a 5-parameter tool.

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 fetches aggregated WakaTime coding stats for a user, with explicit scope (range values) and output (totals and rankings). This distinguishes it from sibling tools like durations or heartbeats, which focus on raw or granular data.

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

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

The description implies usage for aggregated coding stats over time ranges but does not explicitly mention alternatives or when not to use this tool. Sibling tools like durations or summaries exist, but no differentiation is provided, so guidance is left to inference.

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 a write operation, but the description adds substantial behavioral context: OAuth requirement, email/SMS/webhook delivery specifics, phone verification prerequisite, 10/day SMS cap, webhook auto-disable after 10 failures, and one-time webhook signing secret. These details go well beyond the annotations and are operationally critical.

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

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

The description is dense but every sentence provides unique, essential information—purpose, types, delivery channels, prerequisites, and return values. Front-loaded with the core action, it avoids filler while covering a complex multi-option tool effectively.

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 nested objects, three params, and no output schema, the description covers return values (subscription id, one-time webhook secret), prerequisites, and delivery behaviors comprehensively. However, the 'Supported types' list omits patent_grant and clinical_trial (both present in the schema enum), which could mislead a reader relying solely on the description.

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

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

Even with 100% schema coverage, the description adds deep param meaning through concrete examples: sec_8k item codes, polymarket_edge topic, fred_series series_id, and full delivery channel semantics including HMAC signing and verification rules. This transforms generic schema entries into actionable guidance.

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

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

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

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

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

The description provides clear context: requires a Pipeworx OAuth account, explicitly says anonymous/BYO cannot persist subscriptions, and mentions how to pull the always-on feed via recent_alerts or a GET endpoint. It does not explicitly direct users to list_subscriptions for viewing existing subscriptions or unsubscribe for cancellation, so it stops short of a perfect 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful context about return structure (category-bucketed examples, exact tool+argument shapes) and that it draws from a live catalog, which goes beyond what annotations convey.

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

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

The description is dense but well-structured: it opens with natural language questions, then provides a clear functional definition, return content, usage variants, and explicit positioning. Every sentence contributes value, with no fluff.

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

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

For a tool with one optional parameter and no output schema, the description is fully complete: it explains what it returns (categories, exact tool+argument shape), how to invoke it (no args vs. topic), and when to use it (onboarding, discovering meta-tools). No critical information is missing.

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

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

The schema already documents the `topic` parameter, and description adds concrete examples ('finance', 'pharma', 'betting') plus behavioral details (omit for full spread). This enriches the parameter meaning beyond the schema alone.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by explicitly positioning it as the 'FIRST' tool to use and by naming meta-tools like ask_pipeworx and entity_profile.

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

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

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-argument vs. topic filtered call, giving clear context for when and how to invoke.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, covering the safety profile. The description adds output breakdown context, but does not disclose deeper behavioral traits like timezone handling, request size limits, or how optional parameters affect results. 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, well-structured sentence that front-loads the core function and includes essential details (date range, required params, output composition). No wasted words.

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

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

Given the rich annotations and presumed output schema, the description covers the core purpose and required parameters, but lacks guidance on the many optional parameters and fails to mention alternatives among siblings. Adequate but with clear 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?

With 0% schema description coverage, the description must compensate for parameter meanings. It only explains start/end format and implies user_id, but completely ignores the other 5 optional parameters (project, timeout, branches, timezone, writes_only). This is inadequate for an 8-parameter tool.

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 'Fetch WakaTime daily coding summaries for a user over a date range', which is a specific verb+resource+scope. It distinguishes from siblings like durations or heartbeats by emphasizing 'daily' and 'per-day breakdowns'.

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

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

The description gives clear context on when to use: when daily summaries over a date range are needed, with required start/end parameters and a format hint. It does not explicitly name alternative tools, but the scope is clear enough for selection among 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?

Beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), the description discloses critical behavioral specifics: ownership is enforced, and the row is deactivated rather than deleted, affecting historical event availability. This adds significant value and does not contradict any annotation.

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

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

The description is two sentences long, directly front-loaded with the core action, and every sentence contributes meaningful information about behavior and side effects. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully conveys purpose, constraints, and consequences (deactivation and historical availability). It is self-sufficient for an agent to invoke correctly.

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

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

The schema already fully covers the parameter at 100% description coverage, including that it's a subscription id returned by subscribe. The description's 'by id' adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action (Cancel a subscription) and the resource (by id), which is specific and distinct from sibling tools like subscribe or list_subscriptions. It also explains the deactivation behavior, removing any ambiguity about what 'cancel' means.

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

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

The description provides clear context for when to use this tool, emphasizing ownership enforcement and the soft-delete behavior that preserves history in recent_alerts. It doesn't explicitly name alternative tools for cancellation, but it makes the tool's unique constraints and side effects evident.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety is covered. The word 'Public' adds a small hint that no authentication is needed, but the description does not disclose what happens with invalid IDs, response format, or any other behavior. Minimal added value.

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

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

The description is extremely short, but this is under-specification rather than effective conciseness. It's a fragment that doesn't form a complete sentence and doesn't earn its place by conveying useful information.

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

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

For a tool with one parameter and an output schema, the description is far too terse. It doesn't explain what the tool does, what the output represents, or any edge cases. Despite the output schema existing, the overall purpose is unclear.

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

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

Schema description coverage is 0% and the description does not mention the 'user_id' parameter or its meaning. The schema only provides a generic string type, so the description fails to compensate. There is no guidance on id format, examples, or defaults.

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 'Public profile' is a noun phrase that doesn't state an action. It is nearly a tautology with the title 'User' and doesn't specify that the tool retrieves or fetches a user profile. It doesn't distinguish this tool from siblings like 'current_user' or 'entity_profile'.

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

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

There is no guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or exclusions. The description provides no help for 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 declare readOnly, openWorld, idempotent, non-destructive. The description adds crucial behavioral nuance beyond these: it explicitly explains that 'could_not_verify' means the check did not happen (including verification_error{stage,detail}) and is not evidence for or against the claim, and distinguishes 'unsupported' as 'no coverage'. This failure-mode disclosure is essential for correct interpretation of results.

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

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

The description is longer than typical (~150 words) but well-structured: trigger phrases, usage statement, routing logic, return summary, and caveats. Every sentence adds substance; the only minor redundancy is saying 'natural-language claim verification' after already listing trigger phrases. Overall, it is appropriately sized for the tool's complexity.

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

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

Given the two processing paths, five possible verdicts, and failure semantics, the description covers all critical aspects an agent needs: return value with citation, verdict meanings, and the crucial distinction between could_not_verify and unsupported. Since there is no output schema, the description fully substitutes for it. The context 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?

The schema already covers both parameters with 100% coverage. The description adds significant semantic value: it explains that tolerance_pct 'Overrides the tolerance implied by the claim wording', suggests 1–2 for hallucination detection where any material error must be refuted, and clarifies that the default is impled by wording and capped at 5. This tells the agent when and why to override, which the schema alone does not convey.

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

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

The description clearly identifies the tool as a claim verifier with concrete trigger phrases ('Is it true that…', 'fact check'), specifies the scope (factual correctness of user statements), and distinguishes between company-financial and non-financial claims via distinct processing paths. It also notes that it replaces 4–6 sequential calls, which further differentiates it from 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and then details the two routing paths (SEC/XBRL fast path for company-financial, grounded pipeline for all else). This gives clear context for when to invoke the tool, and the 'replaces 4–6 sequential calls' note signals it should be used as a single-step replacement rather than composing a pipeline.

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