Show A Crew

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

Beyond the read-only and non-destructive annotations, the description explicitly reassures 'Read-only — it changes nothing in Procore.' It also discloses error behavior with specific HTTP statuses (401, 403, 404), adding valuable operational context not present in 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 information-dense yet concise. It front-loads the core purpose, then packs usage conditions, defaults, error behavior, required parameters, and API endpoint into a compact paragraph with no redundant phrases or filler.

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?

For a simple two-parameter read-only operation with robust annotations, the description covers all essential aspects: what it returns, when to use it, how parameters behave, error handling, and the exact endpoint. No output schema is needed since the return is just a crew object, and the description states that.

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 coverage is 100%, so baseline is 3. The description adds meaning by explaining project_id's default from procore_set_config and instructing that id must refer to an existing record resolved via a list tool. However, the note about project_id being omittable conflicts slightly with the schema's required flag, so it's not a perfect 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?

Description opens with 'Return Crew detailed information' — a specific verb+resource statement. It further distinguishes from siblings by noting it's for when you 'already know which crew you want and need its full field set,' clearly differentiating it from list/create/update/delete crew tools.

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?

Explicitly states when to use: 'Use this when you already know which crew you want and need its full field set.' It also gives a concrete prerequisite: 'resolve it with the matching list tool first' for the id, and notes project_id default behavior. This provides clear usage context and an implicit alternative (the list tool).

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