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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile needs no restating. The description adds real context beyond them: it is a live rather than cached inspection, and it discloses conditional return fields (codegraph / codegraph_version / codegraph_recommended when the client supports detection). Failure modes or what happens for an unreachable/offline device are not 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 opening sentence is front-loaded and information-dense, and the return-field note is useful, but trailing boilerplate ('Select this tool from the user's intent when it is the best match') and the connector/MCP naming sentence add little for a read-only inspection tool. The middle sentences about context inheritance are vague and dilute an otherwise tight definition.

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

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

With an output schema handling return shape and annotations covering safety, the description only needs to establish purpose, triggers, and the codegraph caveat, which it does. The one shortfall is that an agent still cannot tell from this text alone why it would choose system_capabilities over system_info or system_full_info.

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

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

Schema description coverage is 100%, so all six parameters are already documented, and the description's 'Pass device_name when the user names a computer' largely restates the schema text for that field. The note that a destination may be explicit or inherited from project/conversation context adds a little scoping nuance but does not explain device_id vs device_name precedence beyond what the schema says. Baseline 3 applies.

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

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

The description gives a specific verb and resource ('live check' of what a computer can do) and enumerates concrete capability domains: permissions, client version, files, search, Shell/PowerShell, processes, network ports, Git, Codegraph. It implicitly separates itself from list_devices ('Do not ... stop after listing computers'), but never names the closest siblings system_info/system_full_info, so disambiguation is only partial.

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?

Clear trigger conditions are spelled out ('when the user asks what a specific computer can do, which permissions or tools it currently has...') plus explicit negative guidance against answering from static metadata or stopping at a device list. It lacks explicit routing against nearby inspection tools such as system_info, system_full_info, or system_diagnose, which is the main remaining gap.

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