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

No annotations are supplied, so the description carries the full burden and does so: it discloses that archived trees still serve hits, that writes/eviction/reset/freeze return 409 tree_archived, that archived trees cannot be fork parents or promote targets, and that the operation is idempotent, unbilled and audit-logged. It also names both error codes (409 cannot_archive_main, 404 tree_missing) and the auth/tenant scoping requirements.

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 core effect is front-loaded in the first clause, then restore semantics, then exclusions, then side effects. It is a dense run-on block rather than being broken into scannable segments, but essentially every clause carries non-redundant information an agent needs.

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

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

For a two-parameter mutation tool with no annotations and an output schema, the description covers effect, reversibility, side effects on other operations, error modes, auth and tenant scoping. Return values are correctly left to the output schema rather than restated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by specifying the possible prior states an archived=false restore can return to (active or frozen) and by tying tree_id to the "any tree except main" constraint that produces the cannot_archive_main error. It stops short of adding anything not already hinted at in the schema fields.

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

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

States a specific verb and resource ("Archive a cache tree") and immediately defines the scope of the operation: read-only plus hidden from metrecept_list_cache_trees while entries are preserved. It explicitly separates itself from metrecept_freeze_cache_tree and metrecept_delete_cache_tree, so an agent can pick it out of the sibling set without opening a schema.

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 a positive use case ("retire a finished experiment's tree without losing it") and two explicit not-for cases, each paired with the correct alternative sibling. The listing guidance (include_archived=true) and the restore trigger (archived=false) are both stated as conditions for action.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the read-only GET semantics, that the signed receipt stores only a hash of path/query, per-call billing, authentication requirements (METRECEPT_API_KEY / Bearer), tenant scoping, and concrete error behavior (404 service_not_found, JSON {'error','status'} on vendor and prefix failures). This is substantial behavioral context beyond the schema.

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

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

The core action and routing are front-loaded, and nearly every sentence contributes unique information (prerequisite, alternative, path constraint, billing, errors, auth). It is a dense single paragraph with multiple distinct concerns run together, which slightly reduces readability but wastes little text.

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 six parameters, no annotations, full schema coverage, and an output schema, the description provides everything an agent needs: prerequisites, auth model, tenant scoping, billing, path/query constraints, session grouping, and error responses. Return-value shape is appropriately left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful semantics for path (must sit under allowed_path_prefix, with a concrete example), query (sent as the URL query string), and session_id (groups calls into one session receipt). It does not explain service_key beyond the schema, but the cross-parameter prefix constraint and session grouping add real value.

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

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

The description opens with a specific verb and resource ('Make a read-only GET call to a registered third-party API') and states the return ('vendor's response body, with a signed receipt'). It also explicitly distinguishes this tool from the sibling metrecept_fetch_web_pages, so an agent can route correctly without opening either schema.

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

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

It gives explicit when-to-use ('authenticated vendor JSON APIs mid-session'), a prerequisite ('Register the service first with metrecept_register_api_service'), and an explicit when-not-to-use with the alternative named ('Not for public web pages: use metrecept_fetch_web_pages'). This fully covers the routing decision.

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

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

With no annotations, the description carries the full burden and does so well: it discloses exact-repeat caching, metering and receipting, failure JSON shape, API-key requirements for stdio and HTTP, tenant scoping, and that errors include bad model, missing BYOK key, refused fetch, and rate limit.

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 purpose is front-loaded, and most sentences carry actionable information. It is somewhat dense and has minor repetition around purpose/fetch_urls and session/receipt behavior, but it remains readable and efficient.

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

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

For a complex tool with auth, caching, fetch grounding, metering, and session receipts, the description covers the operational prerequisites and error surfaces. An output schema exists, so return-field detail need not be repeated in 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?

Schema coverage is 100%, so baseline is 3; the description adds workflow meaning by saying "mock" is for testing, real model ids come from metrecept_list_models, purpose matters only with fetch_urls, and session_id should be reused across related calls. It adds useful cross-parameter context beyond the schema descriptions.

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

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

The description names a specific verb and resource: sending one user message to a model through the Metrecept gateway and returning reply text. It also distinguishes the tool from metrecept_fetch_web_pages for page content, so an agent can tell what this tool is and is not for.

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 when to use the tool, how to start with model "mock", where to get real model ids, when purpose applies, when to use fetch_urls, and how session_id should span a run. It also names the alternative for page content and points to metrecept_get_fetch_policy for allowed purpose values.

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

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

With no annotations, the description carries the full behavioral burden and does so well: destructive and immediate with no undo, not billed, refuses main and trees with children with specific 409 codes, missing trees return 404, referenced responses are kept until TTL, and the API-key/tenant scoping is explained.

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 front-loaded and every sentence contributes useful guidance. It is longer than strictly necessary, but the length is justified by the operational caveats and error behavior it must disclose.

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?

An output schema exists, so return values need not be explained. The description supplies the constraints, error cases, authentication requirements, and sibling routing needed to invoke this destructive 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% and the only parameter is documented, including the restriction that it can be any tree except main. The description adds no parameter-level detail 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 gives a specific verb and resource: delete a whole non-main cache tree, including its metadata, digest index, references, and owned cached responses. It distinguishes the operation from sibling alternatives such as metrecept_evict_cache_entry and metrecept_list_cache_trees.

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

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

It explicitly states when to use it: cleaning up after an experiment, typically after metrecept_manage_cache_tree promote. It names the alternative for single-entry deletion and points to metrecept_list_cache_trees for finding ids.

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?

No annotations, so the description carries the full burden and does so: it discloses destructive/immediate/no-undo semantics, that the action is not billed but forces a billed miss, ownership/inheritance rules (parent-owned entries untouched, shared-bytes loss after promote), plus the full error set (404, 409, 400) and auth/tenant scoping requirements.

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

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

Front-loaded with purpose and routing before edge-case ownership and error details. Dense but each sentence carries distinct behavioral information; minor redundancy between 'billed as a miss' in the opening and 'not billed' later could be tightened.

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

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

The tool has an output schema, so return values needn't be explained; the description instead covers the non-obvious essentials an agent needs to call it correctly: digest sourcing, tree inheritance, destructive consequences, error codes, and auth scoping. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by naming the digest source and by surfacing the ownership semantics tied to tree_id that the schema only labels 'Cache tree id that holds the entry'. It stops short of adding anything not reinforced elsewhere, but the extra semantic context exceeds the schema baseline.

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

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

States a specific verb ('Evict'), resource ('one cached response') and scope ('in a cache tree by its request digest'), plus the consequence ('fresh miss sent upstream'). It explicitly distinguishes itself from metrecept_delete_cache_tree, so an agent can route correctly without opening schemas.

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 when-to-use ('drop a stale or wrong cached answer'), where to source the digest (metrecept_list_cache_entries), and an explicit when-not with the named alternative (whole tree -> metrecept_delete_cache_tree). Nothing 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?

No annotations exist, so the description carries the full burden and does so substantively: Terms/DPA acceptance required or the call is refused, robots.txt respected fail-closed, PII redacted, login walls and 401/403/402 honoured and never bypassed, never cached, failures return JSON with redacted secrets. It omits how concurrency, retry or per-call failure granularity behaves (partial successes across multiple URLs), which is the main residual gap for a multi-URL fetch.

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

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

Front-loaded with the core action, then a clearly signalled 'Behaviour:' block. Dense but nearly every clause adds operative fact; the auth sentence at the end is somewhat boilerplate relative to the rest, which keeps it just short of 5.

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

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

For a 5-parameter tool with an output schema and no annotations, the description covers what an agent needs before calling: auth mechanism, tenant scoping, compliance refusal conditions, prerequisite policy lookup, and failure shape. Return-value detail is correctly left to the output schema.

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

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

Schema coverage is already 100%, yet the description still adds cross-cutting meaning: it ties session_id to grouping chat/API calls into one receipt, ties purpose to the mandatory get_fetch_policy lookup and its character caps, and characterizes the expected urls volume. That is workflow semantics the schema cannot express.

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

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

States a specific verb and resource ('Fetch public web pages through the Metrecept compliance filter') plus the return shape (redacted markdown or JSON context, metered and receipted). It explicitly distinguishes itself from the two nearest siblings, metrecept_create_chat_completion (model answers grounded in pages) and metrecept_call_api (authenticated JSON APIs).

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 positive selection criteria ('use it when you need the page content itself'), two explicit when-not cases naming the correct alternative for each, and a prerequisite ('call metrecept_get_fetch_policy first to pick a valid purpose'). It also normalizes call shape ('a few URLs per call is the norm'), which prevents an agent from batching too aggressively.

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

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

Annotations are absent, and the description does substantial work: frozen-state semantics (misses served upstream but not stored), which operations break while frozen (eviction 409 tree_frozen, cannot be fork parent or promote target), idempotency, billing, audit logging, auth requirements, and enumerated errors. That is strong disclosure overall, but the tool's actual result payload and how to confirm the new state are left to the output schema.

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

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

Front-loaded with the core action and follow-up routing, followed by behavior, then errors, then auth. Dense but nearly every clause carries distinct information; the auth/tenant sentence is boilerplate that could be trimmed.

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

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

For a two-parameter mutation with no annotations, the description supplies state semantics, side effects on other operations, idempotency, cost, auditability, auth, and a full error enumeration. An agent has everything needed to call it and interpret failures 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 both parameters are already documented, and the description largely restates them ('frozen=false' to unfreeze, any tree but main via the cannot_freeze_main error). The added value is the error-to-parameter mapping, which is useful but modest at this coverage level.

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

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

States a specific verb and resource ('Freeze a cache tree') plus the inverse operation (unfreeze via frozen=false), and immediately distinguishes itself from archive and delete siblings. An agent knows exactly which sibling to pick from the first sentence.

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 a concrete positive use case ('pin a known-good cache, for example a release branch's tree, while experiments continue in forks') and two explicit negative routings to metrecept_archive_cache_tree and metrecept_delete_cache_tree. When/when-not/alternatives are all present.

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

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

With no annotations, the description carries the full behavioral burden and does so: read-only, not billed, tenant-scoped to the calling key, auth via METRECEPT_API_KEY (stdio) or Authorization: Bearer (remote HTTP), and a concrete failure mode (401 JSON error on bad/missing key). That is exactly the safety, cost, auth and error context an agent needs before calling.

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

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

Front-loaded with the purpose and the settings it returns, then usage, then auth. Every sentence is functional, though the final auth/tenant sentence and the inline parentheticals make it denser than strictly necessary for a no-argument read tool.

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

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

An output schema exists, so return-value explanation is not required, and the description covers everything else: what it reads, when to call it, when not to, auth mechanics, tenant scoping and error behavior. Nothing an agent needs to invoke it correctly 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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly adds no redundant parameter talk, instead spending its words on scoping and auth.

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

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

States a concrete verb and resource ('Read the web-fetch compliance policy enforced for this tenant') and enumerates the exact contents: allowed purpose values, robots.txt and PII-redaction settings, Terms/DPA acceptance, per-source and total character caps. It explicitly carves out its boundary against metrecept_call_api, so an agent can distinguish it from fetch_web_pages and call_api without reading either schema.

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 call-site guidance: invoke before metrecept_fetch_web_pages or a create_chat_completion with fetch_urls, or after a refused fetch to diagnose which rule applied. It also states the negative case — 'Not for third-party APIs: metrecept_call_api uses registered services instead' — naming the alternative tool directly.

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

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

With no annotations provided, the description carries the full behavioral burden and does so: read-only, not billed, never cached, 401 JSON on bad/missing key, tenant scoping tied to the API key, and a critical data-trust caveat that avoided-spend figures are list-price estimates while billed figures are exact. That estimate-vs-exact distinction is exactly the kind of context an agent cannot infer from structured 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?

Front-loaded with what the ledger contains, then routing, then caveats, then auth — a sensible order. Every sentence carries information, though the auth sentence is dense and repeats the key concept twice (env var and Bearer), which could be tightened slightly.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still names the headline figures the agent will see. Combined with auth requirements, error behavior, caching/billing semantics, and data-precision caveats, nothing an agent needs to call this correctly 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 tool takes zero parameters, which sets a baseline of 4; there is nothing to document. The description goes slightly beyond by explaining the implicit inputs — the API key (METRECEPT_API_KEY on stdio, Bearer on HTTP) and the tenant scoping it determines — which is genuinely useful given no explicit params 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?

States a specific verb (Read) and resource (tenant's cumulative savings ledger) and enumerates the exact fields returned: cache hit ratio, hit tokens, avoided spend, billed amounts, net saving, ROI. It also positions the tool relative to siblings (money view vs. raw meters vs. per-day meters vs. public receipt), so the agent can pick it without opening a schema.

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 positive routing ("Use it for the money view") and explicit negative routing with named alternatives: metrecept_get_usage for raw meters/plan, metrecept_get_usage_history for per-day meters, metrecept_publish_savings_receipt for public sharing. Both when-to-use and when-not-to-use are covered.

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

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

With no annotations, the description carries the full burden and does so: read-only, no upstream call, not billed, tenant-scoped by API key, and the non-obvious error semantics that an unknown id returns event_count 0 rather than an error. Auth mechanics for both stdio and remote HTTP are spelled out.

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

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

Front-loaded with purpose and payload contents, then usage, then exclusions, then operational facts — a logical order with no filler sentences. It is on the long side for a single-parameter read and the enumerated receipt fields partially duplicate the output schema, costing a point.

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

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

Given a single required parameter plus an output schema, everything an agent needs is present: what comes back in prose, auth requirements, tenant scoping, billing/upstream side effects, and empty-result behavior. Nothing material is left to guesswork.

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 session_id schema description already says it must match the id used on tagged calls, so the description's restatement adds little. It does contribute the useful behavioral note that an unrecognized session_id yields event_count 0, but no format or validation 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?

States a specific verb and resource ('Get one signed, aggregated receipt for a session') and enumerates exactly what it aggregates (chat completions, web fetches, API calls sharing a session_id). It is immediately distinguishable from metrecept_publish_savings_receipt, metrecept_get_usage and metrecept_mint_receipt through explicit exclusions.

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 a concrete trigger ('at the end of an agent run') plus the follow-through action (put verify_url in the PR, ticket or email), and names two alternatives with the conditions that select them: publish_savings_receipt for public snapshots, get_usage for tenant totals. No inference required.

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?

No annotations are provided, so the description carries the full burden — and it does: read-only, not billed, never cached, tenant-scoped by key, and a bad/missing key yields the gateway's 401 JSON error. It also names the auth mechanisms for both stdio (METRECEPT_API_KEY) and remote HTTP (Authorization: Bearer).

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

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

Front-loaded with the core action, then exclusions, then behavioral caveats — a sensible ordering. The meter enumeration in the first sentence is long, but each clause maps to a real returned value, so little is wasted.

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

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

For a zero-param read tool with an output schema, the description covers everything the schema cannot: auth requirements, error behavior, caching and billing semantics, and tenant scoping. No return-value explanation is needed given the output schema exists.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies the tenant and key are implicit context rather than call arguments.

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

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

Opens with a specific verb and resource ('Read the tenant's live lifetime usage meters') and enumerates exactly which meters are returned (requests, cache tokens/ratio, web fetches, API calls, billed USD, plan, billing status, soft cap). An agent can distinguish it from metrecept_get_usage_history or metrecept_get_savings without opening any schema.

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 both a positive trigger ('how much have I used / what plan am I on') and three explicit exclusions, each paired with the sibling to use instead (history for per-day trends, savings for money saved, session_receipt for a single run). Nothing 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?

No annotations are provided, so the description carries the full burden and does: read-only, not billed, sourced from a durable per-day ledger, idle days reported as 0 with nothing estimated, and tenant-scoped. It also states the auth mechanism for both stdio and remote HTTP transports, which is exactly the kind of context annotations would otherwise supply.

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

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

Front-loaded with the core behavior and scoping, followed by exclusions and operational caveats in priority order. The meter enumeration is long but functional; a couple of clauses (upstream cache tokens, custody and statement meters) are dense enough to cost a point on 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?

Return values are covered by the output schema, so the description doesn't need to explain them. It still supplies everything else an agent needs: scope, ordering, ledger semantics, billing status, auth requirements, and sibling routing.

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 single 'days' parameter is fully documented in the schema, including range, default, and clamping behavior. The description reinforces the UTC-day window semantics but adds no detail beyond what the schema already states, so the 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?

States a specific verb (read), resource (tenant's usage meters), and output shape (per-UTC-day series, oldest first, plus window totals), then enumerates the meters covered. An agent can distinguish this from metrecept_get_usage and metrecept_get_savings without opening any schema.

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 positive cases ('trends', 'what did I spend each day') and two explicit exclusions with the named alternative for each (lifetime totals/plan -> get_usage; spend avoided -> get_savings). Nothing 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?

No annotations are provided, so the description carries the whole burden, and it does well: read-only, not billed, live, not paginated, results scoped to the key's tenant, and credentials neither stored nor returned. Its one real gap is the auth requirement, which it does spell out (METRECEPT_API_KEY on stdio, Bearer on remote HTTP), so that is covered too, but it never says what happens on an invalid or missing key, and pagination is only dismissed in passing.

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

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

One dense paragraph, front-loaded with what is listed and what is returned, then the call-site guidance, then the operational facts. Every clause is load-bearing: no repetition of the title and no filler.

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

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

An output schema exists, so return values need no explanation, yet the description still previews the returned fields. Auth, billing, caching/liveness, pagination, tenant scoping and sibling routing are all present, which is more than enough for a zero-parameter read 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 tool takes zero parameters, so the schema cannot add anything and the baseline is a 4. The description adds the relevant scoping fact that results are limited to the calling key's tenant, which is the only semantic detail a parameterless call needs.

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?

Opens with a specific verb+resource ("List the tenant's registered third-party API services") and enumerates what each entry carries (name, base URL, path prefix, auth header name and purpose), so the agent knows exactly what comes back. It is clearly distinguishable from the sibling registration/removal tools it names.

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

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

States an explicit use case ("confirm a service name before metrecept_call_api") and routes the agent to the correct siblings for the adjacent operations: metrecept_register_api_service and metrecept_unregister_api_service. When-to-use and alternatives are both present.

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

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

With no annotations, the description carries the full burden and does so: read-only, not billed, live, metadata-only with an explicit guarantee that prompt/response content is never returned, plus auth mechanics (METRECEPT_API_KEY env vs Bearer) and tenant scoping of results. These are exactly the traits an agent needs before calling a cache-inspection tool.

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

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

Front-loaded with what is returned, then the non-disclosure guarantee, then usage and paging, then auth. Every sentence is actionable; nothing is repeated from the schema beyond what is needed for context.

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

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

An output schema exists so return structure need not be restated, and the description still covers the two things structured fields cannot: the metadata-only privacy guarantee and the auth/tenant scoping model. Pagination and cross-tool workflow are fully specified.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema by explaining the offset/limit relationship as a paging algorithm and clarifying that the digest is the join key to eviction. The tree_id default and semantics are left to the schema, so it is not a full 5.

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?

Opens with a specific verb+resource ("List entries cached in one tree") and immediately enumerates the returned fields (digest, model, token count, byte size, TTL remaining). It is clearly distinguished from siblings by naming metrecept_list_cache_trees as the id source and metrecept_evict_cache_entry as the consumer of the digest.

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 cases (inspect a tree, obtain a digest for eviction) plus the precondition for tree ids and a concrete pagination loop ("offset = previous offset + limit until fewer than limit entries come back"). An agent has no inference left to make about sequencing.

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

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

With no annotations, the description carries the full burden and does so: read-only, not billed, live, single-call complete results, default tree always included, archived hidden by default, and exact auth requirements (METRECEPT_API_KEY on stdio, Bearer on HTTP) plus tenant scoping.

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

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

Front-loaded with purpose, ordering, and return shape before branching into alternatives and auth. Dense but nearly every clause carries information; the auth/tenant sentence could arguably be split or trimmed given it is boilerplate across the family.

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?

An output schema exists so return-value detail is unnecessary, and the description still covers everything an agent needs: what comes back, how it is ordered, what statuses exist, how to get a tree_id, and what not to use it for.

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 goes slightly beyond by stating the observable effect of the flag ("Archived trees are hidden unless include_archived=true"), which frames the parameter as a visibility toggle rather than just a boolean name.

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

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

States a specific verb+resource ("List every cache tree") plus the scope constraint (tenant-owned) and the ordering guarantee (main first, then creation time). The parenthetical "isolated exact-replay namespace" disambiguates what a cache tree is relative to the many other Metrecept resources.

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 routes the agent: "Use it to find a tree_id for the other cache tools," then names exclusions with the correct sibling for each — metrecept_list_cache_entries for contents, metrecept_manage_cache_tree for create/fork/promote, metrecept_delete_cache_tree for removal.

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?

No annotations exist, so the description carries the full burden and does: read-only, static, not billed, BYOK requirement for non-mock models, auth mechanism for both stdio and remote HTTP, and tenant-scoped results. These are exactly the operational facts an agent needs before calling.

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

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

Front-loaded with purpose and immediately followed by usage routing and constraints. The parenthetical vendor enumeration is longer than strictly necessary but does convey which providers are mocked, so it earns most of its space.

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?

Output schema exists, so return shape needn't be explained; the description instead covers the things the schema cannot: routing semantics, BYOK, auth, billing, and tenant scope. Nothing an agent needs to call and interpret this correctly 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 tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. Baseline 4 applies; no parameter-level detail is missing.

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

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

States a specific verb+resource (list model ids) and enumerates the exact payload (routed model ids plus the prefix routing table). It also distinguishes itself from metrecept_list_providers, so an agent can separate the two without opening a schema.

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 sequencing guidance ('use it before metrecept_create_chat_completion to pick a model') plus an explicit exclusion with the correct alternative ('Not for which vendors are actually configured: use metrecept_list_providers'). It also states the forwarding rule for prefixed ids.

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?

No annotations exist, so the description carries the full burden and does so: it discloses that results are read-only, not billed, and live, that key presence is reported without upstream validation and keys are never returned, and that results are tenant-scoped to the calling API key. Auth mechanics for both stdio and remote HTTP transports are spelled out.

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?

Purpose and vendor coverage are front-loaded, followed by usage, the sibling exclusion, the key-handling caveat, and the auth/scoping note. Every sentence contributes a distinct decision-relevant fact, and telegraphic fragments like "Read-only, not billed, live." keep it compact.

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

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

An output schema exists, so return values need not be explained; the description instead covers the things structured fields cannot — auth requirements, tenant scoping, and the fact that keys are not validated. Nothing an agent needs to invoke this correctly 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 tool takes zero parameters, so per the baseline this sits at 4. The description adds useful framing (no filtering is available; output is scoped by the API key's tenant), which is the only semantic surface available for a zero-arg 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?

States a specific verb and resource ("Show which upstream vendors the gateway has configured and ready") and enumerates the concrete vendor set including the OpenAI-compatible case. It also explicitly distinguishes itself from the nearest sibling by declaring it is not for model selection and naming metrecept_list_models.

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 two concrete use cases (debug a failed metrecept_create_chat_completion, verify a vendor is ready) and an explicit exclusion routing the agent to metrecept_list_models for model ids. Both the when and the when-not are present, so no inference is required.

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

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

With no annotations present the description carries the full burden, and it does: copy-on-write parent-chain reads with zero bytes copied, promote adds references rather than swapping trees, the child stays intact, main cannot be promoted, no billing, audit logging, auth requirement (METRECEPT_API_KEY / Bearer) and tenant scoping. It also enumerates failure modes with status codes (409 tree_exists, 409 cannot_promote_main, 409 parent_frozen, etc.).

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?

Purpose and the recommended workflow are front-loaded, and each subsequent sentence carries real information (semantics, error codes, auth). It is dense and runs long as a single block, but nothing is purely redundant with the schema.

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

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

For a multi-action mutation tool with an output schema and no annotations, the description covers semantics, side effects, error surface, auth and tenant scoping — everything an agent needs to invoke it correctly. Return values are legitimately left to the output schema.

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

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

Schema description coverage is 100% and the schema already explains every parameter including action enum and the 'into'/'parent'/'tree_id' interactions, so the baseline applies. The description reinforces behavior ('create and fork give the new tree an empty local index', 'promote ... leaves the child intact') but adds no parameter-level detail the schema lacks.

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?

Names three concrete verbs (create, fork, promote) on a clearly defined resource ('an isolated exact-replay namespace'), and explicitly distinguishes itself from listing and deletion siblings. An agent can select this tool without opening the schema.

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 a concrete workflow ('fork main, send chat calls into the fork, promote it back when good, then remove it with metrecept_delete_cache_tree') plus explicit exclusions routing to metrecept_list_cache_trees, metrecept_delete_cache_tree and metrecept_evict_cache_entry. Both when-to-use and when-not-to-use are stated with named alternatives.

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

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

With no annotations, the description carries the behavioral burden thoroughly: it discloses real gateway calls, per-kind metering behavior, signed Ed25519/JWS output, browser verification against the public key directory, structured error codes, API-key auth requirements, and tenant scoping. These are exactly the operational details an agent needs before invoking a billed mutating-style tool.

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

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

The description is front-loaded with purpose, then usage and exclusions, then billing, verification, errors, and auth. Despite its length, every sentence adds operational value for a multi-kind billed tool, with no filler.

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

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

Given the complexity, no annotations, and an output schema, the description is complete enough: it covers purpose, alternatives, billing, error modes, verification, and authentication/scoping. Return-value details are appropriately left to the output schema while the description still names the key fields.

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

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

Schema coverage is 100%, so the schema already defines both parameters including the kind enum and label. The description adds useful parameter-specific behavior beyond the schema, notably which kinds are metered, how cache_hit is billed, and the api_call no_api_service error condition, though it does not add meaning for every enum value.

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

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

The description states a specific verb and resource: mint one signed Ed25519 receipt of a chosen kind, returning compact JWS with kid, iat, and verify_url. It explicitly distinguishes itself from metrecept_get_session_receipt and metrecept_publish_savings_receipt, so an agent can select it without opening sibling schemas.

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

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

It gives clear use cases: show or test receipt verification end to end, attach a real receipt to a demo or bug report. It also gives explicit exclusions with alternatives for an existing run and a public savings page, plus notes that each kind makes real billed calls.

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

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

With no annotations, the description carries the full burden and does: discloses that it sends transcript and upstream key, that nothing is stored, that it is unbilled by the gateway (returns billed:false, billed_usd 0) while the vendor still bills, that it is audit-logged, and lists specific error codes (400 prewarm_unsupported_model, 400 cache_autopilot_disabled, 401/402).

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

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

Front-loaded with the action and the when-to-use, then progressively less essential details (billing, errors, auth). Dense but nearly every clause carries operational value; only the auth/tenant sentence is slightly redundant given the schema's upstream_api_key note.

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?

Output schema exists, so return values need no explanation; the description nevertheless covers auth (METRECEPT_API_KEY / Bearer), tenant scoping, billing semantics, storage behavior, and enumerated errors — everything an agent needs to invoke and interpret 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 100%, so all four parameters are already documented in the schema. The description restates the claude-prefix constraint on model and the transcript/key-forwarding nature of messages, adding little beyond the schema; baseline 3 is appropriate.

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

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

Opens with a specific verb+resource+mechanism: refresh an about-to-expire Anthropic prompt-cache breakpoint via a one-token call. It also names exactly which caches it does NOT operate on (the gateway's exact-replay cache) and points to the sibling tool for that path.

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 an explicit trigger ('from an idle timer when a long Claude conversation is about to sit past the cache TTL') plus named exclusions: not for the gateway's exact-replay cache (use metrecept_create_chat_completion) and not for OpenAI/other vendors. An agent can decide between it and siblings without 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?

No annotations exist, so the description carries the full burden and does: it discloses the public immutable page, the 90-day lifetime, that only display_name is exposed and never tenant id or key, and that the call is not billed. It also spells out authentication (METRECEPT_API_KEY env on stdio, Bearer on remote HTTP) and tenant scoping.

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

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

Front-loads what the tool produces, then usage, then exclusions, then side effects and auth. Sentences are dense but every one contributes distinct information: no repetition of the title and no filler.

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

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

An output schema exists so return shape needn't be explained; what remains — side effects, retention, privacy exposure, billing, auth, and tenant scoping — is all covered for a one-parameter publish operation.

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

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

Schema coverage is 100% and the single optional parameter is fully documented in the schema, so the baseline is 3. The description adds a modest amount beyond it by stating the receipt 'shows only display_name, never the tenant id or key', which frames the display_name parameter as the sole public identity surface.

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

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

States a specific verb and artifact ('publish a public, shareable savings receipt') and defines it concretely as an immutable Ed25519-signed snapshot at a URL plus a badge snippet. It explicitly distances itself from the two nearest siblings (metrecept_get_savings, metrecept_get_session_receipt), so an agent can route without reading the schema.

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 an explicit trigger ('when the user wants to share savings outside the tenant') plus two named exclusions with the correct alternative for each, including an ordering instruction to call metrecept_get_savings first to review the numbers.

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?

No annotations exist, so the description carries the full burden and does: it discloses the security model (only non-secret shape stored, credential travels per call), idempotency (re-using a name overwrites), input validation (private/internal base URLs rejected), billing ('Not billed'), and auth/tenant scoping requirements. That is unusually complete disclosure for a mutation tool.

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

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

Front-loads what it does and the primary sequencing constraint, then layers security, idempotency, validation, and billing in short clauses. Dense but every sentence adds a distinct fact; the long final sentence on auth/tenant scoping is the only mildly overloaded part.

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 five parameters, no annotations, and an output schema present, this covers everything an agent needs: prerequisite ordering, credential handling, overwrite semantics, validation rejections, cost, and tenant auth. Nothing material is left to inference.

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 still adds real meaning by grouping which fields constitute the stored non-secret shape (base URL, path prefix, auth header name, purpose) and clarifying that the credential is a call-time argument rather than a registration parameter — semantics 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?

States a specific verb pair (register/update) and resource (third-party API service), plus the downstream consumption by metrecept_call_api for 'receipted GET calls'. An agent can distinguish it from unregister/list siblings without reading schemas.

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 sequencing ('once per vendor before metrecept_call_api'), a verification path ('confirm with metrecept_list_api_services'), and the removal alternative ('remove with metrecept_unregister_api_service'). When-to-use and sibling routing are both spelled out.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: destructive and immediate, no undo, no credential loss, 404 error meanings, no billing, authentication requirements, and tenant scoping. These details materially reduce the risk of incorrect invocation.

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 purpose is front-loaded, followed by alternatives, destructive behavior, error semantics, billing, and auth. Despite being fairly long, every sentence provides operational information needed for a safe destructive call.

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 destructive tool with no annotations, one fully documented parameter, and an output schema, the description is complete: it covers purpose, alternatives, destruction semantics, error outcomes, billing, auth, and tenant scope.

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

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

The single name parameter is fully documented in the schema, including its pattern and example. The description adds a useful operational note to verify exact names via metrecept_list_api_services, but does not add syntax or format details beyond the schema, so the baseline score 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 states a specific verb and resource (unregister an API service), names the tenant scope, and explains the resulting effect on metrecept_call_api. It also distinguishes the tool from metrecept_list_api_services and metrecept_register_api_service.

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 when to use it (retiring a vendor integration) and when not to use it (changing settings; re-register instead). It also directs the agent to metrecept_list_api_services to verify exact names before calling.

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