List All Prime Contracts

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: it returns a JSON array, explains pagination ('page and per_page control pagination and the response reports how many pages remain'), and enumerates common error statuses (401, 403, 404). It also reaffirms the read-only nature ('Read-only — it changes nothing in Procore') which aligns with annotations, adding context about side effects.

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 starts with the core action, then adds a link for filters, the primary use case, return format, pagination, read-only note, error behavior, required parameter, and API context. Each sentence serves a distinct purpose without unnecessary repetition. It's appropriately sized for a list endpoint with pagination and filtering considerations.

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?

Given there is no output schema, the description sufficiently explains what the caller gets (JSON array), how to control pagination (page/per_page), common error responses, and the read-only nature. It also points to filtering documentation for advanced usage. This makes the tool feel self-contained and well-documented.

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% (all parameters have descriptions). The description adds semantic value by noting that project_id is required and that page/per_page control pagination, plus the filtering capabilities are referenced. It also clarifies the response's pagination behavior, which goes beyond the schema's basic parameter descriptions.

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: 'Returns all Prime Contracts for the specified Project.' It distinguishes from siblings by emphasizing 'all' and by stating a key use case: 'discover prime contracts or to look up the id of one before calling a tool that needs it.' This clearly identifies the tool's scope and differentiates it from more specific tools like show_prime_contract.

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 provides a clear usage scenario ('Use this to discover prime contracts or to look up the id of one before calling a tool that needs it') and notes the filtering capabilities link. It doesn't explicitly name an alternative tool to use when the id is already known, but the implication is strong enough. Also, the read-only statement helps set expectations for when it's safe to call.

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