edubase_post_class_permission

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

Annotations include readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description correctly identifies it as a create operation, consistent with annotations. However, it does not elaborate on behavioral details beyond what annotations provide—such as whether the creation requires specific authorization (e.g., only admins or certain role), whether existing permissions for the same user/class are overridden or fail, or what the response format looks like. The output schema exists but the description does not leverage it to hint at return behaviors.

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 concise sentence that accurately captures the tool's purpose. No fluff or unnecessary detail. Every word is meaningful, and it is easy to parse quickly. It earns its place perfectly.

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 presence of an output schema and complete input schema, the description provides adequate purpose and basic context. However, it lacks information about behavioral nuances such as idempotency (the hint is false) and potential side effects. For a permission-creating tool, agents might benefit from knowing whether duplicates are allowed or whether the operation is scoped to a specific role within the class.

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 already describes all three parameters (user, class, permission) with clear descriptions and an enum for permission values. The schema description coverage is 100%, so the description does not need to repeat this information. However, it could add value by explaining how the parameters interact—for example, whether the user must already be a class member, or what happens if the permission already exists. Still, the baseline is high due to full schema coverage.

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 'Create new permission for a user on a class', which is a specific verb+resource combination. It clearly differentiates from sibling tools like edubase_delete_class_permission or edubase_get_class_permission, making the tool's distinct purpose unmistakable.

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 implies the tool is used when adding a new permission to a class for a user, but it does not explicitly state when not to use this tool or mention alternatives like edubase_patch_user or other permission-related tools. There is no guidance on prerequisites (e.g., does the user need to be a member of the class first?) or scenarios where updating an existing permission might be more appropriate.

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