create_cospend_member

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

Annotations only carry basic mutation flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds substantial behavioral context: the MAINTAINER permission requirement, the soft-disabled creation mode and why it's rare, the side effect of linking a user_id (member sees the project in their UI), and the exact return shape. This goes well beyond what annotations reveal.

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 organized with clear sections (access, Args, Returns) and each parameter line earns its place by adding semantic meaning absent from the schema. It is longer than needed because defaults are restated from the schema, but that duplication is forgivable given the schema's zero descriptions.

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?

The description covers permissions, all six parameters with defaults and edge cases, the return-value semantics, and cross-references to other tools (update_cospend_member, memberId for other tools). An agent has everything needed to invoke this correctly.

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%, so the description carries the full burden — and it delivers. Every parameter is explained: project_id and name, the optional user_id with its visibility effect, weight with the concrete 'counts double in even splits' example, active with the soft-disable caveat, and color with hex format guidance and server-pick fallback.

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 a specific verb and resource: 'Add a member to a Cospend project.' This clearly distinguishes it from siblings like update_cospend_member or list_cospend_members, and the scope (create, not modify) is unambiguous.

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 states the required access level ('Requires MAINTAINER access') and gives an explicit alternative routing for a specific case: 'usually create active and disable later via update_cospend_member.' It doesn't broadly contrast with all siblings, but the key decision points are covered.

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