GetDebugState

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful state context ('while paused' for callstack/registers, 'if available' for console), but does not explain what the normalized snapshot looks like when the process is not paused or how the bridge session relates.

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?

Purpose sentence first, then a compact Args block; no filler or redundancy. The structure is standard and front-loaded, though 'normalized' is an unexplained qualifier that adds little.

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 read-only, no-output-schema snapshot tool the definition is largely adequate: parameters are explained and the safety profile is in annotations. It falls short of complete because it never states what the aggregate 'normalized' state contains or how the sub-payloads combine, leaving the return shape undefined.

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% (only titles and defaults), so the description carries the full burden and does document all six parameters with real meaning beyond their names. It does not restate the defaults that the schema already encodes, and it clarifies the paused-state dependency of several flags.

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

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

States a specific verb and resource: 'Get a normalized debugger state snapshot.' An agent can tell it is an aggregate state reader rather than a single-facet reader, though the description never explicitly differentiates from sibling tools like GetCallStack or GetRegisterDump, which fetch overlapping sub-parts.

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 when-to-use or when-not-to-use guidance is given. Given the crowded sibling set (GetCallStack, GetRegisterDump, GetThreadList, GetModuleList), the description should say when this consolidated snapshot is preferable to those single-purpose tools, but it leaves that entirely to inference.

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