Get Single Time Off Record

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

Annotations already include readOnlyHint=true, but the description adds substantial behavioral context beyond annotations: 'Read-only — it changes nothing in Procore,' 'Returns a single JSON object,' and detailed error semantics (401/403/404) with specific meanings. It also discloses that company_id defaults to the procore_set_config value when omitted, which is non-obvious behavior. This goes beyond the annotation safety profile.

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 front-loaded with the main purpose and remains informative throughout. Each sentence adds contextual value (usage, config, errors, endpoint). Minor redundancy: listing 'Required parameters: company_id, person_id, time_off_id' repeats the schema's required list, but this is a small inefficiency in an otherwise focused description.

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 single-record retrieval tool, the description covers usage context, parameter resolution, read-only behavior, error handling, and config defaults. The lack of an output schema is partially compensated by the statement 'Returns a single JSON object describing the time off record' and 'full field set.' It is adequate but could be slightly richer in describing the returned fields.

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% for all three required parameters, so the baseline is 3. The description adds value by explaining the config-based default for company_id and requiring person_id/time_off_id to resolve to existing parent records, advising resolution via the list tool. This semantic guidance enriches the schema, though it doesn't detail parameter formats beyond what the schema already provides.

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 specific Time Off record by its ID,' clearly stating the verb, resource, and scope. It further distinguishes this tool from sibling list/create/update/delete tools by specifying 'Use this when you already know which time off record you want and need its full field set.'

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 gives explicit guidance on when to use the tool and points to resolving parent records with 'the matching list tool first,' effectively referencing an alternative. It also notes the config default for company_id. However, it doesn't explicitly state when NOT to use this tool (e.g., for listing all records), though this is implied by the 'single record' focus.

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