SetGet

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

Beyond the annotations (non-read-only, non-idempotent, non-destructive) the description adds genuinely useful behavior: the ID is random, TTL is absolute with a one-hour default, no credentials are issued, and the key is world-modifiable by anyone holding the ID. That last point is a security-relevant trait the annotations cannot express. It does not cover what the response contains beyond the absence of credentials.

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 tight sentences with the key facts front-loaded and no filler. The telegraphic style ("absolute TTL (default one hour)") trades a little readability for density but 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 a simple create tool with no output schema, the description covers creation semantics, TTL behavior, and the security model, which is a solid baseline. However, with zero schema coverage it leaves the required `value` parameter and the content_type choices completely unexplained, so an agent still cannot fully predict the call's effect.

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 carry the parameter burden and largely does not. Only ttl_seconds gets meaning ("absolute TTL, default one hour"); the required `value` parameter and the content_type enum are never explained, and the absolute-vs-sliding distinction is the sole added nuance.

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 ("Create a ... key") plus a differentiating attribute: the key is PUBLIC and the ID is randomly generated, which separates it from put_key (caller-supplied key) and get_key. It stops short of explicitly naming those siblings, so an agent must infer the distinction.

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 explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The warning that "anyone knowing the ID can modify it" hints that put_key or a private key should be used when confidentiality matters, but the agent must draw that conclusion itself.

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 non-idempotent, non-destructive, closed-world behavior; the description adds the meaningful 'why' — atomicity plus 'Never retry blindly', which implicitly warns that a retried decrement double-applies. It does not disclose what happens on underflow when a minimum clamp is set (error vs. saturation) or whether a decrement creates a missing key, so it falls short of full 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?

Two short, front-loaded sentences with no filler; the safety warning is placed at the end where it reads as an imperative. The compressed phrasing ('optional clamps and bounded history') borders on terse but stays parseable.

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 mutating, non-idempotent tool with five parameters, zero schema descriptions, and no output schema. The definition omits clamp edge-case behavior, what a history-enabled call returns, and error conditions — gaps an agent needs before invoking 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 description coverage is 0%, so the description must carry all parameter meaning, and it only gestures at three of five: 'clamps' (minimum/maximum) and 'bounded history' (history). The core 'by' step amount and the 'key' format constraints are never explained, and clamp semantics remain ambiguous.

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 ('Atomically decrement a signed 64-bit counter') plus the optional modifiers (clamps, history). It is clearly distinguishable from the sibling increment_counter by direction, though it never names that sibling 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?

There is no statement of when to choose this over increment_counter or how to handle a missing key. 'Never retry blindly' is a retry caution, not usage routing, so an agent gets no explicit when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: permanence, the 'write access' authorization requirement, and the 404 outcome for missing keys. It stops short of describing what happens on ETag mismatch or whether the deleted value is returned.

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, front-loaded with the destructive action and its condition; every clause carries information (permanence, permission, ETag, 404). Nothing is wasted or redundant.

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

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

For a destructive, two-parameter mutation tool with no output schema, the description covers permanence, auth, and the missing-key case, but omits the conditional-delete failure mode (mismatched ETag) and any note on what the response contains. Adequate but with clear gaps for an irreversible 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 description coverage is 0%, so the description carries the burden. It does identify the second parameter's nature ('optional ETag'), which is more than the bare 'If Match' title, but it never explains the conditional-delete semantics (delete only when the ETag matches) or the key naming pattern, leaving a material 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?

States a specific verb (delete) and resource (key), plus the scope 'permanently' and the optional ETag condition. Among siblings (create_key, get_key, patch_key, put_key) this is unambiguously the removal operation, so an agent can select it 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?

No explicit when-to-use or when-not-to-use guidance; it never contrasts itself with patch_key or put_key, which could also alter a key. The only implicit signal is 'permanently', which hints at irreversibility but is not framed as usage advice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description does add genuinely useful behavior beyond that: fixed bucket counts per resolution, UTC-only timestamps, and inclusive-start/exclusive-end boundary semantics. It stops short of saying what a missing or never-written counter returns.

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 dense sentence with the resource and the window limits front-loaded, and no filler. It is slightly telegraphic – "opted-in" and the parenthetical bucket counts assume prior context – but 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 a four-parameter read tool with a fully documented safety annotation set, the description covers the essential query semantics. The main omission is the return shape (bucket timestamps vs values), which matters more here because there is no output schema, plus the default window when start/end are null.

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%, so the description must carry parameter meaning. It clarifies that start/end are ISO timestamps with start inclusive and end exclusive, and the 168/90/24 bucket counts implicitly map to the resolution enum values. It says nothing about the required key parameter, the default resolution of "hour", or what null start/end mean (presumably a trailing window).

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?

"Read ... history" gives a specific verb plus resource, and the bucket/resolution detail distinguishes it from siblings like get_key or get_metadata. The qualifier "opted-in" is unexplained, so the scope is not fully self-evident, but an agent can still tell this is the time-series read tool.

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

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

There is no statement of when to use this versus get_key, get_metadata, or wait_for_change, nor any precondition such as history being enabled for the key. The agent has to infer usage entirely from the name and the bucket counts.

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=false for what looks like a pure read; the description resolves that apparent conflict by disclosing that a read 'may renew sliding TTL with write access', and it adds a failure behavior ('refuses burn values'). It does not say what happens when the key is absent, so it falls short of a 5.

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 dense sentences with the return payload front-loaded and side effects immediately after; no filler. Terms like 'burn values' and 'sliding TTL' assume domain familiarity, which slightly reduces standalone 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?

There is no output schema, and the description names the return contents (value, metadata, ETag) as well as the TTL side effect, which is enough to call the tool. The not-found / error path is the one meaningful omission for a single-key lookup.

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 was expected to compensate, and it does not — it says nothing about what 'key' means or its format. The schema's own regex pattern supplies the naming constraint, keeping this at a baseline 3 rather than lower.

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 verb 'Read' plus the precise payload ('exact string value, metadata and ETag') tells an agent exactly what the call returns. It is not fully distinguished from the sibling get_metadata, which likely overlaps on the metadata portion, so a 4 rather than 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?

Usage is implied (fetch a stored value) and there is one explicit exclusion — it 'refuses burn values' — but no alternative tool is named for that case, and nothing says when to prefer this over get_metadata or touch_key.

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 the read-only, idempotent, non-destructive safety profile, and the description adds genuinely non-obvious behavior: inspection does not extend TTL and does not trigger single-use 'burn' key consumption. Those are exactly the side effects an agent cannot infer from the schema or 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?

One sentence, front-loaded with the action and then the three non-behaviors, with no filler wording. It is dense but every clause carries distinct information; a brief mention of the returned metadata shape would still be affordable.

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 single-parameter read tool with full safety annotations and no output schema, the description covers the critical semantics well. It leaves the returned metadata fields and the missing-key behavior unexplained, which are the only meaningful gaps remaining.

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 single 'key' property carries only a pattern, no prose, so the burden falls entirely on the description — which says nothing about the key format or that it identifies the entry being inspected. The parameter name is largely self-evident, keeping this at the minimum-viable baseline rather than lower.

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 (Inspect) and resource (metadata and ETag), and immediately scopes what it does NOT do — read values, renew expiry, consume burn keys — which cleanly separates it from get_key and touch_key. An agent can pick this over its siblings 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?

The negative scoping ('without reading values, renewing expiry or consuming burn keys') effectively tells the agent when to choose this instead of a value-returning or TTL-extending call. It falls short of naming the alternative tools explicitly, so the routing is implied rather than 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?

Annotations already declare non-read-only and non-idempotent, but the description adds real context beyond them: 'Atomically' discloses concurrency semantics, and 'Never retry blindly' converts the idempotentHint=false flag into an actionable retry rule. It stops short of saying what happens when a clamp is hit (clamp silently vs. error).

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 plus a short imperative warning — zero filler. The trailing 'Never retry blindly' is slightly disjointed from the main clause but earns its place as the one behavioral caveat.

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 mutating tool with no output schema and no parameter descriptions, the definition leaves key questions open: does it return the new value, is the key auto-created, does hitting a clamp error or saturate, and what does history=true actually record? These are material for correct 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 description coverage is 0%, so the description must carry the burden, and it only partly does: 'optional clamps' maps to minimum/maximum, 'bounded history' maps to history, and 'signed 64-bit' explains the numeric bounds. The 'by' parameter (increment amount, default 1) is never explained, nor is clamp-hit behavior.

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 ('Atomically increment a signed 64-bit counter') plus the optional features it supports (clamps, bounded history), so the agent knows exactly what the operation does. It never names the obvious sibling decrement_counter, so the differentiation is left implicit.

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?

'Never retry blindly' implies the tool is non-idempotent and gives a retry caution, which is genuine guidance. But there is no explicit statement of when to use this versus decrement_counter, or whether a missing key is created implicitly, so usage is only implied.

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 flag destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds substantive behavior beyond that: null members delete, arrays/scalars replace, and an exact quoted ETag is mandatory with no blind retries — effectively disclosing precondition-failure semantics. It stops short of saying what happens on an ETag mismatch or what is returned.

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 short, front-loaded sentences with no filler; the core mechanism and its key caveats come first. The telegraphic style ('No blind retries.') is efficient but borders on cryptic, which keeps it just below the top score.

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

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

For a destructive, non-idempotent mutation with no output schema and zero parameter descriptions, the definition covers merge semantics and concurrency preconditions but omits permission/auth requirements, failure behavior on ETag mismatch, and any notion of the response. Adequate to call correctly in the happy path, incomplete around failure handling.

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%, so the description carries the load. It meaningfully explains the `patch` parameter's merge semantics and clarifies that `if_match` must be an exact quoted ETag, which adds real value over the schema's regex. However, the `key` parameter's namespace/format and the encoding of the patch body are left entirely to 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 mechanism: 'Apply JSON Merge Patch text with an exact quoted ETag', which tells the agent this is a merge-patch mutation rather than a full replace. It does not explicitly distinguish itself from put_key or create_key, but the 'patch' verb plus merge-patch reference is enough for an agent to infer the distinction.

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 'exact quoted ETag' and 'No blind retries' constraints imply usage context (optimistic concurrency; re-read on conflict), but there is no explicit when-to-use-this-vs-put_key guidance and no stated prerequisite for obtaining the ETag. Usage is implied rather than directed.

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=false, destructive=true), the description discloses real operational semantics: existing TTL protection is preserved, an absolute deadline will not be extended, and preconditions guard against lost updates. It does not say what happens to an existing value when no precondition is supplied, nor what a precondition failure returns, which is the remaining behavioral gap for an overwriting write.

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 short sentences, front-loaded with the upsert semantics, and each clause carries distinct information. It is efficiently sized, though the terse phrasing ('Existing protection remains') is compressed to the point of ambiguity for a first-time reader.

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 7-parameter mutating tool with no output schema and no per-parameter documentation, the description covers the most consequential facts (replace semantics, TTL rules, preconditions) but leaves overwrite behavior without preconditions, error modes, and most parameter meanings unexplained.

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 7 parameters, so the description must carry the load. It partly does: it implies the concurrency preconditions (if_match/if_none_match), clarifies that values are UTF-8 text, and explains the absolute-vs-sliding TTL rule that governs ttl_mode/ttl_seconds. It says nothing about the key pattern, content_type, or the special '*' semantic of if_none_match, so several parameters stay opaque.

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 pair and resource: 'Create or replace UTF-8 text', which tells an agent exactly what the write does and that it is an upsert rather than a pure create. It never distinguishes itself from the closest siblings create_key and patch_key, so the agent cannot route between them from this text alone.

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 explicit when-to-use guidance and no mention of the obvious alternatives (create_key for create-only, patch_key for partial updates). The clause 'Preconditions prevent lost updates' hints that if_match/if_none_match should be supplied under concurrency, but the agent must infer the condition and the parameter it maps to.

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?

Goes meaningfully beyond the annotations by disclosing the authorization requirement ('write access'), a hard behavioral ceiling (cannot exceed the existing absolute deadline), and failure semantics for expired keys (no revival). This adds real context beyond readOnlyHint=false and destructiveHint=false. It does not explain the interaction with if_match or what happens on a stale match.

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 short, front-loaded sentences with no filler; the core action comes first and the constraints follow in order of importance.

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?

A mutation tool with no output schema and zero parameter descriptions needs more from the description than two lines. Return values (whether the TTL was renewed, remaining deadline, mismatch behavior) and the semantics of if_match, ttl_mode, and ttl_seconds are all absent, so an agent cannot call this confidently beyond the simplest case.

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 schema description coverage at 0%, four parameters are undocumented in structured fields and the description must compensate. It only hints at ttl_mode/ttl_seconds via 'absolute deadline' and says nothing about 'key' syntax or the purpose of 'if_match' (presumably optimistic concurrency). Most of the parameter surface is left unexplained.

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 ('Renew TTL') plus the operative constraint ('within the existing absolute deadline'). This distinguishes it from siblings like put_key or create_key, which write values rather than lifecycle state, though no sibling is named 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 description implies when it applies by bounding the operation ('within the existing absolute deadline', 'Never revive expired keys'), which effectively tells the agent when the call is a no-op. It never states when to choose touch_key over patch_key or put_key when the goal is to change TTL, so alternatives remain inferred.

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 and idempotency, and the description adds real operational context: a 30-second ceiling, the fact that timing out is expected rather than an error, no replay of missed changes, and a per-IP concurrency cap. The phrase 'no replay or burn values' is cryptic but the rate-limit and timeout semantics are genuinely 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?

Three short sentences, front-loaded with the core behavior, with no filler. The one weak spot is 'no replay or burn values', which reads as internal jargon that an agent cannot act on.

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 should explain what a returned change looks like versus a timeout, and it does not. Combined with three undocumented parameters and no guidance on how `last` interacts with the wait, the definition leaves too much for an agent to infer.

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 explain `key`, `last`, and `timeout` — and it only restates the 30-second bound that the schema already enforces via maximum. The `last` parameter, which appears to be the caller's known prior value and is central to correct invocation, is completely unexplained.

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 verb 'wait' and the notion of a 'visible change' are stated, but the resource is left implicit — the required `key` parameter suggests it watches a key, yet the description never says so. Against siblings like get_key and put_key, an agent can guess this is a blocking variant, but the definition does not make that distinction explicit.

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 notes that a timeout is a normal outcome, which is useful framing, but it never says when to choose this over polling with get_key or when to avoid it. There are no stated prerequisites and no named alternatives among the ten sibling tools.

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