Show Project User

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

While readOnlyHint is already annotated, the description adds substantial non-obvious behaviors: null keys are omitted from the response, error payloads carry HTTP status with common codes (401/403/404), project_id has a default, and id must reference an existing parent record. These details go well beyond annotations and schema.

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 informative but slightly verbose. The '#### OK Response' heading is an awkward artifact, and 'Required parameters: project_id, id' duplicates schema information. However, the content is front-loaded with the purpose and each subsequent sentence earns its place.

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?

With no output schema, the description adequately explains the return type ('a single JSON object describing the project user'), covers error behavior, mentions defaults, provides prerequisite context, and includes the API endpoint. It is complete for a read-only single-resource GET tool.

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% with both parameters already described. The description adds the project_id default behavior and the requirement to resolve id via the list tool first. These are meaningful additions beyond the schema, though not exhaustive on parameter syntax.

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: 'Show detail on a specified Project User.' It clearly distinguishes from sibling tools like list_project_users, create_project_user, and update_project_user. The added note 'Use this when you already know which project user you want and need its full field set' reinforces the singular-get 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?

Explicit when-to-use guidance is provided: 'Use this when you already know which project user you want...' It also names an alternative workflow: 'resolve it with the matching list tool first' for the id parameter, and explains the project_id default from procore_set_config. This is clear and actionable context.

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