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

The description discloses important behavioral traits beyond the annotations: the copy is 'saved inactive' and 'remains off the data plane', requiring explicit activation, and 'Requires edit access' which is an authorization requirement. This adds significant context to the readOnlyHint=false and destructiveHint=false annotations, giving a clear picture of post-conditions and permissions.

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 two sentences long, front-loaded with the primary action, and every clause earns its place. It conveys purpose, key side effects, and a workflow hint without any waste.

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?

Given the tool's complexity (5 params, no output schema), the description covers the essential context: what is duplicated, the inactive state, the required edit access, and the next step via activate_line. It does not cover edge cases like existing newLineKey conflicts or commit modes, but the schema addresses those, so this is adequate.

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 the baseline is 3. The description does not add much parameter-specific information beyond what the schema already provides; it mentions 'build v2 from v1' which nods to newLineKey, but does not elaborate on commitMode or draftRevision. The schema already does the heavy lifting.

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 uses the specific verb 'Copy' and clearly identifies the resource ('a line and all its endpoints/targets/rules') and the outcome ('into a new line key — build v2 from v1'). This distinguishes it from sibling tools like create_line by emphasizing duplication of an existing line with full dependencies.

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?

The description provides clear usage context by framing it as 'build v2 from v1' and instructing to 'edit it, then activate_line when ready', which tells the agent the typical workflow. It does not explicitly state when not to use this tool or name alternatives, but the context is sufficient.

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