retention_generate_policy

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

With no annotations, the description carries the full burden of behavioral disclosure, but 'Generate data retention policy' reveals almost nothing. It does not state whether the tool writes files, modifies the project, requires authentication, or has side effects. The description is effectively a restatement of the tool name and provides no behavioral context beyond the bare action.

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 short sentence with no filler, but it is under-specified rather than appropriately concise. It sacrifices necessary detail for brevity, leaving the definition thin. There is no front-loaded scoping or clarification that would make this length effective.

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?

The tool has no output schema, no annotations, and a minimal description. It does not explain what a generated retention policy looks like, what side effects occur, how parameters are used, or what the agent should expect. Given the complexity of policy generation and the presence of related sibling tools, this definition is critically incomplete.

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 coverage is only 50%: the 'directory' parameter has a terse description ('Project directory'), while 'api_key' has none. The description does not explain either parameter or clarify how they are used in generating the policy. An agent cannot determine the role of api_key or what directory should point to from this definition.

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 ('Generate') and object ('data retention policy'), which clearly identifies what the tool produces. It distinguishes itself at a top level from sibling tools like retention_generate_report and retention_add_automation by focusing on the policy output. However, it is very close to the tool name and lacks any additional specificity about the policy's scope or format.

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 no guidance on when to use this tool versus related siblings such as retention_generate_report or retention_add_automation. There is no mention of prerequisites, target scenarios, or exclusions. An agent is left to infer usage entirely from the tool name and context.

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