modx_delete_access_policy_template

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

No annotations are supplied, so the description carries the full behavioral burden for a destructive operation, and it discloses almost nothing: not whether deletion is permanent, what happens to access policies bound to the template, or what errors occur for a nonexistent id. Only the implied mutation is conveyed, which the verb already states.

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?

A single front-loaded sentence with the verb and the key discriminator ('by id'); nothing is wasted. It is short because it is under-specified rather than over-trimmed, which keeps it from a 5.

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 destructive, one-parameter tool with no annotations and no output schema, the definition should at minimum state irreversibility and any referential side effects. Neither is present, so an agent cannot predict the consequences of a successful call.

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 single parameter 'id' is typed only as number, but the phrase 'by id' confirms the argument is the identifier of an existing template. That is minimal added meaning; the description does not say where the id comes from (e.g., from modx_list_access_policy_templates).

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 and resource ('Delete an access policy template') and adds the scoping detail 'by id'. The sibling set makes the CRUD boundary obvious (modx_get_access_policy_template, modx_update_access_policy_template, modx_list_access_policy_templates), though the description itself does not name an alternative.

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 delete versus update, no prerequisites (e.g., administrator permission), and no warning about templates still referenced by access policies. An agent gets no criteria for choosing this tool over its siblings beyond the verb.

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