promote_exploration

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

With no annotations provided, the description carries the full burden, and it provides useful behavioral specifics: it is a WRITE operation, the source body is not copied, and the new item receives explicit outcome/completion metadata plus an evidence link back to the source. It does not cover permissions, reversibility, or side effects on the source, but it goes beyond a generic 'promote exploration' statement.

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 short and front-loaded with a 'WRITE.' signal, then a one-sentence statement of purpose and behavior. It is efficient and readable, although some additional essential context needed for a 18-parameter tool is absent. As structure alone, it is good.

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?

A tool with 18 parameters, no output schema, no annotations, and 0% schema coverage leaves the description as the only guide. Two sentences do not explain which IDs are required, how 'sourceProjectId' and 'targetProjectId' relate, what 'kind' selects, or how the evidence link is represented. The description is far from sufficient to invoke the tool correctly.

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%, and there are 18 parameters including 5 required ones. The description only hints at 'outcome/completion metadata' and an 'evidence link', which vaguely relates to outcome, doneWhen, and source/target IDs, but it does not explain the meaning or relationships of the parameters. This falls far short of compensating for the complete lack of schema descriptions.

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 a clear verb ('creates') and resource ('committed execution item') and explains the source ('exploratory material'). It distinguishes the operation from plain create_task by emphasizing that the source body is not copied and that the new item carries outcome/completion metadata and an evidence link. It does not explicitly name a sibling alternate, but the semantics are clear enough to differentiate.

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 implies the intended use case: converting exploratory work into a committed execution item. However, it does not explicitly state when to prefer this over create_task or related lifecycle tools, and it offers no exclusions or alternative conditions. This is only slightly above no guidance.

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