CaptureManagedRuntimeState

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

Adds real behavior beyond the annotations: passive sidecar, never claims the debug port, no target mutation, and the scope of optional token resolution. It doesn't disclose what the caller should expect about the pause/resume_after lifecycle, but it meaningfully explains a non-read-only tool's safety 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?

Three short, front-loaded paragraphs; the core purpose leads and the constraints follow. No filler, though the token-resolution sentence is niche detail placed at the same weight as the pause requirement.

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?

Behavioral context is decently covered, but for a 10-parameter tool with no output schema and zero schema coverage, the description leaves parameter semantics and the return shape entirely unaddressed. It is adequate on behavior but incomplete on invocation detail.

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?

10 parameters at 0% schema description coverage, and the description only hints at metadata_token/instruction_pointer via the token-resolution sentence. max_maps, max_frames, max_modules, max_threads, timeout_ms, module, resume_after, and pause_if_running are left entirely to bare names and defaults.

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 (Capture) and a precise resource (CLR/AppDomain/module/thread/stack/JIT state) plus the mechanism (passive sidecar). This distinguishes it from siblings like GetRegisterDump, GetCallStack, and DumpModule, which cover unmanaged/register/module-level state rather than the full managed runtime view.

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

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

Gives one hard precondition (target must be paused) but never states when to choose this tool over CaptureStopContextStructured, DumpModule, or GetCallStack. Usage is implied by the resource it captures, so this is minimum-viable rather than routing guidance.

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