gateway_work_tracker_policy_set

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

There are no safety annotations beyond a title, so the description carries the full burden of disclosing side effects. It does reveal one important behavioral trait—no issue transition—but it omits whether the policy is persisted, overwritten, validated, or requires specific permissions, and it does not clarify the consequences of setting a lifecycle policy.

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 a single sentence with no filler, and the most important qualifier is placed at the end. It is concise, but the undefined 'Tracker lifecycle policy' terminology makes it less self-contained than it could be.

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?

With 0% parameter coverage and no explanation of policy_json's structure or the operation's effects, an agent cannot reliably invoke this tool. The output schema exists, so return-value details are not required, but the missing parameter semantics and behavioral context leave a significant gap.

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 the description does not explain either parameter. 'Tracker lifecycle policy' hints that policy_json contains the policy and work_id likely identifies the issue, but no format, allowed values, or semantics are provided, which is insufficient for constructing a valid call.

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 names a specific verb and resource ('Set the Tracker lifecycle policy') and adds a meaningful qualifier ('without transitioning the issue') that separates it from state-transitioning work tools. It is slightly weakened by the capitalized 'Tracker' jargon and the mismatch between the title's 'Completion Policy' and the description's 'lifecycle policy,' but the core operation is identifiable.

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 phrase 'without transitioning the issue' implies a use case where the agent wants to update policy but keep the issue state unchanged. However, the description never names alternatives or explicitly states when not to use this tool, leaving the agent to infer routing among many work_* siblings.

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