Get Receipt Change History

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: failure modes (401/403/404), defaulting behavior for company_id/project_id via procore_set_config, and explicit confirmation that it is read-only. It also notes the output shape ('single JSON object describing the receipt change history'). No contradiction with 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 longer than minimal but every sentence provides useful information: purpose, usage context, defaults, error handling, and endpoint. It is front-loaded with the core purpose. Minor redundancy exists between 'paginated list' and 'single JSON object', and the required-parameters line repeats schema info, but overall it is well-structured and not verbose.

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 tool with 7 parameters, filtering, pagination, and no output schema, the description covers the essential usage context: what it returns, prerequisites, defaults, error behavior, and the specific API endpoint. It does not detail the exact fields within each history entry or pagination defaults, but the schema covers page/per_page and the core behavior is sufficiently described.

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 the baseline is 3. The description adds meaning beyond the schema by explaining that company_id and project_id default to procore_set_config values when omitted, and that id must identify an existing parent record, resolving it with the list tool first. This clarifies the required path parameters better than the schema alone.

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+resource: 'Returns a paginated list of change history events for the specified receipt.' It clearly states what the tool does and what each entry contains (what changed, when, who), distinguishing it from siblings by explicitly scoping to receipt change history.

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?

Provides context: 'Use this when you already know which receipt change history you want and need its full field set.' Also gives a prerequisite: 'id must identify an existing parent record — resolve it with the matching list tool first.' However, it does not explicitly name alternative tools for other change-history types (e.g., purchase orders), so no exclusions are given.

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