Show Company Action Plan Template Reference

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so 'Read-only' adds little. The description adds valuable error-status context (401, 403, 404), but it also creates confusion by saying company_id defaults when omitted while later stating it is required—an internal contradiction that undermines behavioral clarity.

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 well-organized with purpose, usage, defaults, error handling, and API reference. It contains some redundancy (read-only, required-params listing) but is generally tight for the amount of useful information packed in.

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 show-by-id tool, it covers the return type ('single JSON object'), common error statuses, id resolution guidance, and the Procore API endpoint. The company_id contradiction introduces a gap, but overall the description is sufficiently complete for invocation.

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 basic descriptions, so the baseline is 3. The description adds useful guidance for id (must resolve to existing parent record via list tool), but the contradictory statements about company_id being both defaultable and required severely harm parameter clarity, making this worse than the 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 opens with 'Retrieves a single company action plan template reference for the specified Procore company,' which clearly identifies the verb, resource, and scope. It distinguishes this show tool from list and recycled variants by emphasizing 'single' and 'existing parent record.'

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?

It says 'Use this when you already know which company action plan template reference you want and need its full field set,' providing a clear usage trigger. It advises resolving id with the matching list tool first, though it doesn't explicitly name the list tool or exclude recycled alternatives.

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