create_approval_policy

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

Beyond the all-false annotations, the description discloses that the server injects tenant_id and created_by, and clarifies that creation alone does not activate the policy—binding to an agent's CSP is required. This is meaningful behavioral context for a write operation.

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?

Three dense sentences front-load the purpose, then give the approver shapes, activation path, and contract constraints without repetition. Every sentence adds needed information.

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 creation tool with no output schema, the description covers the call contract, parameter restrictions, and the post-creation activation requirement. It does not describe the response shape or error cases, but those are not essential for a correct first invocation.

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 100%, so the baseline is 3; the description adds examples for approvers ({type:'user', id:'<uuid>'} vs {type:'role', role:'admin'}) and restricts the payload to name/description/stages. This helps an agent construct valid input beyond the schema's enum/type 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 opens with 'Cria uma política de aprovação', giving a specific verb and resource, and clarifies the domain (who approves tool actions under HITL). It is immediately distinguishable from sibling tools like list_approval_policies, get_approval_policy, and update_approval_policy.

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 primary use case (creating an approval policy) is clear, and the description adds an important follow-up step: the policy only takes effect when bound via CSP behavior.approval_policy_id + behavior.require_approval_for. However, it does not explicitly contrast this with update_approval_policy or state when not to use this tool, so alternative selection guidance is only implicit.

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