redmine_membership_create

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, yet it only reveals that this is a POST (write) operation to a specific path. It says nothing about whether creating a membership over an existing one replaces it, what permissions are needed, what happens on duplicate creation, or what the success response contains. For a mutating tool with zero annotation coverage, this is a substantial gap.

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 tight sentence with the verb front-loaded, and the HTTP endpoint is genuine routing information rather than filler. Every word earns its place, and it is easily parseable at a glance. It is under-specified in content, but that deficiency is properly penalized in the other dimensions.

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?

Both parameters are required, the membership object is an opaque nested structure, and there is no output schema or annotations to fall back on. An agent cannot construct a valid membership body from this description alone—it would have to guess at the required fields. The endpoint and project_id mapping are useful, but the critical payload shape and success/error semantics are entirely missing.

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 50%; project_id is documented in the schema ('project id or identifier') and the endpoint clarifies it as the target project. However, the required membership object is described only as additionalProperties: {} with no field documentation, and the description adds nothing about what it should contain (e.g., user_id, role_ids). At 50% coverage the description should partially compensate, but it does not.

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 ('Create') and resource ('membership') that distinguish it from siblings like redmine_membership_update and redmine_membership_delete. The exact endpoint, POST /projects/:project_id/memberships.json, adds concrete routing information beyond the tool name. However, it never explains what a membership actually is in Redmine terms, so an agent's understanding of the domain object remains thin.

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. The description does not mention prerequisites (e.g., that a user and role must exist before creating the membership, or that project membership management permission is required), nor does it route the agent to redmine_membership_update for modifications or redmine_project_memberships_list for viewing existing memberships. Usage intent is left entirely to inference from the tool name.

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