start_trace_group

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

Beyond the annotations, the description discloses important failure semantics: configurations are validated first, newly started traces are detached if a later target fails, spawned applications may already have run, and rollback is hook cleanup rather than application-state undo. This is exactly the kind of operational caveat an agent needs for a destructive, open-world tracing 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 dense sentences, front-loaded with the core action and followed by failure behavior, side-effect limits, and scope exclusions. There is little waste and each sentence carries operational meaning.

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 complex tracing tool with no output schema and a large nested config schema, the description covers purpose and critical failure/rollback behavior well. However, it leaves significant gaps around parameter-level semantics and does not describe what the result of starting a trace group looks like, so it is adequate but not 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 only 33%, so the description must compensate. It adds useful high-level meaning by explaining that configs are explicit per-process configurations, limited to 1..4, and that run_id is shared, but it does not explain required config fields such as device_id and mode, nor does it mention the optional analysis_project_id parameter.

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 and resource: start 1..4 explicit per-process configurations in one retained run with a shared run_id. It also distinguishes the tool from implicit-discovery behavior by stating 'No implicit discovery or attachment to children,' making its scope clear relative to sibling tracing 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?

It gives clear usage context: use this when starting up to four explicit per-process configurations under one shared run_id. It also gives a when-not signal by saying there is no implicit discovery or attachment to children, though it does not explicitly name the closest sibling alternative such as start_trace.

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