directus_create_permission

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

With no annotations provided, the description carries the full burden of behavioral disclosure but only provides minimal information. While it notes that 'policy' is required for Directus v10+, it fails to disclose side effects, reversibility, idempotency, or error conditions when permission rules conflict with existing system 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 brief with only two sentences and front-loads the action, but includes the '[UNIFIED]' metadata prefix which serves no purpose for the AI agent. The 'NOTE:' section is appropriately placed but the overall structure includes noise that does not aid tool selection.

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 high complexity of Directus permission systems involving relationships between policies, roles, collections, and granular action controls, the description is insufficient. With zero schema descriptions and no output schema, the description should explain the domain model or parameter relationships necessary to construct valid permission rules.

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?

The input schema has 0% description coverage for 9 complex parameters, requiring the description to compensate heavily. While it mentions the 'policy' constraint, it provides no semantics for critical parameters like 'collection', 'action', 'permissions', or 'validation' which are essential to constructing valid Directus permission rules.

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 clearly states 'Create a new permission rule' which identifies the specific verb and resource. However, the '[UNIFIED]' prefix adds noise without semantic value, and it does not explicitly distinguish from the `directus_update_permission` sibling tool or explain what constitutes a 'rule'.

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?

There is no guidance on when to use this tool versus alternatives like `directus_update_permission` or when to prefer creating new permissions versus modifying existing ones. The description lacks prerequisites or conditions that would help an agent decide between this and sibling permission management tools.

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