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

Annotations already declare idempotent=true, destructive=false, readOnly=false and openWorld=false, so the safety profile is largely covered. The description usefully adds side-effect scoping ('without changing other notifications') and the pending-state precondition, but says nothing about behavior when the id is unknown or the reminder already fired.

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 well-formed sentence with the action, target, key, and side-effect boundary all front-loaded. No filler, nothing to trim.

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 one-parameter mutation with full annotation coverage and no output schema, the description covers target, key, precondition and non-interference. Only minor gaps remain: source of the id and outcome on unknown/completed reminders.

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% for the single reminder_id property, so the description is the only source of meaning. 'By id' confirms the parameter is an identifier lookup, but it gives no format, no hint about where ids come from (presumably list_reminders), and no behavior for invalid ids.

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 (cancel) and resource (pending personal reminder) plus the keying parameter (id). It implicitly separates itself from create_reminder, list_reminders, and the notification siblings by scoping the target to 'personal reminder' and disclaiming other notifications, though it never names a 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?

The word 'pending' signals the applicable state (only un-fired reminders), which is genuine usage context. But there is no explicit when-not guidance, no mention of what to do for already-delivered reminders, and no routing to alternatives such as snooze_notifications or dismiss_notification.

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 this is not read-only, not idempotent, and not destructive; the description correctly implies a capture that produces a new artifact. It adds useful concrete detail (1280x960 output) and a real behavioral caveat about what low_light does not do, but says nothing about capture latency, blocking behavior, camera permissions, or failure modes.

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 sentences, zero filler. The core action and output format come first, then the single parameter's caveat, which is exactly the right front-loading for a one-parameter 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?

For a one-optional-parameter, no-output-schema capture tool, the description covers the action, the image resolution, and the one parameter's real effect and limits. Nothing an agent needs to call 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?

Schema coverage is 0% - the low_light boolean has no description in the schema - so the description must do the work, and it does: it explains that low_light adjusts exposure and explicitly bounds expectations about IR lamps and night vision. That is a genuine semantic contribution beyond the bare boolean type.

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

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

States a specific verb and resource plus the exact resolution: 'Take and return a new 1280x960 camera photo.' That is far more informative than the bare name, but it never distinguishes itself from the sibling record_camera, leaving the agent to infer that this takes a still while that one records video.

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 statement and no reference to the sibling record_camera. The only guidance is implicit: the low_light caveat ('does not switch the hardware infrared lamps on or prove night vision') tells the agent not to reach for it expecting IR lighting.

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 and idempotentHint=false, so the agent knows this mutates display state; the description adds the key disclosure that it 'replaces screen content,' telling the agent existing display content is overwritten even though destructiveHint is false. It stops short of saying how long the expression persists or what clears it.

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 sentences, zero waste, with the core action and the display-replacement consequence front-loaded. Nothing redundant against the name.

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 no-output-schema mutation tool with annotations already covering safety; the description covers purpose and the main side effect, but omits the undocumented 'intensity' parameter's meaning and any note on persistence. Adequate but with a clear gap for an agent composing calls.

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 parameter meaning. It names emotion and activity (whose enum values are already self-documenting in the schema) but says nothing about 'intensity' — no range, units, or effect — leaving one of three parameters undocumented anywhere.

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 (show) and resource (the configured character) plus the two expressive dimensions (emotion, activity), and clarifies 'without speaking,' which separates it from character_speak. It does not name siblings explicitly, but the implicit contrast is readable.

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 'without speaking' implies when to prefer this over speaking tools, but the description never names character_speak or speak as alternatives, nor states any exclusions or prerequisites. Usage is inferable rather than instructed.

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-readOnly, non-idempotent, non-destructive, closed-world. The description adds real operational context beyond that: playback occurs on physical hardware, the bridge de-duplicates playback when the text appears in the final answer, uncertain playback should not be retried, and text is capped at ~600 chars / 30 seconds. These are meaningful behavioral traits not derivable from the annotations.

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

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

Front-loaded with the core action and device effect, followed by practical constraints and pitfalls in short sentences. Every sentence carries an instruction the agent needs; only minor tightening is possible, such as folding the duplicate-playback note into the 'do not also call speak' line.

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 non-idempotent hardware-mutating tool with no output schema, the description covers side effects, retry policy, and post-call bookkeeping well. Remaining gaps are secondary: `intensity` behavior and what happens when no character is configured or the display Pi is unreachable.

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 has to carry parameter meaning. It adds guidance for `emotion` (match the reply, not the user's feelings), explains that `voice=default` uses the user's saved preference, and constrains `text` to under 600 characters / 30 seconds. `intensity` is never mentioned and the non-default voice options are left entirely to the enum, so the compensation is substantial but not complete.

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 ('Speak as the configured character'), and adds the distinct device-side effects (matching face, animated mouth on the display Pi) that separate it from the plain `speak` sibling. An agent can distinguish it from `speak` and `character_expression` 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?

Explicit alternatives and exclusions are given: 'Do not also call speak for the same reply' and 'Choose emotion to match the reply, not infer the user's feelings.' It also covers post-call behavior ('put the spoken text in the final answer') and a failure policy ('Do not automatically retry uncertain playback'). This is close to a complete routing instruction.

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 mutation (readOnlyHint=false), idempotency, and non-destructiveness, but the description adds the critical context the annotations hide: existing content is discarded and the pending expiry timer is cancelled. That side-effect disclosure is exactly what an agent needs before overwriting a user's screen; only the return/result state is left unstated.

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 sentence with no filler, and the primary action is front-loaded ahead of the secondary timer-cancellation detail.

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 parameterless, annotation-covered tool this covers action and side effect adequately; the only gap is that no output schema exists and the description doesn't say what is returned or what state the display reports afterward.

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; baseline 4 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 concrete verb+resource pair ('Replace screen content with a blank dark canvas') plus the secondary side effect ('cancel its expiry timer'), which clearly distinguishes it from the display_message/display_image siblings. It stops short of naming those siblings explicitly, so differentiation relies on inference.

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 only implied – an agent can infer 'use this to wipe the screen' from the word 'Replace', but there is no explicit when-to-use, when-not, or reference to preview_display/display_image as alternatives.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive behavior, but the description adds meaningful context beyond them: starting replaces the current timer and retries should not be blind. It also notes that completion respects existing notification preferences. It does not contradict annotations.

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

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

The description is short and front-loaded with purpose. Each sentence adds relevant context, though 'Completion uses existing notification preferences' is slightly tangential compared to the more actionable replacement and retry warnings.

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

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

For a simple two-parameter timer tool with annotations and no output schema, the description covers the main behavioral risks: replacement on start, notification preference behavior, and retry caution. The main gap is that it says nothing about the duration parameter, but the schema supplies its name and default.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the meaning of 'start' as replacing the current timer and 'cancel' as stopping the timer, but it does not explain the optional 'minutes' parameter or its 25-minute default, leaving part of the schema undocumented in prose.

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: start/replace or cancel the dashboard focus timer. It clearly distinguishes the two actions and is specific enough that an agent can tell what the tool does 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?

The description implies usage through the start/cancel actions and adds a useful caution ('do not retry blindly'), but it does not explicitly say when to use this tool instead of the sibling get_focus_session or list prerequisites. Usage is mostly implied rather than fully guided.

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 a non-readonly, non-idempotent, open-world operation, and the description adds material context beyond them: it needs opt-in and playback permission, acceptance is not confirmation that audio played, and blind retries of skips are unsafe. The one gap is that it never mentions what the call returns or how to detect failure.

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?

Five short sentences, no filler, with the scope and the permission prerequisite front-loaded before the operational caveats. Every sentence carries distinct information.

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

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

For a side-effecting playback tool with no output schema, it covers the important unknowns: permissions, implicit device targeting, and the unreliability of success signals. The missing piece is what a successful response actually contains and how 'device_id' should be sourced.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it explains that 'uri' selects music (a Spotify URI). 'action' and 'device_id' get no explanation at all, and device targeting is only obliquely implied by 'active Spotify Connect device'.

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 ('Control Spotify') and scopes it to 'an active Spotify Connect device', which cleanly separates it from list_spotify_devices and get_current_media in the sibling list. It does not name the individual actions, but the enum in the schema covers that.

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 real prerequisites ('Explicit opt-in and Spotify playback permission required') and a retry caution, which is more than most. However it never tells the agent how to pick the target device or that list_spotify_devices is the way to obtain a device_id, and it does not state when not to use it.

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

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

Beyond the annotations, the description discloses persistence, the 1–525600 minute range, the default chime behavior, and that delivery is subject to existing notification preferences. It also explains the idempotency mechanism in practical terms: use a unique request_id and reuse it after an uncertain response to avoid duplicates, which adds meaningful operational context not captured by the idempotentHint alone.

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

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

The description is three tight sentences with the core action and limits front-loaded, followed by default behavior and then the request_id idempotency instruction. Every sentence carries useful information without repetition.

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 create tool with annotations and no output schema, the description covers the important behavioral and parameter semantics, including idempotency and delivery constraints. It does not state what the call returns or how the created reminder is referenced afterward, which is a minor gap given the absence of an 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?

With 0% schema description coverage, the description carries the parameter burden well: it defines the minutes range, states the audio default, and specifies the request_id length/charset plus its idempotency role. The text parameter is not described, but its meaning is self-evident.

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

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

The description uses a specific verb and resource ('Schedule a persistent reminder') and adds a concrete time window, making the purpose immediately clear. It does not explicitly name sibling tools like list_reminders or cancel_reminder, but the create action is naturally distinguishable from those.

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 by 'Schedule a persistent reminder' and by the request_id reuse guidance for uncertain responses, but there is no explicit when-to-use versus alternatives guidance or when-not-to-use exclusion. An agent can infer this creates a reminder rather than listing or canceling one, but the definition leaves routing to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context — 'grouped cards dismiss together' — warning that a single dismiss can affect multiple items. It stops short of stating reversibility or what happens with an unknown/stale id.

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 compact sentence, front-loaded with the action and resource, with the grouped-card caveat placed where it is most useful. 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?

The tool is simple and annotations cover the safety profile, but with no output schema and zero schema coverage, the description should say where ids come from and what a dismissal returns or how failures behave. Those gaps are modest but real.

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 the single parameter — it does identify that dismissal is keyed 'by its id', and the grouped-card note adds scope meaning. However, it gives no id format and no hint about where to obtain a valid id, leaving the one parameter only partially explained.

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 ('Dismiss') and resource ('inbox notification/card') plus the key qualifier 'by its id'. It implicitly separates itself from snooze_notifications and get_recent_notifications through the verb, though it never names 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?

Usage is only implied by the verb: an agent can infer 'dismiss reads as removing a notification', but there is no guidance on when to dismiss vs snooze_notifications, or whether the id must come from get_recent_notifications. No exclusions or prerequisites are stated.

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 cover the safety profile (idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: fixed 480x320 rendering, the exact contain-vs-cover visual outcome, and the statefulness of duration 0 meaning "stays until replaced." It omits failure behavior (missing/invalid file, unsupported format) and whether showing an image interrupts other display content.

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?

Four short sentences, each carrying a distinct fact (render size, fit semantics, security boundary, duration semantics), with the core verb and resource front-loaded. Zero 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?

For a 3-parameter, no-output-schema tool, the description covers nearly everything an agent needs to invoke it correctly. The remaining gap is error/edge behavior and the interaction with the other display tools, which matters given siblings like clear_display and preview_display exist.

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 the load and largely does: it defines both enum values of `fit` in visual terms and explains the 0 vs 1–86400 semantics of `duration_seconds`. `path` is only partially specified — "local controller image file" implies controller-side resolution but not absolute vs relative paths or accepted formats.

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 with scope: display a *local* controller image file, resized to 480x320. An agent can immediately tell this is not display_message or speak. It stops short of naming preview_display or clear_display, so the boundary against the preview sibling 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?

"No URL fetching or code execution" is a useful negative constraint that rules out a common wrong call, and the duration rules imply a persistent-vs-temporary usage choice. However, there is no explicit guidance on when to pick this over preview_display or display_message, nor any stated prerequisites such as the file existing on the controller.

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, idempotent and non-destructive, and the description adds real behavioral context beyond them: it destroys/replaces current content, rejects oversized text instead of clipping, and defines the auto-clear window. Return value and failure behavior for oversized text are not described.

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?

Four short sentences, front-loaded with the core action, and each sentence conveys a distinct operational fact. "Short messages work best on 3.5 inches" is the weakest line because it doesn't quantify the limit it implies.

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 mutating display tool with no output schema, the description covers replacement behavior, sizing limits, and persistence semantics. What remains unclear is the theme options and how oversized rejection is surfaced to the caller.

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 parameter meaning; it fully explains duration_seconds but says nothing about theme (three enum values) or title. Roughly half the parameters remain 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?

States a specific verb and resource ("Show readable text on the Pi screen"), which clearly separates it from image-oriented siblings like display_image and clear_display. It never names a sibling explicitly, so differentiation is implicit rather than spelled out.

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 duration semantics (0 = persistent, 1–86400 = auto-clear) and the size constraint imply usage, but there is no explicit when-to-use / when-not guidance versus clear_display, preview_display, or speak. An agent can infer intent but must guess at edge cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context by specifying the transport ('over Bluetooth') and that the target is a preconfigured device, implying a local connection requirement. It does not mention what happens if the bot is out of range or unpaired, which is the main behavioral risk for a Bluetooth read.

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 sentence with no filler, front-loading the verb and the returned data. Every word (battery, firmware, mode, Bluetooth, configured) carries information.

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

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

With no input parameters and no output schema, the description usefully enumerates the fields returned (battery, firmware, mode) so an agent knows what it gets. It stops short of describing the response shape or failure behavior over Bluetooth, which is the only remaining gap for such a simple 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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies the target is implicitly 'the configured' device rather than something passed in.

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 a specific resource ('the configured SwitchBot's battery, firmware and mode'), which lets an agent distinguish it from get_device_health or get_display_status. It does not explicitly name which sibling to prefer for a general device check, so it falls 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?

Usage is only implied: it reads status of 'the configured' SwitchBot, suggesting it applies to the paired bot rather than an arbitrary device. There is no explicit when-to-use vs. when-not guidance and no mention of alternatives such as get_device_health.

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

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

Annotations already declare readOnlyHint=true; the description reinforces this by clarifying that events are not consumed and adds genuinely new facts: a 100-event retention buffer, ID reset on session change, and the push-to-talk side effect of holding the button. It does not describe the shape of returned events, which matters since there is no 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?

Three front-loaded sentences; the cursor semantics come first and the retention limit and bridge side effect follow. The final sentence about push-to-talk is slightly tangential to a read tool but earns its place as context for what the events mean.

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

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

With no output schema, the description should ideally indicate what an event record contains; that is the main omission. Everything else an agent needs — cursor behavior, buffer limit, reset condition — is present.

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

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

The single parameter has 0% schema description coverage, so the description must carry it, and it does: it explains after_id is an exclusive cursor that survives between calls and that polling must restart at 0 after a session change. It never spells out the integer semantics of a default of 0 beyond that, but the meaning is clear.

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 ('Read button press/release events') plus a key scope qualifier ('without consuming them'), which is exactly the distinction an agent needs. It is clearly separated from mutation-style siblings like press_bot.

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 concrete polling instructions: read after an ID, and restart from after_id=0 when IDs reset on session_id change. It stops short of naming an alternative sibling or saying explicitly when not to use it, but the operational context is clear.

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

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

Goes well beyond the readOnly/openWorld annotations: it discloses the caching path, that results include all-day and already-started events, that recurrences are expanded, that end_date is exclusive, and flags event text as untrusted data (a prompt-injection warning). These are exactly the traits an agent could not 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?

Three short sentences, front-loaded with the core action and no filler. The compressed phrasing ('Today/tomorrow uses a fast timed-event cache') is dense but readable; a little more spacing between the mode rules would help.

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 parameterless-required, read-only tool with no output schema, this covers modes, format, inclusivity, recurrence, caching, empty-result handling and safety warnings. The remaining hole is sibling disambiguation against show_calendar_agenda and any hint of the returned shape.

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

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

With 0% schema coverage the description carries the whole load and mostly does: it defines the day enum's meaning, the ISO YYYY-MM-DD format, the exclusivity of end_date, and a 366-day span cap. It omits precedence rules when day and dates conflict and whether start_date alone is valid.

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 existing calendar feed' — which is unambiguous about what the tool returns. It does not, however, distinguish itself from the sibling show_calendar_agenda, so an agent must guess which one renders vs. retrieves the agenda.

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 real usage conditions for the two modes (today/tomorrow via fast cache vs. explicit date range) and warns to 'check available before interpreting an empty result', which is actionable. But it never states when to pick this over show_calendar_agenda, nor what to do if both day and start/end_date are supplied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The added phrase 'No automatic content classification' is ambiguous and does not clearly explain what the tool does or does not do beyond that vague constraint.

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 definition is very short and front-loads the list operation. The second sentence is cryptic but does not add excessive length.

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-parameter, read-only listing tool, the description is minimally adequate. However, it does not explain what slots or presets contain, lacks usage context, and there is no output schema to fill that gap.

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

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

The tool has zero parameters, so schema semantics are minimal and the baseline score of 4 applies. No parameter explanation is needed.

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 clear verb, 'List,' and a specific resource, 'content reaction slots and presets.' It distinguishes itself from most siblings by resource, though it does not explicitly differentiate from related tools like set_content_context.

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

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

The description gives no explicit when-to-use guidance or alternatives. 'No automatic content classification' reads as a caveat rather than a usage rule, and it does not tell the agent when this tool should be selected over siblings.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: that returned metadata is untrusted and that absent titles or playback state do not prove nothing is playing — a non-obvious nullability/false-negative caveat.

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

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

Two sentences, zero waste, with the resource and the interpretation caveat front-loaded. Everything stated is actionable or prevents a plausible misread of the result.

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

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

No output schema exists, so the description bears the burden of conveying return shape. It names 'metadata and parser context' and warns about missing values, but doesn't sketch what fields to expect (title, artist, album, playback state, source/app), leaving the agent to discover this empirically.

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?

Zero parameters, so the baseline is 4. There is nothing parameter-level for the description to clarify beyond the schema's empty contract.

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: read current TV/music metadata plus parser context. It's clearly a read-only query distinct from the mutation-oriented siblings (control_spotify, play_audio, speak), though it never names those alternatives 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 word 'Read' and the caveat about interpreting missing data imply usage, but there is no explicit when-to-use or when-not, and no pointer to control_spotify for changing playback. The agent must infer routing from the -control vs -read naming.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'without actuation' largely restates structured data, though it usefully reinforces that no state changes occur. 'Controller-observed' adds genuine value by disclosing the data source and implying the health is an indirect, upstream view rather than a local probe. It says nothing about freshness, latency, or failure reporting, which matters for a health-check 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?

A single front-loaded sentence covering the action, the data source, the scope, and the non-mutating guarantee. No filler, no repetition of the tool name.

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

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

With no parameters and no output schema, the description carries the burden of conveying return content, and 'hardware, speech and integration health' only sketches the categories. The agent gets no sense of what a degraded result looks like or how to interpret it, and no routing guidance relative to the several subsystem-status siblings.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies: the absence of arguments is fully consistent with the schema.

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

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

The description gives a specific verb ('Read') and a well-scoped resource ('controller-observed hardware, speech and integration health'), so the agent knows exactly what data the tool returns. It does not name sibling tools such as get_voice_status or get_bot_status that cover overlapping health domains, so differentiation is implied rather than stated.

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, no exclusions, and no pointer to alternatives. Given siblings like get_voice_status, get_bot_status and get_display_status that report overlapping subsystem status, the agent must guess whether this is the aggregate health check or whether the narrower tools are preferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful reassurance that the screen is not changed and scopes the read to metadata and dimensions, but does not add details about permissions, response shape, or edge cases.

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 definition is a single front-loaded sentence with no wasted words. Each phrase contributes to purpose, scope, or safety.

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 no-parameter, read-only status tool with annotations covering safety, the description is nearly complete. It could specify the returned metadata or dimensions more precisely, but no output schema exists and the current wording is sufficient 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?

There are zero parameters, so parameter semantics are not a meaningful burden. The description appropriately avoids inventing parameter details and simply describes what the tool reads.

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: read current display metadata and dimensions. It clearly distinguishes this read-only status tool from display-mutating siblings such as display_message, display_image, and clear_display.

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 a clear usage context: read display metadata and dimensions without changing the screen. It does not explicitly name alternatives or when-not-to-use cases, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The phrase 'shared with the dashboard' adds a small hint about the data source, but nothing about what happens when no session is active or what state fields are 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?

A single, front-loaded sentence with no wasted words. It is arguably too terse rather than too long, which is a completeness issue rather than a structure one.

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

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

With no output schema, the description carries the burden of telling the agent what a returned 'focus session' looks like (remaining time, running/paused state, label), and it does not. For a simple zero-param read the gap is modest but real.

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 and the schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 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 states a specific verb ('Read') and a specific resource ('the current focus timer'), which is unambiguous. It does not explicitly name the sibling `control_focus_session` as the mutating counterpart, so differentiation is implied rather than stated.

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

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

There is no guidance on when to call this versus `control_focus_session` (which presumably starts/stops/pauses the timer), nor any mention of prerequisites or whether the timer may be absent. Usage is only inferable from the read-only framing.

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

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

Annotations already establish this as a read-only, non-open-world operation. The description adds valuable behavioral context: the result is capped at 30 records, it is only a recent window, notification text is untrusted, and dismissal is a separate action.

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

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

Three sentences, front-loaded with the core operation and then adding the safety warning and scope limitation. Every sentence contributes useful information without repetition.

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

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

For a simple read-only tool with annotation safety coverage, the description supplies the key scope, cap, filter mention, and untrusted-data warning. It remains slightly incomplete on source/status value semantics, but no output schema is present to require return-value explanation.

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 parameter meaning. It mentions all three parameters indirectly and adds the important cap of 30 for limit, but it does not define valid source or status values, nor does it explain filtering semantics beyond naming the 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?

The description gives a specific verb and resource: read recent inbox records, with an explicit 30-record cap and optional source/status filtering. It also distinguishes the tool from dismissal operations by stating that dismissing is separate.

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

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

It clearly frames the tool as a recent window and explicitly warns that it is not a complete historical audit. It also names the boundary with dismissal, though it does not name a specific alternative tool for full-history retrieval.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description contributes the useful detail that the read returns four distinct data items, but says nothing about freshness, whether values are cached, or what an empty result looks like. Given annotation coverage, a 3 is appropriate.

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

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

One sentence, front-loaded with the verb and then the returned data, with zero filler. Nothing could be removed without losing information.

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

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

With no output schema, the description carries the burden of explaining returns, and it names all four returned values. It stops short of describing formats (e.g., what a 'session ID' looks like or how 'recent events' are bounded), which is a minor gap for a zero-argument status reader.

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; baseline 4 applies. The field enumeration is about output, not parameters, and does not conflict with the empty 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?

A specific verb ('Read') plus an enumerated set of resources (button state, session ID, recent events, audio busy flag) makes the tool's output scope unambiguous. It partially distinguishes itself from siblings like get_button_events and get_device_health by naming the fields, but never explicitly says how it differs from those overlapping readers.

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

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

The description gives no indication of when an agent should call this versus get_button_events, get_device_health, or get_bot_status, and states no prerequisites or exclusions. Usage must be inferred entirely from the field list.

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

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

Annotations already establish that this is a read-only, non-open-world operation. The description adds useful detail that the result consists of three locally installed presets plus the saved default, though it does not describe the response format or any ordering guarantees.

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 definition is a single front-loaded sentence with no redundant or wasted wording. It communicates the core result efficiently.

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

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

For a zero-parameter, read-only listing tool whose safety profile is already covered by annotations, the description supplies enough detail about what will be listed. No additional parameter or output-schema explanation is necessary.

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?

There are zero parameters, so the schema has nothing to document. The description correctly does not invent parameters and focuses on what the no-argument call will return.

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

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

The description uses a clear verb and resource: list the character's locally installed voice presets and saved default. It is specific about scope and count, but it does not explicitly differentiate itself from nearby siblings such as set_character_voice or get_voice_status.

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 listing intent implies this tool is used when the agent needs to discover available voice presets or the current default before switching or inspecting voices. However, no explicit when-to-use guidance or alternative-tool comparison is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral fact that playback is not triggered, preventing a plausible misread; it says nothing about return contents, but that is a minor residual gap given the annotation coverage.

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

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

A single clause pair with zero filler, and the core purpose is front-loaded before the clarifying negation.

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 parameterless read-only list tool with no output schema, the description covers purpose and the key behavioral caveat. It could note roughly what the returned entries look like (e.g., names/IDs) since no output schema exists, which is the only real gap.

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

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

Zero parameters, so the baseline of 4 applies; there is no parameter detail needed. The description correctly adds none, wasting no space on param semantics.

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

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

States a specific verb ('List') and resource ('configured explicit Echo speech destinations'), and adds a negating clause ('does not play audio') that separates it from audio-playing siblings like speak or speak_on_echo. An agent can identify 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?

The 'does not play audio' clause implies when not to use it relative to speak/play_audio siblings, but no alternative is named explicitly and no positive context (e.g., 'use before speak_on_echo to discover destinations') is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context beyond that: results are filtered to pending items, ordered by due date, and capped at 100 — the cap being the closest thing to a rate/result limit disclosure. It stops short of saying what happens when more than 100 reminders are pending (truncation vs. pagination).

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 short sentence, front-loaded with the verb and resource, then the scoping constraints. Every clause (pending, personal, 100, due order) carries information; nothing is 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 zero-parameter read tool with readOnly annotations and no output schema, this covers the essentials. The only gap is behavior at the 100-item boundary and whether completed/dismissed reminders are ever included, which an agent might want to know.

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 and there is nothing for the description to compensate for. The schema is trivially complete.

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?

Specific verb (List) plus resource (personal reminders), with meaningful qualifiers: 'pending', capped at 100, in 'due order'. It is naturally distinguishable from the write-oriented siblings create_reminder and cancel_reminder, though it never names them 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?

Usage is implied by 'pending personal reminders' — the agent knows this is the read path for reminders — but there is no explicit when-to-use/when-not guidance or pointer to create_reminder/cancel_reminder for the mutation cases.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the bar is lower, and the description still adds real value: it clarifies no audio session is created and that an empty result is not proof the TV is offline because the device may not advertise Spotify. That is a non-obvious failure-mode caveat an agent would otherwise misread. It omits auth/credential or enumeration-timing details, so not 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 short sentences, no filler. The scope is front-loaded and the interpretive caveat about the empty list follows immediately as the single most important secondary fact.

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

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

No output schema and no parameters, so the description carries the burden for return semantics, and it addresses the one trap that matters (empty list ≠ offline). It could have sketched what a discovered target looks like, but for a zero-argument read tool this is close to sufficient.

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 is the baseline-4 case; there are no arguments whose meaning could be lost. The description correctly does not waste words restating the empty 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?

Uses a concrete verb ('Discover') plus a specific resource ('current Spotify Connect targets') and rules out the adjacent write behaviours (starting or transferring audio), which separates it from control_spotify. It stops short of naming that sibling, so an agent must infer the pairing rather than being told directly.

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 'without starting or transferring audio' clause implies this is the read-only inspection call and that playback should go through a sibling, but no explicit when-to-use or when-not-to-use condition or alternative tool is named. Usage is inferable rather than stated.

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 annotations provided, the description adds useful behavioral context beyond the safety flags: it discloses the 30-second maximum, local-only file behavior, and platform-specific conversion via afconvert or ffmpeg. It does not explain failure behavior for oversized files or unsupported formats, but it adds meaningful operational detail.

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

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

The description is short and front-loaded with the primary action and constraint. The platform conversion detail and local-only warning are compact and relevant, with no wasted sentences.

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

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

For a simple one-parameter playback tool with annotations and no output schema, the description covers the essential constraints: local file, speaker target, duration limit, and no remote fetching. It is mostly complete, though the path parameter could be described more precisely.

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

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

The single path parameter has 0% schema description coverage, so the description must compensate. It clarifies that the file is a local controller audio file and that remote URLs are not fetched, but it does not specify path format, expected location, or supported audio formats.

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: playing a local controller audio file on the AIY speaker, with a 30-second limit. It is clear about what the tool does, but it does not explicitly contrast itself with sibling tools such as speak or speak_on_echo.

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

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

The description gives implied usage constraints: the file must be local, no remote URLs are fetched, and playback is capped at 30 seconds. However, it does not explicitly say when to use this instead of speak, speak_on_echo, or other audio-related siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds meaning annotations cannot: 'Confirmed means the Bot acknowledged actuation, not that an appliance changed state' clarifies the success signal, and the reuse rule explains the idempotency semantics in practice. It does not cover latency, failure modes, or what a non-confirmed response looks like, so not a full 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?

Three short sentences, front-loaded with the action, then the ID rule, then the confirmation caveat. Nothing redundant and nothing buried.

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, no-output-schema actuation tool, the description supplies the parameter contract and the interpretation of a confirmation, which is the main thing an agent could misread. Return shape beyond 'confirmed' and any precondition (e.g. Bot must be online) remain unspecified.

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 — and it does, specifying the ID's character set and 8–100 length plus the retry semantics ('always reuse that ID'). It omits whether deduplication is time-windowed or server-persistent, which is the one remaining semantic gap for a request_id.

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 with scope: 'Physically press the Bot ONCE.' The word 'physically' plus 'ONCE' clearly separates it from read-only siblings like get_bot_status or get_button_events, which report on the Bot rather than actuate it.

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 strong invocation rules: one press per call, a per-intent ID, and explicitly what to do when the outcome is unknown (reuse the same ID rather than re-press). It never names a sibling alternative or says when not to use it, so it stops short of the 5 bar.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the meaningful detail that the result is a rendered-canvas snapshot rather than a hardware camera image. It does not mention image format, resolution, or whether the canvas reflects pending draws, which would be a nice addition but is not critical.

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

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

A single semicolon-joined sentence with the primary action front-loaded and the disambiguation second — 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?

For a zero-parameter, read-only tool with no output schema, the description adequately conveys what comes back (an image of the rendered canvas) and what does not (a camera view). Minor gaps remain around image format/size, but nothing blocks 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 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 and resource ('return the current rendered canvas as an image') and immediately distinguishes itself from the camera-oriented siblings (record_camera, capture_camera) with 'not a camera view of the LCD'.

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 exclusion clause tells the agent when not to use this tool (i.e. when a physical camera capture is wanted), which implicitly routes to the camera tools. It lacks an explicit positive 'use when you want to see what is currently on the display' framing, but the context is clear.

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

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

Beyond the annotations (idempotent, non-destructive, closed-world), the description discloses three things they cannot: the delivery precondition (a running controller), the delivery behavior tied to priority (important/urgent may be spoken when idle), and a prompt-injection safety contract that notification text must never be treated as instructions. It stops short of saying whether queued cards persist, expire, or return a handle for later dismiss/snooze.

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?

Four short sentences, front-loaded with the action, with the safety caveat and precondition placed after the core statement. Almost no waste, though the sentence fragments read slightly telegraphic.

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

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

No output schema exists, so the description should at least hint at what comes back (an id usable with dismiss_notification/snooze_notifications) and it does not. The safety, idempotency and controller-precondition coverage is good for a mutation tool, but the five undocumented parameters and the missing return/expiry story leave real gaps.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the burden and it explains only two: dedupe_key (reuse to avoid duplicates) and priority (important/urgent may be spoken when idle). source, body, audio, group_key and group_title receive no meaning at all, leaving the grouping semantics and the audio enum entirely 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 (queue a notification card) and adds that it is presented by the character, which separates it from display_message and from the read/manage siblings get_recent_notifications, dismiss_notification and snooze_notifications. It does not explicitly call out those siblings, so differentiation is inferential rather than stated.

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?

"Reuse a dedupe_key to avoid duplicates" and "Requires a running controller to deliver" are useful preconditions, but there is no explicit when-to-use-this-instead guidance against siblings like dismiss_notification, snooze_notifications or display_message. Usage is implied rather than routed.

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, the description discloses key behavior: the recording length range, output format, where the file is saved, and the fact that no transcription is performed. It does not specify whether repeated calls create separate files or how filenames are chosen, but the annotations already establish the non-read-only, non-destructive, non-idempotent profile.

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

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

The description is two compact sentences with the core action front-loaded. Every clause adds useful information: duration bounds, audio format, save location, return value, and transcription behavior.

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

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

Given the lack of an output schema, the description usefully explains what is returned: an absolute path to the saved WAV file. It covers the main behavior an agent needs, though file naming and overwrite behavior are left unspecified.

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 for the single duration_seconds parameter. It supplies the critical range of 1–20 seconds, though it does not explicitly name duration_seconds or mention the default value of 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?

The description states a specific verb and resource: record the Voice-kit microphone. It also specifies important scope details (1–20 seconds, mono 16kHz WAV, saved on the controller) and distinguishes the output from transcription-focused siblings by saying there is no automatic transcription.

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 by the clear action and duration constraint, but there is no explicit guidance about when to choose record_audio instead of record_camera, capture_camera, or other audio-related siblings. The 'No automatic transcription' note clarifies expectations but does not route the agent among 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?

Adds real context beyond the annotations: repeating the call creates a NEW clip (consistent with idempotentHint=false), there is no continuous background recording, output is an absolute local path, the clip is silent, and low_light means 10 fps with night exposure rather than software-controlled IR. Only the lack of failure/permission behavior keeps it below 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?

Four short sentences, front-loaded with the core action and format, then constraints, then mode semantics. Every sentence adds information; the line break placement is slightly awkward 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 two-parameter, annotation-backed tool with no output schema, it covers duration limits, mode behavior, non-continuous behavior, and return value (absolute local path). Only inter-tool routing against capture_camera 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?

With 0% schema description coverage the description carries the load and does it well: it gives the 1–20 second duration bound the schema lacks and defines low_light as 10 fps plus night exposure with no IR illumination. Both parameters gain meaning not present in the schema.

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

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

States a specific verb and resource plus format detail: 'Record a new silent 720p MP4 for 1–20 seconds and save it on the controller.' An agent can tell this is a video-recording action distinct from audio capture, though the sibling capture_camera is never named to make the boundary 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?

It explains mode choice (normal vs low_light) and excludes continuous background recording, which is useful guidance. But it never states when to use this tool versus capture_camera or record_audio, so selection between siblings is left to inference.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description usefully adds that it saves the default voice and does not play a sample, which prevents confusion with speak/play_audio. It does not describe overwrite behavior or whether the setting persists across sessions, but the key behavioral distinction is covered.

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

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

The description is two short sentences with no wasted words. The core action is front-loaded, and the non-playback clarification is concise and useful.

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

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

For a simple one-parameter setter with annotations and no output schema, the description covers the main action and an important behavioral distinction. The notable gap is parameter semantics and any explicit relationship to sibling tools for listing voices or checking current voice status.

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 should compensate by explaining the required voice parameter. It does not mention the parameter name, the allowed enum values, or what each voice choice means. The schema enum lists valid values, but the description adds little semantic guidance.

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

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

The description states a specific verb and resource: saving the character's default voice. It also distinguishes this setter from playback tools by saying it does not play a sample. It does not explicitly contrast with list_character_voices or get_voice_status, so it falls short of full sibling differentiation.

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 'when the user chooses one' gives an implied trigger for using the tool. However, it does not explicitly say when not to use it or point to alternatives such as list_character_voices for discovering valid voices.

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 consumer ('read by the running controller') and a lifecycle limit ('expires after four hours'), plus an explicit scope exclusion ('does not infer scene events/goals'). With idempotentHint/destructiveHint already given, this is solid added context; only the failure behavior for unverified IDs is missing.

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 action, then parameter guidance, then runtime behavior. No filler and no repetition of 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?

With no output schema, the description covers the important runtime facts (who reads the data, four-hour expiry) and scope limits. It is nearly complete for a write tool; the remaining gap is that valid keys inside the free-form 'context' object are only illustrated, not 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 0% and the nested 'context' object is additionalProperties:true with no property docs, so the description must compensate. It does partially, naming likely context keys (genres, format, sport, participants) and characterizing 'app'/'content_id' as verified IDs, but it never enumerates allowed keys definitively or types for the content object.

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 ('Set structured content slots') plus the scoping constraint 'one verified app/content ID', which is more precise than the bare name. It does not explicitly differentiate from siblings, but no sibling in the list touches content context, so the risk of confusion is low.

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?

'Use genres for movies, format/sport/participants for videos' gives real conditional guidance on how to populate the context object. However, there is no statement of when to call this versus not calling it, or any prerequisite beyond 'verified' IDs; usage 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 the mutation profile (non-read-only, idempotent, non-destructive), so the description needn't restate safety. It does add genuinely useful behavior beyond them — that other source rules are preserved, i.e. a partial merge rather than a full replace — but stays silent on what happens for an unknown source or how defaults are applied to unspecified 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?

A single sentence, front-loaded with the verb and resource, with the preserve-semantics clause appended where it matters. No waste.

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

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

Annotations and the enum carry part of the load, and no output schema is needed. But for a configuration tool whose required key is opaque, the description leaves the most important semantic — what identifies a source — 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 3 parameters. The description gestures at 'audio' and 'delivery' but never defines what a 'source' is (app, package, device, contact?), which is the required parameter, nor explains the audio enum values (default/silent/chime/speech) or the effect of enabled.

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: setting a source's notification delivery/audio rule. Clear enough to act on, though it doesn't differentiate from neighboring notification tools (snooze_notifications, dismiss_notification, publish_notification) which operate on notifications rather than per-source rules.

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 — you call it to configure how a given source notifies. There is no explicit when-to-use vs when-not, and no guidance on how this relates to snooze/dismiss or to global notification settings.

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, idempotent, non-destructive, closed-world behavior. The description adds genuine context beyond that: the value is the device's actual volume and it is shared with the dashboard slider, so changes are globally visible and persist. It stops short of saying what happens with out-of-range input.

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 compact sentence with the action and range front-loaded and no filler. Every clause ('actual volume', '0–100', 'shared with the dashboard slider') adds usable information.

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

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

For a one-parameter, non-destructive tool with clear annotations and no output schema, the description supplies what an agent needs: target device, unit/range, and global effect. Only edge-case behavior (invalid values, error vs clamp) and the return value are unaddressed.

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 — and it does, defining percent as volume on a 0–100 scale and tying it to the physical speaker. Only the out-of-range/clamping behavior for percent is left unspecified.

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 (set the Pi speaker's volume) plus the valid range, and 'actual' clarifies it targets real hardware rather than a logical playback stream. It is distinguishable from siblings like speak/play_audio, though it does not explicitly contrast itself with them.

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 only implied: an agent can infer this is the tool for adjusting hardware volume when audio output is too loud/quiet. There is no explicit when-to-use, when-not, or named alternative (e.g. per-stream volume via control_spotify).

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description earns credit for disclosing the side-effect boundary (silent, no speech, no character replacement). It does not say whether queuing replaces or stacks against content already on the display, nor whether the Pi must be online — meaningful gaps for a write-hinted display 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?

Three short sentences, front-loaded with the core action, with zero filler. The middle sentence is a cross-reference rather than information, which slightly weakens an otherwise tight definition.

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

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

For a tool whose three parameters are entirely undocumented and which has no output schema, the description should resolve the date-range semantics and the display-replacement question. It covers the essential behavior (silent card, no speech) but leaves the parameters — the main source of invocation error — 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%, so the description carries the full burden, and "Same date range options as get_calendar_agenda" only defers to a sibling rather than explaining anything. Critically, the interplay between the `day` enum (today/tomorrow) and `start_date`/`end_date` strings is never addressed — which wins when both are supplied is left undefined.

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?

"Queue a silent calendar card on the Pi" gives a concrete verb (queue/show) and a concrete resource (calendar card) on a named surface. It is clearly distinguished from get_calendar_agenda (retrieval) by the word "queue" and from the speak/character tools by "silent." It does not, however, explicitly contrast with display_message/display_image, the closest sibling display tools.

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

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

"Does not replace the character or trigger speech" functions as an explicit when-not, routing the agent away from speak/character_speak for silent display. The implicit alternative (get_calendar_agenda) is named only as a parameter reference, not as a use-case alternative, so the routing is clear but not fully 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, idempotent, non-destructive, closed-world. The description adds real behavioral value by defining the duration bound and that zero resumes notifications, but it omits scope (which notifications are snoozed) and whether repeated calls overwrite the existing snooze timer.

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 sentences with zero filler, and the operative constraint (the range) is front-loaded before the edge-case clarification.

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 one-parameter, non-idempotent-looking-but-idempotent mutation with no output schema, the definition covers duration and the zero edge case, but leaves the blast radius (which notifications, per-source or global) unspecified — the main thing an agent needs to call it safely.

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 the parameter; it does so by giving the domain 0–1440 and explaining the boundary meaning of 0 (resume). It does not state units explicitly or what happens at 1440, but the compensation is substantial for a single integer param.

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 ('Snooze notifications') and adds the allowed duration range, which is genuinely informative. It doesn't explicitly differentiate from the sibling 'dismiss_notification', but the verb choice makes the distinction inferable.

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 statement of when to use snooze versus dismiss_notification, nor whether the snooze applies to all notifications or only a subset. 'Same policy as dashboard' points at external, unspecified behavior rather than giving the agent actionable guidance.

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

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

The annotations already state readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the agent knows this is a side-effecting but harmless, non-idempotent action. The description adds real behavioral context beyond the annotations: the 300-character limit and the fact that speech is rendered locally with no cloud dependency. It doesn't say whether calls block until speech finishes, what happens if text exceeds 300 characters, or what the tool 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?

Two short sentences, and the length cap and delivery target are front-loaded in the first sentence. Every clause adds information: what is spoken, where, how long, and via which backend. There is 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?

For a one-parameter action tool with meaningful annotations and no output schema, the description covers the essentials: target device, backend, and length limit. It leaves only minor gaps, namely over-length behavior and whether playback is synchronous. It doesn't need to describe return values because no output schema exists and the effect is audible.

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 single 'text' parameter has no documentation in the schema and the description must compensate. It contributes meaningfully by defining the content as the utterance and by capping it at 300 characters, but it never says whether the input is plain text or accepts SSML/markup, or how over-limit input is handled. The description adds useful partial semantics, not full coverage.

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

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

The description names a concrete verb (speak) and a concrete target (the AIY speaker), and it scopes the action with a 300-character cap. The phrase 'configured local speech backend' further narrows what 'speak' means so the agent doesn't mistake it for a cloud TTS tool. Siblings such as speak_on_echo and character_speak are distinct targets, but the description never says so explicitly, so it stops short of full sibling differentiation.

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 agent can infer usage (make the local AIY speaker say some text), but the description gives no explicit when-or-when-not guidance. It never mentions the near-neighbor siblings speak_on_echo (Echo hardware) or character_speak (character voice), even though choosing among them is the main selection problem. That makes the guidance implied rather than stated.

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 well beyond the annotations: 'Accepted means submitted to HA, not confirmed playback' discloses asynchronous acceptance semantics, which no annotation conveys, and 'Never retry automatically' encodes a retry policy consistent with idempotentHint=false. It also adds 'Soft-volume delivery' and dry_run validation behavior. It stops short of permissions, failure modes, or timing, keeping it below 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?

Six short front-loaded clauses, each carrying distinct information, with the primary targeting constraint first and caveats after. 'Soft-volume delivery' is the only clause whose meaning stays ambiguous, slightly softening an otherwise tight structure.

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 3-param, no-output-schema tool, it covers the essentials an agent needs: targeting semantics, async acceptance instead of playback confirmation, retry policy, and dry-run behavior. The remaining gap is speaker-name validity and error behavior, which matters given sibling `list_echo_speakers` exists but is never referenced.

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 full burden: it explains `dry_run` ('validates configuration without sound') and implies `speaker` via 'the explicitly requested named Echo', but says nothing about `text` and gives no guidance on valid speaker names or whether an unknown speaker errors. Partial compensation only.

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 (speak on a named Echo) plus a distinguishing scope constraint ('no presence routing'), which separates it from the generic `speak` sibling without naming it outright. The purpose is clear, but the routing contrast to `speak`/`character_speak` is left implicit rather than 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?

'Speak only on the explicitly requested named Echo. ... no presence routing' implies the use case (targeted playback) versus ambient routing, and 'dry_run validates configuration without sound' implies a pre-flight use. However, no sibling tool is named and no explicit when-not condition is given, so the agent must infer the alternative.

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