MCP Usage Metering

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 it discloses only the TTL and monotonic fencing token. It never says what happens when a lock is already held (block, fail, or return a token), whether operations are idempotent, what the response contains, or how caller_id, holder_id, and source affect ownership — critical behavior for a concurrency primitive.

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

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

Two compact sentences with the mechanism front-loaded and the namespace note appended; no filler. The colon-embedded action list is slightly compressed but readable, and nothing 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 an 8-parameter mutation-capable lock tool with no annotations and no output schema, the description is thin: it omits per-action parameter requirements, collision/contention behavior, and any sense of what is returned on acquire vs status. A reader cannot confidently invoke renew or release from this text alone.

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% across 8 parameters, so the description must compensate. It mentions TTL and lock name and implies namespace partitioning, but says nothing about idempotency_key, caller_id, holder_id, source, the status action, or the TTL bounds (1-3600s, default 60) and which parameters each action requires.

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 (distributed lease lock) and enumerates the lifecycle operations acquire/renew/release plus the fencing-token mechanism, so an agent knows exactly what the tool is for. It omits the 'status' action present in the enum and gives no explicit contrast with its siblings (spend ledger, usage metering), but the purpose is unmistakable.

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 phrase 'so only one agent does a job at a time' describes why locking exists, not when to choose this tool or which action to invoke. There is no guidance on when to acquire vs renew vs release, no note that renew/release require an existing held lock, and no 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?

With no annotations, the description carries the full burden, and it does disclose real behavior: atomic pre-payment reservation, no overspend under concurrency, idempotency, and namespace-shared state. It omits permission/auth requirements, what happens when a reservation expires (ttl_s), and what an error or insufficient-budget outcome looks like.

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?

Tight and front-loaded: the lifecycle is in the first sentence, with atomicity, idempotency, and namespacing as follow-ups. The final fragment 'Share state by namespace' is telegraphic at the cost of a little clarity, but nothing is padded.

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

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

For an 11-parameter, action-multiplexed tool with no annotations and no output schema, the description should at minimum map actions to their required parameters (e.g., reserve needs amount_micros; settle needs reservation_id) and sketch return values such as a reservation id. Neither is present, leaving the caller to reverse-engineer the call shape from the schema alone.

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% across 11 parameters, so the description must compensate. It maps loosely onto a few of them (budget ceiling, reservation, namespace, idempotency) but never explains limit_micros vs amount_micros, ttl_s, memo, caller_id, source, or reservation_id — and critically never says which parameters are required for which of the five actions.

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 resource (a hosted shared spend ledger) and its lifecycle verbs (set a budget ceiling, reserve, settle, release), so an agent knows exactly what the tool does. It does not differentiate itself from siblings agent_lease_lock or mcp_usage_metering, which look adjacent in purpose, so it stops short of a 5.

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 lifecycle order (set budget → reserve before paying → settle or release) implies when each action applies, which is useful implied guidance. However, there is no explicit when-to-use versus agent_lease_lock, no statement of prerequisites or ordering constraints, and the 'status' action is never mentioned at all.

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 load. It does usefully disclose that this is a '(dry run)' returning a preview, which lowers the perceived risk, but 'Record' implies persistence that the dry-run note partially contradicts, and it says nothing about idempotency-key behavior, auth requirements, or what happens on duplicate keys.

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?

A single front-loaded sentence with no filler; the operation and its return are stated up front. It is arguably too terse for a 10-parameter tool rather than bloated.

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

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

For a 10-parameter tool with a nested metadata object, zero annotation coverage and no output schema, one sentence is far from sufficient. Mentioning the invoice-line-preview return partially compensates for the missing output schema, but the dry-run-vs-persist question and the idempotency contract remain unresolved.

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% across 10 parameters (atomic titles, defaults and patterns only), and the description names none of them. Critical semantics like idempotency_key dedupe behavior, units scaling, unit_price_cents meaning, and the metadata constraints are left entirely undocumented.

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?

Uses a specific verb ('Record') with a specific resource ('metered usage event for any MCP tool call') and states the return ('invoice line preview'). An agent can tell this is a billing/metering write-ish operation versus the sibling ledger and lease tools, though it does not name those siblings explicitly.

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 phrase 'for any MCP tool call' implies the context of use, and '(dry run)' implies a preview-only intent, but there is no explicit when-to-use, when-not-to-use, or comparison against agent_spend_ledger or agent_lease_lock. Guidance must be inferred.

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