Bulk Create Project Memberships

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

Beyond the annotations (readOnly=false, openWorld=true), the description discloses critical behavioral details: processes all records in one request, returns the resulting collection, individual entries can fail independently, and failures return error payloads with common HTTP statuses (401, 403, 404). It also states that project_id defaults to the configured value, which clarifies a non-obvious behavior. No contradictions with annotations.

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 dense but every sentence adds value: purpose, constraints, usage preference, behavioral details, errors, required parameters, and API endpoint. It is well-structured and front-loaded with the main purpose. No filler or redundancy.

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 there is no output schema, the description makes a reasonable effort to explain return behavior ('returns the resulting collection' and 'individual entries can fail independently, so check each one'). It also covers required parameters, error statuses, and defaults. However, it does not specify the exact structure of each collection entry, which would be more complete. Overall, it is sufficient for most use cases.

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 covers both parameters (100%), but the description adds meaning by clarifying that party_ids are for reference users only and that project_id can be omitted when a config default is set. This goes beyond the schema's 'array of party identifiers' and 'unique identifier' descriptions. Slightly more detail on the format of party_ids could have earned a 5.

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 'Bulk Create Project Memberships for many parties on the given Project,' which clearly states the action (create), the resource (project memberships), and the scope (bulk, many parties). It distinguishes itself from sibling tools like create_project_membership (single-record) and bulk_remove_project_memberships (removal) by explicitly noting 'Prefer this over repeated single-record calls.'

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?

Provides explicit usage guidance: 'Prefer this over repeated single-record calls when handling many project memberships at once' and clearly states limitations ('can currently only be used to add reference users... cannot be used to add a user who has a login or to add vendors'). It also notes the project_id default from procore_set_config, which helps the agent decide when to omit it.

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