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

With no annotations, the description carries the full behavioral disclosure burden. It adds a meaningful behavioral detail: time_control is 'none', the board has no frame counter, so frame is null. It also enumerates reported fields; it stops short of stating explicit read-only guarantees or error behavior, but 'Report' strongly implies a non-mutating diagnostic call.

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 dense sentences with no filler. The purpose and returned values are front-loaded, and the time_control/frame caveat is placed at the end where it adds necessary precision.

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 status tool with no output schema, the description is complete enough: it lists what will be reported and explains the unusual null frame case. Missing details such as exact response formatting or failure modes are minor for this simple read-only diagnostic.

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 per calibration the baseline is 4. The description contains no parameter-specific information, but none is needed because there is no input schema to clarify.

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 reporting verb and lists concrete resources: machine id, enabled layers, current view/foreground app, and MicroPython app runtime. The 'Common (arcl)... any layer' preamble gives scope and helps distinguish it from CYD-specific siblings, though it does not explicitly name an alternative tool.

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

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

The phrase 'Common (arcl), any layer' implies this is the general arcl status entry point rather than a CYD-specific one, but the description does not explicitly say when to prefer it over siblings like cyd_runtime_status. Usage context is implied rather than stated as clear when-to-use/when-not-to-use 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?

With no annotations, the description carries the full burden of explaining side effects and behavior, but it only offers the opaque label 'Action, L1' and an alias. It does not say what activating does, whether it is synchronous, or what side effects occur. Referencing cyd_launch provides only indirect behavioral information.

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-loads the machine scope before the alias and legacy note. It wastes little space, though the cryptic 'Action, L1' fragment is not very informative.

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 alias with no output schema or annotations, the description is not complete enough on its own: it lacks actual semantics of activation, any guidance for app_id, and any consequences of the action. The alias to cyd_launch only helps if that sibling's full definition is consulted.

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 description does not mention app_id at all, so no meaning is added beyond the raw parameter name and required flag. The description should at least connect app_id to the application being activated.

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 does not directly state what cyd_activate does; it calls it 'Action, L1' and refers to cyd_launch as the equivalent. This makes the purpose inferable only through the sibling tool, which is vague. It is not a pure tautology, but it lacks a concrete verb+resource statement.

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

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

The description explicitly names cyd_launch as the canonical equivalent and says this tool is 'kept for clients written against the older name.' This tells an agent when to use this tool and implies that new clients should use cyd_launch instead.

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

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

With no annotations, the description carries the behavioral burden. It transparently states the operation is permanent and includes the cascading shortcut cleanup. However, it does not mention prerequisites, error behavior, or consequences for a currently running app.

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

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

The core sentence is compact and front-loaded with the action and scope. The opening fragments 'Machine-specific (cyd). Action, L1.' add little value and could confuse an agent, but overall the definition is efficiently sized.

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 destructive tool, it gives the essential effect and cascade behavior. Still, without annotations or an output schema it omits what happens on failure, whether deletion is recoverable, and any access or runtime prerequisites.

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

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

Schema description coverage is 0% and the description never addresses the app_id parameter semantically. It says 'one installed MicroPython app' but does not clarify that app_id is the identifier, its format, or how it relates to app names shown in listing tools.

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

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

The description uses a specific verb ('delete') with a clear resource ('one installed MicroPython app') and a precise behavioral scope ('and any Home shortcut that targets it'). This distinguishes it from siblings like cyd_shortcut_delete and cyd_apps_list.

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

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

No guidance is given for when to use this tool versus alternatives such as cyd_shortcut_delete or cyd_app_deploy. The phrase 'Machine-specific (cyd). Action, L1.' does not convey usage context or exclusions.

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

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

No annotations are provided, so the description must disclose behavior itself. It does mention that the manifest is checked, that the tool returns to Home first, and that it installs or updates a whole directory. However, it does not disclose the destructive nature of the 'replace' parameter (default true) or any side effects like overwriting existing apps, nor does it mention permission or state changes. The behavior is partially transparent but not complete for a mutation tool with zero annotation coverage.

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

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

The description is three sentences with no filler. Key information (action, scope, path resolution, behavioral prerequisite) is front-loaded. The phrase 'Machine-specific (cyd). Action, L1.' is somewhat cryptic but does not waste words. It is appropriately compact for the complexity.

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

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

For a deploy operation with 4 parameters, no output schema, and no annotations, the description should cover parameter effects, error behavior, and side effects. It covers app_dir resolution and the Home-return requirement, but omits the semantics of the boolean parameters (pin, launch, replace) and does not mention return values or failure modes. The tool is more complex than a simple list or query, so this is insufficient.

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 for undocumented parameters. It explains app_dir resolution, but says nothing about 'pin', 'launch', or 'replace' — their meanings, defaults, or effects. With 4 parameters and only one addressed, the description fails to provide semantic value for the majority of the input 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 states a specific verb ('Install or update'), a clear resource ('whole app directory'), and enumerates the contents (manifest.json, entry file, assets, binaries). It clearly distinguishes itself from sibling tools like cyd_launch or cyd_package_upload by scope — whole directory vs single file.

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

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

It provides context on where app_dir is resolved (CYD_DESKTOP_APPS_ROOT, default examples dir) and a prerequisite (returns to Home before upload because device refuses uploads while an app runs). However, it does not explicitly name alternatives or state when NOT to use this tool versus cyd_package_upload or other install-related siblings, leaving usage selection partially 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly says 'Read', indicating a non-destructive operation, and specifies it retrieves the most recent failure traceback. It does not mention potential side effects or edge cases (e.g., no failures), but for a simple read tool this is adequate transparency.

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

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

The description is two short sentences with no fluff. It leads with the core action and resource, then adds a useful constraint (48-character summary limitation). Every word earns its place, and the structure is efficient.

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

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

Given zero parameters, no output schema, and a simple read operation, the description fully covers what an agent needs to know to call the tool correctly. It specifies the input (none), the action, and the rationale for using it. There are no missing critical details.

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

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

The tool has zero parameters, so the schema is empty and coverage is trivially 100%. The baseline for 0 parameters is 4, and the description does not need to explain any parameters. It correctly omits parameter details, which is appropriate.

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

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

The description clearly states the verb 'Read' and the resource 'full traceback of the most recent MicroPython app failure', making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like cyd_logs by specifying it retrieves a full traceback rather than a generic log, and mentions the machine-specific context (cyd).

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

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

The description implies when to use this tool by noting that the event log only keeps a 48-character summary, suggesting this tool is for getting the full details when needed. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5 but provides clear contextual 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that the list is 'fixed' and 'kept in the firmware', which is useful behavioral context. However, it does not describe the output format, whether the list is sorted, or any side effects (though listing is likely read-only). The description adds some value but leaves the return shape unspecified.

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 with no waste. The core purpose is front-loaded, the scoping qualifier is immediate, and the sibling distinction is a single efficient sentence. Every sentence earns its place.

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

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

For a zero-parameter, no-output-schema list tool, the description is nearly complete. It tells the agent what is listed, that it is machine-specific, and how to get the other kind of list. The only gap is the lack of any hint about the output format (e.g., JSON array of strings), but with no output schema and a simple list operation, this is a minor omission.

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 there is no schema burden to compensate for. The description's mention of 'ids' and 'fixed list' gives the agent a sense of what the output will contain, which is the only parameter-like semantic needed here. Baseline 4 for zero-param tools is appropriate.

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

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

The description states a specific verb ('List'), a specific resource ('ids of the built-in views and native apps'), and a key scoping constraint ('Machine-specific (cyd)'). It also explicitly distinguishes itself from the sibling cyd_installed_apps_list, which lists installed MicroPython apps. This is a clear, non-tautological purpose statement.

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

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

The description explicitly names the alternative tool (cyd_installed_apps_list) and the condition that selects it ('Installed MicroPython apps are listed by...'). This gives the agent a clear when-to-use vs when-not-to-use rule, which is especially valuable given the large sibling 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?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: pairing forgets the previous keyboard. It also explains the PIN/passkey flow and that the PIN is also available in cyd_bt_status. It does not mention failure modes or whether the action is destructive beyond the forget behavior, but the disclosed traits are meaningful.

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, all information-dense. The action, the interaction flow, and the destructive consequence are each covered without redundancy. Front-loaded with the action and scope.

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 action with no output schema, the description covers the essential context: what it does, how the user interaction works, and the side effect. It could mention what happens if the index is invalid or whether the action blocks, but those are minor gaps given the simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'index' refers to a keyboard from the last scan, which adds meaning beyond the raw integer schema. It does not specify the valid range, but the schema already provides minimum/maximum.

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 ('Pair'), a specific resource ('a keyboard from the last scan by index'), and the exact interaction flow (PIN shown, user types on keyboard, Enter). It is clearly distinguishable from siblings like cyd_bt_scan and cyd_bt_forget.

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

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

The description implies when to use it: after a scan, selecting by index, and it warns that pairing forgets the previous keyboard. It does not explicitly name alternatives or say 'use cyd_bt_scan first', but the context is clear enough.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a state-changing operation ('disconnect and forget') but does not specify whether the action is reversible, whether the keyboard must be currently connected, or what side effects occur on remembered pairings. 'Forget' suggests permanent removal, but that is not explicitly stated.

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 core action. The 'Machine-specific (cyd). Action, L3.' prefix is cryptic and adds little value, but it is minimal. Overall, every significant word contributes to understanding the tool's purpose.

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-argument tool, the description is mostly sufficient, but it omits potential return values, failure conditions, and whether the action permanently removes the pairing or just disconnects temporarily. Since there is no output schema and no annotations, these gaps leave an agent with some uncertainty about the operation's full effect.

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

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

The schema has zero parameters, so the baseline is 4. The description adds meaning by clarifying that the tool operates on 'the remembered Bluetooth keyboard,' implying the target is a stored pairing rather than a device passed as an argument. This helps explain why no parameters are 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 uses a specific verb phrase 'Disconnect and forget' with a clear resource, 'the remembered Bluetooth keyboard.' This distinguishes it from sibling tools like cyd_bt_connect, cyd_bt_scan, and cyd_bt_status, which deal with connecting, scanning, or status rather than forgetting a stored pairing. The 'Machine-specific (cyd)' and 'Action, L3' prefixes are cryptic but do not obscure the core function.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention cyd_bt_connect, cyd_bt_status, or any related tools, nor does it state conditions or exclusions. The verb 'disconnect and forget' implies a use case, but the agent is left to infer when this action is appropriate.

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

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

No annotations are provided, so the description carries the burden. It discloses that the scan runs for a given number of seconds and that results are not immediate, requiring a separate poll to cyd_bt_status. However, it does not mention side effects, permissions, or state changes (e.g., whether the scan clears previous results), which is a gap for a machine-specific 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?

The description is two sentences with no redundancy. It front-loads the action and duration, then immediately provides the polling instruction. Every word adds value, and it is appropriately terse for a simple parameter.

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

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

The tool has one parameter, no output schema, and no annotations. The description covers the main purpose and the polling step, but it lacks details like what constitutes a successful scan, how to interpret results from cyd_bt_status, or any error states. Given the simplicity, it's mostly complete, but an agent has to infer the exact outcome of the scan.

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

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

Schema description coverage is 0%, and the only parameter is 'seconds' with a default of 10 and a maximum of 30. The description states 'for the given seconds,' which directly explains the parameter's purpose, adding value beyond the schema. However, it doesn't explain what happens if seconds exceeds the max or if a lower value is better for responsiveness, so it's adequate but not thorough.

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

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

The description clearly states the action: 'Search for Bluetooth Classic keyboards in pairing mode for the given seconds.' It specifies the resource (Bluetooth Classic keyboards) and the condition (pairing mode), and it distinguishes itself from siblings like cyd_bt_connect and cyd_bt_status by focusing on the scan action.

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 context: run this scan when you need to find keyboards in pairing mode, then poll cyd_bt_status for results. It does not explicitly state when not to use it or name alternatives, but the instruction to poll cyd_bt_status indicates a sequence, which is clear enough for an agent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states this is a read-only observation, lists the specific data it exposes, and adds a runtime constraint ('Bluetooth runs only in radio mode bluetooth'). It does not mention side effects, but 'Observation' strongly implies none.

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

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

The description is a single compact sentence group that front-loads the key facts (machine-specific, observation) and then enumerates the status contents in a scannable list. Every phrase earns its place; there is no filler or 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 no-argument observation tool, the description is largely complete: it names the resource, the data points returned, and a runtime prerequisite. It does not describe the return format, but absence of an output schema and the simplicity of a status read make this a minor gap rather than a blocking one.

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

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

The tool has zero parameters and the input schema is empty, so the schema coverage is trivially complete. The baseline for 0-param tools is 4, and the description adds no irrelevant parameter detail. Nothing more 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 specific verb ('Read') and resource ('Bluetooth keyboard state'), and enumerates exactly what that state includes: connected/remembered keyboard, pairing progress with PIN/passkey, and last scan results. This clearly differentiates it from mutation or scan siblings like cyd_bt_connect, cyd_bt_forget, and cyd_bt_scan.

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

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

The description signals this is an observation tool ('Observation, L3') and provides a prerequisite ('Bluetooth runs only in radio mode bluetooth'). However, it does not explicitly tell the agent when to prefer it over sibling tools such as cyd_bt_scan or cyd_bt_connect, nor does it state exclusions (e.g., 'use cyd_bt_scan to initiate a new scan'). Usage is implied rather than explicit.

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

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It explains the fingerprint parameter's effect: '1 starts summing the CRC-32 of everything sent to the LCD... 0 stops it'. This is a meaningful side effect beyond a simple read. It also adds the property about firmware builds producing the same change, which is useful diagnostic context. The 'Observation' label suggests a read-only nature, though the fingerprint action modifies state, so it is not purely read-only. This is a solid disclosure of the tool's behavior.

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 compact—two sentences that pack a lot of information without waste. The main purpose is front-loaded, and the parameter explanation follows logically. No redundant phrases or filler. Every sentence earns its place.

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

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

For a simple read tool with one parameter and no output schema, the description covers purpose and parameter well. However, it does not describe the return format or how the diagnostics data is presented, which could be ambiguous for an agent. It also doesn't clarify what 'desktop transport and health diagnostics' concretely includes. Given the lack of an output schema, the description should ideally hint at the response structure or provide usage examples. These gaps make it only partially complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does so excellently by explaining exactly what fingerprint=1 and fingerprint=0 do, including the CRC-32 summing behavior and the property of identical painting behavior. This goes far beyond the raw schema (integer min 0 max 1) and gives the agent everything needed to use the parameter correctly. The optionality is implied but not explicitly stated; still, the semantics are fully clarified.

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

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

The description opens with 'Read desktop transport and health diagnostics', giving a clear verb and resource. The tool is distinct from its siblings, which deal with home, apps, input, etc. The phrase 'Observation, L2' hints at a read-only monitoring role, though 'desktop transport' is jargon that could be clearer. Overall, the purpose is discernible and differentiated enough.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or situations where another tool would be preferable. The only contextual hint is 'Machine-specific (cyd)', which suggests it applies only to that machine, but there is no explicit when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core action but does not explain side effects, whether it preserves app state, any permissions required, or the nature of 'Home' (e.g., a specific launcher or system home). This is minimal for a tool that presumably navigates away from the current app.

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 ('Return the foreground application to Home'). The prefix 'Machine-specific (cyd). Action, L1.' is terse but adds some context, though it could be clarified. Overall, it is concise and efficient without unnecessary words.

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

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

For a simple action with no parameters and no output schema, the description gives the core purpose, which is adequate for basic invocation. However, it lacks context about what 'Home' means (system home, a specific app, or an app-specific state), and it does not mention any prerequisites or limitations. Given the absence of annotations, a slightly richer description would improve completeness, but the tool is simple enough that this is acceptable.

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

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

The tool has zero parameters, and the schema coverage is trivially 100% (empty object). Per the baseline for 0-parameter tools, the description does not need to explain parameters, and it adds no parameter semantics because none exist. A score of 4 reflects the baseline and that no additional clarification 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 clearly states the action: 'Return the foreground application to Home.' It specifies a verb and resource, and it is distinct from siblings like cyd_launch or cyd_pause in that it performs a specific navigation action. It lacks an explicit differentiation from other navigation-related tools, but the purpose is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only states what it does ('Return the foreground application to Home') with no mention of prerequisites, exclusions, or alternative tools. The context 'Machine-specific (cyd). Action, L1.' offers metadata but not usage criteria.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the read-and-clear mutation but does not disclose what happens when no input event is pending, whether clearing affects the state seen by cyd_input_read, or what 'L0' means. For a mutation operation with zero annotation coverage, this is a notable gap.

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

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

The core behavior is front-loaded in a single efficient sentence with no wasted words. It could earn a 5 by explaining the unexplained 'Action, L0' tokens, but as written it is properly concise.

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, no-output-schema tool the description is mostly sufficient, but it leaves the 'L0'/'Action' terminology unexplained and omits edge-case behavior (e.g., behavior when the input queue is empty). Adequate but with clear gaps in operational context.

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

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

The tool has zero parameters and 100% schema coverage, so there are no parameter semantics the description must clarify. Per the baseline for zero-parameter tools, a 4 is appropriate – nothing is left 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?

The description states a specific verb+resource pair: 'Read the most recent input event and clear it.' This clearly distinguishes it from sibling cyd_input_read (which presumably only reads) because it adds the clearing behavior. The 'Machine-specific (cyd)' prefix is minor noise but not misleading.

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

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

No guidance on when to use this tool versus alternatives like cyd_input_read or cyd_input_state. The 'Action, L0' qualifier is unexplained jargon that gives the agent no actionable routing information. There is no when/when-not/alternative 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?

With no annotations, the description carries the full burden. It mentions 'queue' (implying asynchronous) and 'short' (implying a limit), but does not disclose side effects, whether it blocks, if it clears previous queued input, or error behavior. It also does not mention that the machine is 'cyd' beyond the initial tag. Key behavioral aspects are 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?

The description is short and front-loaded with the action, but it includes extraneous metadata 'Machine-specific (cyd). Action, L0.' that does not aid understanding. The core sentence is concise, but the overall structure could be more useful by focusing on usage and 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 a complex parameter (array of objects), no annotations, and no output schema, the description is inadequate. It does not explain how to structure the steps array, the limits on coordinates and delays, or what the tool returns. An agent needs more explicit guidance to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'coordinate taps' and 'optional delays' but does not explicitly map these to the 'steps' array fields (x, y, delay_ms). It does not clarify coordinate ranges, the meaning of delay_ms, or the max 64 items. The description adds minimal semantic value over the raw 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 clearly states it queues a sequence of coordinate taps with optional delays, which is a specific verb+resource and differentiates from single-tap siblings like cyd_tap by the word 'sequence'. However, it does not name sibling tools explicitly, so the 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?

No guidance is given on when to use this tool versus alternatives such as cyd_tap or cyd_input_clear. The description does not state conditions like 'for multiple taps' or 'when you need delays between taps'. An agent would have to infer use cases from the tool's name and purpose.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool reads without clearing, which is a key behavioral trait, and notes it is machine-specific ('cyd'). However, it does not specify the return format, error behavior, or any side effects beyond not clearing, leaving some ambiguity.

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

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

The description is a single sentence, concise and front-loaded with the core action. However, the prefixed jargon 'Machine-specific (cyd). Observation, L0.' is not explained and could be confusing to an agent, slightly reducing clarity.

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

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

For a simple read tool with no parameters and no output schema, the description explains the core behavior and provides examples. The main gap is the lack of details about the return structure, which an agent might need to correctly interpret the output. Overall, it is reasonably complete given the tool's simplicity.

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

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

The tool has zero parameters, so the schema is trivially 100% covered. Per the baseline for zero-parameter tools, a score of 4 is appropriate; the description adds no parameter information, but none 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 clearly states the verb 'Read' and the resource 'most recent input event', with concrete examples ('tap.home or tap.<button id>'). It also distinguishes itself from cyd_input_clear by noting 'without clearing it', making the tool's function unmistakable.

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

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

Usage guidance is implied rather than explicit. The phrase 'without clearing it' hints that cyd_input_clear is the alternative for clearing, but there is no explicit statement of when to use this tool versus cyd_input_state or other siblings. No direct condition or recommendation 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?

With no annotations, the description carries the behavioral burden, and 'Read' plus 'Observation' clearly indicate a non-mutating operation. It also discloses that it reports queued synthetic tap count, which is useful context. It does not mention potential side effects, but the read-only framing makes them unlikely.

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

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

The description is a single sentence with no filler. It front-loads the read action and immediately lists the specific state components, making it easy for an agent to parse quickly.

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

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

For a zero-parameter state-read tool, the description is nearly complete: it names all observed data and labels the operation as observational. It does not specify return format or units, but the tool is simple enough that this is a minor gap rather than a blocker.

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 there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description adds relevant context about what data will be returned.

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

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

The description uses the specific verb 'Read' and names the exact resources: physical touch state, last coordinate, and queued synthetic tap count. It clearly identifies what the tool does, and the 'Observation' label helps distinguish it from mutating input tools like cyd_tap or cyd_input_clear, though it doesn't explicitly name a sibling.

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 'Observation, L0' implies this is a low-level read-only inspection tool, and 'Machine-specific (cyd)' suggests it is for that particular device. However, there is no explicit guidance about when to prefer this over cyd_input_read or other input-related tools, and no exclusions 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?

No annotations are provided, so the description must carry the behavioral transparency burden. 'Observation, L1' implies a read-only, low-impact operation, which provides some safety signal, and 'List' reinforces a non-mutating action. However, it does not explicitly state that nothing is modified, nor does it mention filesystem access, output format, or any side-effect-free guarantee.

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 very brief and uses no filler. However, it frontloads metadata labels ('Machine-specific' and 'Observation, L1') before the core verb phrase, which slightly delays the most actionable information; still, each phrase contributes context and the overall length is appropriate.

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 zero parameters and no output schema, the description conveys purpose but leaves the return value uncertain beyond 'list of apps'. It doesn't describe what 'Home pin state' means, nor does it mention whether results are app names, metadata, or another structure. The tool is a simple observation action, but the lack of any behavioral or output context is a notable 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 input schema has zero parameters and a 100% schema description coverage with nothing to document. Per the baseline for zero-parameter tools, this dimension is strong; the description doesn't need to explain parameters and does not introduce ambiguity.

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 ('List'), a clear resource ('MicroPython apps installed on the microSD'), and adds a distinguishing detail ('including Home pin state'). It does not explicitly differentiate itself from the similarly named sibling 'cyd_apps_list', 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 description provides no guidance on when to use this tool instead of alternatives like 'cyd_apps_list' or 'cyd_shortcuts_list'. It labels the tool as 'Observation, L1' and 'Machine-specific (cyd)', but does not state when it is the right choice or mention any exclusion criteria.

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

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

With no annotations, the description carries the burden of explaining behavior, and it does well: it says the key behaves like a hardware keyboard press, reaches the editor/app, and that CTRL+C interrupts a running app. It also clarifies machine-specific (cyd), modifier syntax, and the accepted key set. It does not cover return values or failure modes, but the most important side effects are disclosed.

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 compact and front-loaded with the tool's purpose, followed by a dense but understandable list of valid keys. The only minor noise is the cryptic 'Action, L0' fragment, which adds little for an agent; otherwise every sentence earns its place.

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

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

For a one-parameter action with no output schema, the description covers what the tool affects (the editor and running app), the accepted key grammar, and an important side effect (CTRL+C interruption). It is nearly complete, though it does not state what the tool returns or how an agent would detect a failed key press.

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 fully explain the sole 'key' parameter. It does so by enumerating characters, named keys, function keys, and modifier prefixes with a concrete example (CTRL+S) and a special-case behavior (CTRL+C interrupt). This goes well beyond the raw regular expression and makes correct invocation predictable.

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: 'Press one key as a hardware keyboard would.' It clearly separates this from text input or touch input by focusing on a single key event and enumerating valid key names. This lets an agent distinguish it from siblings like cyd_type_text and cyd_tap.

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

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

The description provides useful usage context: the editor receives the key, a running app reads it via cyd.key(), and CTRL+C has the special effect of interrupting a running app. It does not explicitly name alternatives or state when not to use this tool, but the single-key framing makes the intended boundary reasonably clear.

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

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

The description discloses a key behavioral trait beyond the schema: launching a MicroPython app is queued, so success means it will start, not that it has. This is valuable async/queuing context. With no annotations provided, the description carries the full burden, and it does so reasonably well, though it could also mention side effects or prerequisites.

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 with no waste. The core action and scope are front-loaded, and the queuing caveat is placed at the end where it belongs. Every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description is largely complete: it defines the resource types, the action, and the async caveat. It could be more complete by clarifying how to discover valid app_id values (e.g., via cyd_apps_list or cyd_installed_apps_list), but the core calling context is 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?

Schema description coverage is 0%, so the description must compensate. It explains that app_id identifies a built-in view, native app, or installed MicroPython app, which adds meaning beyond the bare schema. However, it does not specify the format of app_id (e.g., whether it is a name, numeric id, or path), so the compensation is partial.

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 ('Open') and resource ('a built-in view, a native app, or an installed MicroPython app by id'), which clearly distinguishes it from many siblings. It does not explicitly name a sibling alternative, but the scope is clear enough to differentiate from tools like cyd_activate or cyd_run.

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

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

The description implies when to use it: when you want to open a built-in view, native app, or installed MicroPython app by id. It does not explicitly state when not to use it or name alternatives like cyd_activate or cyd_run, so the guidance is implied rather than explicit.

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

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

With no annotations, the description must carry the behavioral burden. It does state that the operation is a read/observation and names the log categories, which implies non-destructive behavior. However, it omits details such as output format, retention window, ordering, whether the log is cleared or affected by reading, and error behavior, so disclosure is adequate but incomplete.

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 tool's identity and purpose. The fragments 'Machine-specific (cyd)' and 'Observation, L2' are terse but not wasteful; however, 'L2' is unexplained and could confuse an agent, so it is not maximally concise.

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 tool, the description provides the basic subject and operation, but it does not describe the expected response, log contents beyond the three categories, or when this log is useful. Since there is no output schema, more context about the returned log data would be needed for the tool to be considered fully self-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 input schema is an empty object with zero parameters, so there is no parameter information to explain. The description's reference to the specific log domains is the only semantic content, and for a parameter-free tool this meets the baseline expectation.

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 ('Read') and a specific resource ('retained recent UI, input, and application event log'), so an agent can tell this is a log-reading tool. The 'Machine-specific (cyd)' and 'Observation, L2' fragments add context but are cryptic, and the description does not explicitly distinguish it from other observation tools like cyd_ui_tree or cyd_diagnostics.

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 guidance on when to prefer this tool over the many sibling observation/diagnostic tools. It does not mention alternatives, exclusions, prerequisites, or typical scenarios, leaving the agent to infer usage from the word 'Read'.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers atomicity, SHA-256 verification, default encoding, preservation of existing files unless replace is true, and the foreground-app failure condition. This is strong transparency for a mutation tool.

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

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

The description is four short sentences with the core operation front-loaded. It adds no redundant restatement of the schema, and every sentence contributes behavioral or usage 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?

Despite having no annotations and no output schema, the description covers the operation, preconditions, binary/text handling, and existing-file behavior. It does not describe return values or exact failure details, but those are not critical gaps for this upload action.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the target path via app_id, the file name placement, encoding choices with a concrete JPEG example, and replace semantics. Content is implied as the uploaded file data, though not explicitly named.

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 operation: atomically upload one file into /sd/apps/<app_id>/ after SHA-256 verification. This clearly distinguishes it from sibling tools such as cyd_app_deploy or cyd_app_delete and gives an exact target path.

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

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

It gives concrete invocation conditions: text is the default, base64 must be used for binary assets like JPEGs, existing files are preserved unless replace is true, and the tool fails while a foreground app is running. It does not name alternative tools explicitly, but the conditions and target path make intended usage 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose a key behavioral trait: the pause is cooperative and deferred until the next cyd.update(), which adds real value. However, it does not mention whether the pause is reversible, how to resume, or what side effects may occur, which are relevant for an agent invoking a control command.

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 brief and front-loads the essential behavior ('pause') before explaining the cooperative mechanism. The opening fragments 'Machine-specific (cyd).' and 'Control, any layer.' add some noise, but the overall structure is efficient and easy to parse.

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 zero-parameter schema and simple command semantics, the description is mostly complete for invocation. It explains what the command does and its distinctive timing behaviorcars. It omits guidance on resumption or state implications, but those are secondary for a minimal pause command.

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 Removal: 0 params = baseline 4. The description adds no parameter semantics because none exist, and the empty input schema is fully covered. This is appropriate for a parameterless command.

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 ('pause') and identifies the target resource ('the foreground MicroPython app'). It further clarifies the cooperative nature by specifying the pause occurs at the next cyd.update(), which distinguishes it from immediate interruptions. The phrase 'Control, any layer' is vague, but the core purpose remains clear.

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

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

The description does not state when to use this tool versus alternatives such as cyd_resume or cyd_step. It provides no explicit usage context, prerequisites, or exclusions, leaving the agent to infer when a cooperative pause is appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses persistence across boot, delayed application until restart, and the failure condition for restart=true. It does not mention output or side effects, but the key behavioral traits are 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 short and front-loaded with the core purpose. The 'Machine-specific (cyd). Action, L3.' fragment adds some jargon but does not significantly bloat the 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 two-parameter setter with no output schema, the description covers the essential behavior, persistence semantics, and the main caveat. It does not describe return values, but that is a minor gap for this tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains mode values inline and adds meaning for restart by describing its immediate effect and failure condition. This goes beyond the bare 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 states a specific verb ('Store') and resource ('radio mode') with the intended scope ('for the next boot'). It is clearly distinct from the sibling read tool cyd_radio_status, and the action is unambiguous.

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

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

The description clearly explains when the setting takes effect ('after a restart') and warns that restart=true fails while a foreground app is running. It does not explicitly name alternatives, but the context makes the intended usage 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?

With no annotations at all, the description carries the full responsibility. 'Read' and 'Observation' correctly imply a read-only operation, and the exclusivity note adds useful state-model information. However, there is no mention of permissions, error cases, or what happens if radio state is unknown, leaving some gaps.

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 tightly written sentences. The purpose is front-loaded, the state values are enumerated, and the exclusivity constraint is provided in a second short clause. No wasted words.

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

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

For a parameterless read-status tool, the description covers what is returned (current and next-boot radio mode) and its domain (off, wifi, bluetooth). Since there is no output schema, a little more detail about return format would boost it, but the tool's simplicity makes the description largely 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 has zero parameters and the schema covers 100% of them, so there is nothing for the description to add. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on semantics of the response rather than parameters.

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 ('Read') and a specific resource (radio mode), and specifies exactly what is read: current boot mode and next-boot stored mode, with enumerated values. It also distinguishes the tool as an observation tool within a set that includes a setting sibling (cyd_radio_set).

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 a usage context ('Observation, L3') but never explicitly says when to use this over alternatives such as cyd_radio_set or cyd_bt_status. There are no when-not-to-use caveats or references to sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals one precondition (the app must be cooperatively paused) but says nothing about error behavior when nothing is paused, whether the call is synchronous or blocking, or what side effects resuming entails. For a state-changing control operation on remote hardware, this is a meaningful gap.

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

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

At roughly ten words the description is suitably brief, but it reads as three disjointed fragments rather than a coherent statement. The fragment 'Control, any layer' does not earn its place — it is ambiguous rather than informative and could confuse an agent about the tool's scope.

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?

As a parameterless control operation, the description is mostly adequate, but with no output schema and no annotations the agent gets no expectation of return values or failure behavior. For a stateful remote-device operation, noting what happens when no app is paused or the app is already running would complete the picture.

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 rubric baseline is 4 and there is nothing for the schema or description to document. The 'cooperatively paused' qualifier usefully conveys the invocation precondition, which is the closest equivalent to parameter semantics here. Nothing is missing.

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

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

The description names a specific verb ('Resume') and resource ('a cooperatively paused MicroPython app'), which clearly differentiates it from siblings like cyd_pause and cyd_step. However, the leading fragments 'Machine-specific (cyd)' and 'Control, any layer' are cryptic and don't add obvious clarity. The core action is clear but the surrounding qualifiers muddy precision slightly.

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 qualifier 'cooperatively paused' implies a precondition — this tool should only be used when the app paused cooperatively, which is the state created by the cyd_pause sibling. But the description never explicitly states when to use this versus alternatives (e.g., cyd_launch, cyd_run) nor what to do if the app was forcibly halted. Usage guidance is 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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose the central behavior—pausing the app and advancing a bounded number of update frames—which is real context beyond the tool name. However, it does not clarify whether the app remains paused afterward, what side effects frame advancement may have, or what the operation 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?

The description is short and mostly front-loaded, with the core mechanism in the second sentence. However, 'Control, any layer.' is a cryptic fragment that does not earn its place and the first sentence adds little beyond 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?

For a single-parameter tool, the core invocation information is present: what it does and what the frame count means. But there is no output schema, no post-condition clarity, and no orientation against the large cyd_* sibling family, leaving some contextual gaps.

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

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

Schema coverage is 0%, so the description must explain the single parameter, and it does: 'frames' clearly corresponds to the number of cyd.update() frames granted. This fully compensates for the missing schema descriptions and adds meaning the schema alone does not provide.

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 concrete action: pause the cooperative MicroPython app and grant a bounded number of cyd.update() frames. This distinguishes it from a generic 'run' command and from siblings like cyd_pause or cyd_step. The phrase 'Control, any layer' is vague, but the main clause is specific enough.

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

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

There is no guidance on when to use this tool versus the many closely related siblings such as cyd_pause, cyd_resume, or cyd_step. 'Machine-specific (cyd)' is a scope warning, not usage direction, and no alternative or exclusion is mentioned.

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

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

With no annotations, the description must carry the behavioral disclosure. It states it's a read operation, but gives no details on side effects, blocking behavior, or whether the state is a snapshot. The ambiguous 'Control, any layer' further muddies the behavioral 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 very short and front-loaded with the machine-specific label, but the 'Control, any layer' phrase is confusing and appears out of place. It's concise but poorly structured, wasting words on ambiguity.

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?

Without an output schema, the description should hint at the return value format. It only says it reads state, not what the agent will receive (e.g., a JSON object with pause and frame fields). The ambiguous 'Control' phrase also leaves room for misinterpretation. For a simple read tool, this is under-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?

The tool has zero parameters, so the schema provides full coverage by default. Per the rubric, a baseline of 4 is appropriate, and the description doesn't need to explain parameters. It also doesn't introduce conflicting parameter info.

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 specifies a clear verb ('read') and resource ('cooperative MicroPython runtime pause and frame state'), and the machine-specific context ('cyd') distinguishes it from generic tools. However, the phrase 'Control, any layer' is ambiguous and detracts from clarity, as it could imply control functionality that contradicts the read-only intent.

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

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

The description provides no guidance on when to use this tool versus alternatives like arcl_status or cyd_pause. It doesn't mention scenarios, exclusions, or how this status read differs from sibling read tools, leaving the agent to infer.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses that the output is a logical, lightweight PNG derived from the retained UI tree rather than actual pixel data, and 'Observation' implies read-only behavior. This is meaningful context, though it does not elaborate on error conditions or environmental prerequisites.

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

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

The description is extremely concise: two short sentences plus a terse classification fragment. Every element earns its place by adding machine scope, observation level, output type, and a key caveat. 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 no-parameter observation tool with no output schema, the description covers the essential facts: what it renders, the resolution, the source data, and the important caveat that it is not pixel-accurate. It could be slightly more explicit about the exact return value format, but 'PNG mirror' is sufficiently clear.

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

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

The tool has zero parameters, and the input schema is empty, so the baseline is 4. The description does not need to add parameter semantics because there are none to document.

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: 'Render a lightweight logical 320x240 PNG mirror from the retained UI tree.' It clearly distinguishes itself from pixel-level capture by stating 'This is not an LCD pixel readback,' which separates it from related tools like cyd_ui_tree.

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 'Observation, L0' gives clear context for when the tool is appropriate, and the explicit exclusion 'not an LCD pixel readback' helps an agent avoid misuse. It does not name a specific sibling alternative or describe when not to use it beyond that exclusion, so it falls short of full 5-level 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?

There are no annotations, so the description must carry the full behavioral burden. The phrase 'single foreground' hints at exclusivity, but the description does not disclose what happens to the currently running app, whether stopping/termination occurs, what side effects may result, or what the return/status behavior is.

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 very compact and front-loaded with the essential action. 'Action, L1' is cryptic and adds little clarity, but it does not create bloat; overall the description is efficient and direct.

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, the description is adequate in naming the target script and the single-foreground behavior. However, with no annotations and no output schema, it remains incomplete about side effects and expected results, which an agent would need for safe invocation.

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

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

The description adds meaning beyond the schema by embedding app_id in a path (/sd/apps/<app_id>/main.py), making clear that the parameter identifies the application directory. However, it does not explain how to discover valid app_id values or which sibling tools provide them.

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

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

The description clearly states a specific action (launch) and a specific resource (/sd/apps/<app_id>/main.py), and adds behavioral scope ('single foreground MicroPython app'). It is not a tautology, but it does not explicitly differentiate itself from siblings like cyd_launch, cyd_run, or cyd_activate.

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

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

No guidance is given on when to use this tool instead of alternatives such as cyd_launch, cyd_run, or cyd_activate. The only contextual hint is the cryptic 'Machine-specific (cyd)' and 'Action, L1', which do not provide practical selection criteria.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does state the operation is read-only via 'Read' and 'Observation', and it notes the card is optional and FAT, implying the result may be negative when no card is present. However, it does not describe the return format or any failure/error behavior, leaving some ambiguity for a tool without an 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?

The description is extremely brief and front-loaded. Each clause adds relevant context: machine scope, observation type, and the exact subject being read. There is no filler or 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 zero-parameter status read, the description says enough to invoke the tool correctly: it identifies the exact condition being checked. The only minor gap is that the return value is not explicitly specified, but 'whether' strongly implies a boolean or status indicator, so this is not a serious omission.

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

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

The input schema has zero properties and the description requires no inputs, so there is no parameter semantics burden at all. The baseline for zero-parameter tools is 4, and nothing in the description creates confusion.

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

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

The description names a specific verb ('Read') and a specific resource state ('whether the optional FAT microSD card was mounted safely at boot'). The 'Machine-specific (cyd)' and 'Observation, L3' tags further clarify that this is a targeted read-only status check, making it easy to distinguish from the many sibling control and diagnostics tools.

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

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

The description clearly frames this as an observation tool for a cyd-specific SD-card mount check. It does not explicitly contrast with sibling status tools like cyd_runtime_status or arcl_status, but the narrow resource wording makes the intended use obvious without needing exclusions.

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

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

No annotations are present, so the description carries the behavioral disclosure burden. It does reveal a non-mutating intent through 'Read' and 'Observation, L1' and limits scope to the cyd machine. However, it does not explicitly say the operation is safe/read-only, nor does it cover output/error behavior or environmental prerequisites.

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 compact and lists its key content in a single readable sentence. The opening fragments 'Machine-specific (cyd)' and 'Observation, L1' add context but could be better integrated or reordered to lead with the action.

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 parameter-less getter with no output schema, the description is mostly complete: it defines the device scope and enumerates the fields being read. It does not describe return shape, but that is less critical when the tool has no parameters and the read targets are named explicitly.

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

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

The tool has zero parameters and schema description coverage is 100%. There is no parameter meaning for the description to add, so the baseline score 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?

The description uses the specific action 'Read' and a clear resource ('settings'), and it enumerates exact settings exposed: brightness, color theme, animation speed, and Bluetooth keyboard layout. This makes it unmistakably the getter counterpart to the sibling cyd_settings_set.

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 guidance is primarily implied: the tool reads settings and is labeled an observation, so an agent can infer when to use it. It does not explicitly direct the agent to prefer this tool over cyd_settings_set or other siblings, nor does it state exclusions or preconditions.

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

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

With no annotations at all, the description carries the full burden, and it does disclose the most critical behavior: persistence semantics with merge-style updates (omitted settings unchanged). It does not disclose error behavior, whether changes apply immediately, persist across reboots, or require a device connection, but for a simple settings tool the merge semantics are the key behavioral trait and they are clearly stated.

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 compact and front-loaded: the core action and the partial-update caveat appear first, followed by the single parameter clarification that adds the most value. The "Action, L1" fragment is minor noise that adds no decision-relevant information, but overall every other sentence earns its place.

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

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

For a simple tool with four optional enum parameters and no output schema, the description covers scope, action, update semantics, and the ambiguous parameter. It falls short by not relating the tool to cyd_settings_get, not indicating what the tool returns after persisting (relevant since there is no output schema), and not stating whether settings survive reboots.

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 for four parameters. It explains keyboard_layout (the one genuinely ambiguous parameter, with jis/us enums) while the other three (theme, animation, brightness) have reasonably self-explanatory enum values. This is targeted compensation but does not fully describe all parameters; e.g., what distinguishes animation=fast from smooth is left unexplained.

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

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

"Persist one or more settings" is a specific verb + resource statement that clearly identifies the tool as a write operation for settings. It is implicitly distinguished from the sibling cyd_settings_get through the set/get naming, though it does not explicitly name that sibling. Categorizing labels "Machine-specific (cyd)" and "Action, L1" add context about scope but do not sharpen the purpose.

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

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

The statement "Omitted settings remain unchanged" communicates partial-update semantics, telling the agent it can safely modify a subset of settings without clobbering others. However, there is no explicit guidance about when to use this tool versus cyd_settings_get (read), cyd_radio_set (adjacent hardware settings), or other sibling tools, leaving routing largely implicit.

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

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

With no annotations, the description must carry behavioral disclosure. It does state machine-specificity, microSD-backing, and the capacity of 18 shortcuts, which gives some operational context. However, it does not disclose what happens on duplicate shortcut_id, whether the operation overwrites or fails, or if the microSD card must be present. These are notable gaps for a create operation, so a score of 3 reflects partial disclosure rather than a complete behavioral contract.

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

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

The description is extremely concise, consisting of two sentences with no filler. The core action is front-loaded ('Create a new microSD-backed Home shortcut'), and the second sentence adds relevant layout details. Every word earns its place, achieving high information density without verbosity.

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

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

Given no output schema, no annotations, and three undocumented parameters, the description falls short of what an agent needs to correctly invoke the tool. It fails to explain what each parameter represents, what a successful creation returns (if anything), and how the agent should handle potential errors (e.g., duplicate ID, capacity limits). The layout info is nice context but does not compensate for the missing operational details.

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

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

The description provides no explanation of the three parameters (title, app_id, shortcut_id). Schema description coverage is 0%, so the description is the only place to convey parameter meaning, yet it mentions none of them. Even the patterns in the schema only constrain format, not semantic intent. This is a critical omission for a tool with three required parameters.

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

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

The description clearly states the action (create) and the resource (Home shortcut), and specifies 'microSD-backed' which distinguishes it from other shortcut operations. It also provides concrete context about the Home screen layout (two on first page, eight per following page, 18 total), making the tool's purpose unmistakable and differentiating it from sibling tools like cyd_shortcut_update and cyd_shortcut_delete.

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 this is the creation tool for Home shortcuts and gives useful layout context that helps an agent understand where shortcuts will appear. However, it does not explicitly state when to prefer this over alternatives or mention any exclusions (e.g., 'use only when a slot is available'). The layout info serves as reasonable contextual guidance, so it slightly exceeds baseline but lacks explicit routing.

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

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

With no annotations, the description carries full behavioral disclosure burden. It states the deletion but does not disclose irreversibility, error behavior (e.g., missing ID), or any side effects on the home screen or storage. The qualifier 'microSD-backed' adds specificity but not behavioral scope.

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 brief (one sentence) and not bloated, but it lacks substance. While conciseness is good, the structure provides no additional layers of information beyond the bare purpose. It is under-specified rather than efficiently complete.

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

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

Given no annotations and no output schema, the description ought to carry the full context. It does not address failure modes, validation rules, or the meaning of 'microSD-backed' in the context of Home shortcuts. For a simple tool this might be minimal, but the lack of behavioral detail leaves gaps 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?

The schema has 0% description coverage, and the description does not explain the parameter at all. It simply uses 'shortcut_id' without stating what it represents, its format, or that it must reference an existing shortcut. The pattern in the schema is the only clue.

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

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

The description names a specific action ('Delete') and a precise resource ('microSD-backed Home shortcut'). It clearly distinguishes from siblings like cyd_shortcut_create and cyd_shortcut_update, which operate on the same object type but with different operations.

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

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

No guidance on when to use this tool versus alternatives. There is no mention of conditions, prerequisites (e.g., shortcut must exist), or when to prefer update over delete. The context is left entirely to the agent to infer.

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

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

No annotations are provided, so the description must carry the behavioral burden. The word 'Observation' hints at a read-only operation, but the description does not explicitly state side effects, permission requirements, or whether it modifies internal state. This is passable but thin for a non-annotated tool.

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

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

The description is compact: one context sentence, one functional sentence. It front-loads the actual list behavior and avoids filler. The initial 'Machine-specific (cyd). Observation, L1.' is slightly cryptic, but it adds context without wasting space.

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

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

With no output schema, the description tells the agent that shortcuts are listed but does not describe the returned value shape, fields, or possibly empty/normal conditions. For a simple zero-parameter read this may still be callable, but the agent is left guessing about the output format.

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

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

The tool has zero parameters and a fully covered empty schema, so there are no parameter semantics to enrich. Per the baseline for no parameters, a score of 4 is appropriate; the description cannot add more because there is nothing to parameterize.

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 ('List') and a distinct resource ('microSD-backed Home shortcuts'), which unambiguously identifies the operation. It also has clear distinct siblings (cyd_shortcut_create/update/delete), so an agent can tell this is the read-only listing variant without opening schemas.

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

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

The description labels this as an 'Observation, L1', implying a read-only inspection use, but it never explicitly states when to use it over related tools such as cyd_home, cyd_apps_list, or cyd_shortcut_*. There are no exclusions or alternative tool names, so selection guidance is left to inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds machine-specific and microSD-backed context and clearly implies mutation, but it does not state side effects, whether the update replaces or merges fields, permission requirements, or failure behavior. This is thin for a mutating tool.

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

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

The description is one sentence with the action and target front-loaded and no filler. The 'Action, L1' fragment is cryptic but compact, and the overall structure is appropriately brief even though it omits important operational 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 three-parameter mutation tool with no annotations and no output schema, this description is incomplete. It identifies the resource but omits parameter semantics, return behavior, and update semantics. An agent would need more context to invoke it correctly.

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

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

Schema description coverage is 0% and the description does not explain shortcut_id, app_id, or title. It only restates that an update happens without mapping the three required parameters to their meaning. An agent cannot infer what values to supply or how they relate to the shortcut being updated.

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 'Update' and a specific resource, 'existing microSD-backed Home shortcut.' The word 'existing' plus the verb distinguishes it from create/delete siblings, even though those alternatives are not named. The 'Action, L1' prefix is cryptic but does not obscure the core purpose.

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

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

Provides no guidance on when to use this tool versus alternatives such as cyd_shortcut_create, cyd_shortcut_delete, or cyd_shortcuts_list. There are no prerequisites, exclusions, or explicit conditions for when an update is appropriate. The only implied signal is that the shortcut must already exist.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool advances by one frame and that it targets cooperatively paused apps, but it does not state what happens if the app is not paused, whether the step is reversible, or what side effects (e.g., state changes) occur. This is a significant gap for a control operation with no annotation coverage.

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

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

The description is a single sentence and is efficient, but the phrase 'Control, any layer.' is ambiguous and adds little value. The core action is front-loaded, but the vague prefix could be removed for clarity. Overall it is concise and structurally sound.

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

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

For a tool with no parameters and no output schema, the description provides the essential precondition (cooperatively paused) and the action (advance by one frame). It is adequate for invocation, though it does not mention error conditions or return behavior, which is acceptable 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?

The tool has zero parameters, so the schema provides no semantic content. The baseline for 0 params is 4, and the description adds the key semantic context of 'one cyd.update() frame', which is useful but not required since there are no arguments to document.

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 ('Advance') and a clear resource ('a cooperatively paused MicroPython app'), and it specifies the action as advancing by one cyd.update() frame. This distinguishes it from siblings like cyd_resume (full resume) and cyd_pause (pause), making the purpose unambiguous.

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

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

The description implies usage when the app is 'cooperatively paused', which is a precondition, but it does not explicitly contrast with alternatives such as cyd_resume for full continuation or cyd_tap for UI interaction. No explicit 'when-not' or alternative is named, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tap is 'synthetic' and 'queued' (not immediate), and specifies the coordinate system ('absolute 320x240 display coordinate'). However, it doesn't disclose whether the tap is injected at the OS level, whether it requires a foreground app, or what happens if coordinates are out of bounds (though schema enforces bounds).

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 key qualifiers ('Machine-specific', 'Action, L0', 'synthetic tap', 'absolute 320x240 display coordinate'). Every word earns its place; 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 simple 2-parameter tool with no output schema, the description is mostly complete. It covers the action, coordinate space, and queued nature. Gaps: no mention of return value/acknowledgment, no mention of whether the tap is injected immediately or batched, and no mention of any prerequisites (e.g., device must be awake). These are minor for a low-level action but would help an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that x and y are absolute display coordinates in a 320x240 space, which adds meaning beyond the raw integer schema. However, it doesn't clarify units (pixels), origin (top-left?), or whether the coordinates are relative to the display or the current app.

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 ('Queue a synthetic tap') and resource ('absolute 320x240 display coordinate'), which clearly distinguishes it from sibling tools like cyd_key_press or cyd_type_text. It doesn't explicitly name a sibling alternative, but the action is unambiguous.

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

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

The description implies when to use it: when a synthetic tap at a display coordinate is needed. It doesn't explicitly state when not to use it or mention alternatives like cyd_touch_calibrate_start for calibration, but the context is reasonably clear for a low-level action tool.

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

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

With no annotations, the description carries the full burden, but it only restates the core mutation ('synchronize the clock'). It does not disclose whether this overwrites the current time, requires permissions, is reversible, or what the tool returns on success/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?

The core sentence is compact, but it is prefixed by cryptic fragments ('Action, L1') that do not earn their place. The description is short yet not optimally front-loaded.

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

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

For a one-parameter action with no output schema, the description covers the essential operation and input. It is minimally adequate, though an agent would still lack information about the expected result or side effects.

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

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

The schema provides only a name and minimum for the single integer parameter, but the description clarifies that the parameter represents a Unix epoch, which is essential semantic meaning. It could add units/range clarity, but 'Unix epoch' is a recognizable standard.

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 ('Synchronize') and resource ('CYD clock'), and specifies the input source ('Unix epoch'), making the tool's function clear. It does not explicitly differentiate from siblings, but no sibling covers clock/time operations, so the lack of explicit differentiation is not a real issue.

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 about when to call this tool, prerequisites, or alternatives. 'Machine-specific (cyd)' only hints at scope and does not help an agent decide between this and other cyd_* tools.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses that the tool is interactive, displays the first crosshair, requires tapping, and saves a corrected mapping. However, it does not mention whether this is reversible, what happens after the third tap, or whether it changes persisted device settings, leaving some behavioral ambiguity.

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 concise and front-loaded with the crucial machine-specific and action-level context. The only minor issue is the cryptic 'Action, L3' phrase, which adds some ambiguity but does not create redundancy.

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

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

The description conveys the core three-step calibration flow and the required user interaction, which is adequate for a no-parameter tool. However, it omits details such as cancellation behavior, what happens after the third crosshair, and whether a return value or confirmation is provided, which an agent might need for full context.

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

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

The tool has zero parameters and the schema has no properties, so there are no parameter semantics to explain. The description adds no parameter details, but none are 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 clearly identifies the tool as a machine-specific cyd action that starts touch calibration by showing the first of three crosshairs. The verb 'show' and the calibration context distinguish it from generic tap or settings tools, though it does not explicitly differentiate itself from a sibling by name.

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

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

The description implies when to use it: during a three-step touch-calibration process on cyd, with the user instructed to tap each crosshair. It does not explicitly state when not to use it or mention alternatives, but no sibling appears to be a calibration tool, so the context is reasonably 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?

With no annotations, the description carries the disclosure burden, and it does so well: text is sent as hardware keyboard presses, one key per character, newlines become ENTER, and only printable ASCII is accepted. It does not mention focus prerequisites or side effects, but the core behavior is clearly disclosed.

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 compact and mostly front-loaded, with the essential behavior stated early. The cryptic fragment 'Action, L0.' adds little value for an agent and prevents a perfect score.

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

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

For a one-parameter tool with a detailed schema, the description is mostly sufficient: it covers the operation and special newline handling. It leaves some gaps, such as whether a field must already be focused and what happens if the tool is invoked outside a text-entry context.

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

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

Schema description coverage is 0%, so the description must explain the text parameter itself. It adds real meaning by specifying one-key-per-character behavior, the newline-to-ENTER mapping, and the printable-ASCII limitation, going beyond the raw JSON pattern.

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

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

The description states a specific action (type text) and mechanism (hardware keyboard presses) on a specific machine, with clear input constraints. It is behaviorally distinct from sibling key-press and macro tools, though it does not explicitly name an alternative.

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

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

The 'Printable ASCII only' constraint and the newline-to-ENTER rule give implicit guidance about what inputs this tool supports. However, it never explicitly says when to choose cyd_type_text over cyd_key_press, cyd_input_macro, or other input-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?

No annotations are present, so the description carries the burden. It discloses it is a read-only observation and lists what it reads, which is good. However, it does not mention any behavioral traits like latency, performance impact, or whether it can be called repeatedly without side effects. The description is accurate and does not contradict any annotations (none provided).

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?

Extremely concise and front-loaded. The first sentence establishes the tool's identity and scope. Every phrase adds value: 'detailed', 'visible', 'UI tree', and the list of attributes. No wasted words.

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

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

For a zero-parameter observation tool with no output schema, the description is quite complete. It covers what the tool does and what information it provides. Minor gap: it does not clarify if 'visible' means only what is on-screen vs. accessible view hierarchy, or if there are any prerequisites (e.g., app must be foregrounded). Still, strong coverage for the tool's simplicity.

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 no parametersainer, so the description does not need to explain parameter semantics. The description clearly states what information is returned (ids, roles, labels, bounds, enabled state), which goes beyond the empty schema. This provides the necessary semantic context for the tool's output.

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

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

Description states a clear purpose: reading the detailed UI tree with specific attributes (ids, roles, labels, bounds, enabled state). This is a distinct read-only observation tool. Some ambiguity remains with the 'Machine-specific (cyd)' prefix but this does not detract significantly.

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

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

The description implies usage for UI observation but does not explicitly contrast with siblings like cyd_screen_mirror or cyd_input_state. It does not state when to use this versus alternatives, but the emphasis on 'detailed visible UI tree' suggests its role. Lacks explicit guidance on khi nào to use or not.

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