stop_system_trace

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

With no annotations at all, the description carries the full burden. It says 'gracefully' and mentions a retry path after transfer/cleanup failure, but does not state whether the trace is discarded, whether stop blocks until finalization, what permissions/state are required, or how long artifact retrieval may take — meaningful gaps for a mutating, file-producing operation.

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 tight sentences with the primary action and the artifact outcome front-loaded, followed by the retry condition. No filler, though the retry sentence is slightly cryptic about what specifically failed.

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?

It names the return artifacts, which partly compensates for the absent output schema, and gives retry guidance. But for a lifecycle-ending tool with zero annotations and an undocumented parameter, it omits prerequisites, failure modes, and whether the traceId remains valid after the call.

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% for the single parameter, so the description must explain traceId; it does not. An agent must infer that traceId is the identifier returned by start_system_trace and that it must reference a currently running capture.

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 ('Stop') plus the resource ('owned capture') and adds the outcome ('retrieve a local Perfetto file or validated Instruments .trace bundle'), which separates it from start_system_trace and get_system_trace_status. The phrase 'owned capture' is slightly jargon-y but understandable in context.

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

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

Usage is implied (call it to end a trace you started and get the artifact) and there is a useful retry hint ('Retry after a transfer/cleanup failure'). However, it never says how this differs from cancel_system_trace or when to prefer cancel versus stop-and-retrieve, leaving the key sibling choice to inference.

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