Create A New Crew

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

This description adds substantial behavioral context beyond the annotations. It explicitly describes the non-idempotent nature ('calling it again creates another record'), the success response (returns the crew with its new id, HTTP 201), and common failure modes (401, 403, 404). It also explains a non-obvious payload behavior: fields are nested under 'crew' in the request, but the agent passes them as top-level arguments. This goes well beyond the simple hint flags.

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 efficiently structured: it opens with the core purpose, then covers payload handling, defaults, idempotency, error responses, required parameters, and API reference. Each sentence conveys necessary operational detail without fluff, and the information is front-loaded.

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 that this is a relatively simple create operation with full schema coverage and no output schema, the description is remarkably complete. It covers the action, payload structure, parameter defaults, non-idempotency, success/error response patterns, required fields, and the underlying API endpoint. There are no significant gaps for an agent to invoke and understand the result.

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 provides descriptions for all five parameters, so the baseline is 3. The description adds valuable semantics: it explains that body fields are automatically nested under 'crew' in the payload, and that project_id defaults to a configured value when omitted. This is meaningful information that complements the schema, raising the score above baseline.

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 clearly states the tool's primary action: 'Create a new Crew associated with the specified Project.' This uses a specific verb (Create) and resource (Crew), immediately distinguishing it from sibling tools like show_a_crew, update_a_crew, and delete_a_crew. The inclusion of the endpoint (POST /rest/v1.0/projects/{project_id}/crews) further reinforces the purpose.

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 provides clear contextual guidance: it tells the agent to pass fields as top-level arguments, explains that project_id defaults to the procore_set_config value, and notes that calling it again creates another record (non-idempotent). It also lists required parameters. However, it does not explicitly name alternatives (e.g., 'for updates, use update_a_crew') or state when not to use this tool, so it stops short of a 5.

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