List Correspondences

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

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description appropriately adds behavioral context: it explicitly states 'Read-only — it changes nothing in Procore,' and describes error payloads with common HTTP statuses (401, 403, 404). It also documents pagination behavior and the 'pages remaining' response reporting, going beyond the annotation coverage. A small deduction because it doesn't specify the exact structure of the error payload, but it provides substantial additional context.

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 information-dense but well-organized. It front-loads the primary purpose in the first sentence, then covers discovery/id lookup, parameter semantics, pagination, read-only guarantee, error handling, and API reference. Every sentence adds value, but it is somewhat long and could potentially be tightened. Still, the structure is logical and each sentence earns its place, so it stays in the 4 range.

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 read-only list operation with comprehensive annotations, complete schema coverage, and no output schema, the description covers everything the agent needs: purpose, usage, prerequisites, pagination, safety, error handling, required parameters, and even the API endpoint. The error status semantics address a common real-world need. No gaps are evident, making it complete for this tool's complexity.

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?

While the schema has 100% description coverage for all four parameters, the description adds important semantic context: it explains that project_id defaults to the value set by procore_set_config when omitted (a behavioral nuance not in the schema), and that bid_package_id must identify an existing parent record and should be resolved with a list tool. It also states 'Required parameters: project_id, bid_package_id,' confirming the two required fields. The pagination parameters are already well-documented in the schema, so the added value is in the contextual prerequisites.

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 clear verb+resource statement: 'Return a list of all Correspondences for a Bid Package.' It explicitly states the tool's purpose, scopes it to a specific parent entity, and distinguishes it from sibling tools that list other bid-related resources. The mention of looking up an id for subsequent tools adds practical 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?

The description explicitly states when to use this tool: 'Use this to discover correspondences or to look up the id of one before calling a tool that needs it.' It also gives a clear prerequisite: 'bid_package_id must identify an existing parent record — resolve it with the matching list tool first.' This provides concrete guidance and directs the agent to the appropriate alternative when the id is unknown.

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