List Alternative Response Sets

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description explicitly states 'Read-only — it changes nothing in Procore,' reinforces safety. It adds critical behavioral details about pagination ('page and per_page control pagination and the response reports how many pages remain') and error handling (HTTP statuses 401, 403, 404). These details are not present in the annotations and materially improve the agent's understanding of runtime behavior.

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 a single, well-organized paragraph of about five sentences. Every sentence serves a purpose: purpose, use case, defaults, pagination, read-only guarantee, and error semantics. It is information-dense but not bloated, with key facts (id lookup, pagination, error payload) front-loaded where relevant.

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 this is a simple list tool with no output schema, the description covers all necessary context: return format (JSON array), pagination control and remaining-pages indicator, error response structure with common status codes, required parameter, default parameter behavior, and the underlying Procore API endpoint. This is comprehensive for the tool's complexity and annotation richness.

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 three parameters have descriptions), so the baseline is 3. The description adds value beyond the schema by explaining the company_id default ('defaults to the value set by procore_set_config when omitted') and the effect of page/per_page on pagination results. This enriches parameter understanding without repeating schema definitions.

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 clearly states the tool's function: 'Lists Alternative Response Sets for a specified Company.' It also distinguishes its discovery utility: 'Use this to discover alternative response sets or to look up the id of one before calling a tool that needs it.' This is a specific verb+resource pair with clear scope, differentiating it from siblings that operate on other entities.

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 use case: 'Use this to discover alternative response sets or to look up the id of one before calling a tool that needs it.' It also notes the default behavior of company_id, which helps an agent decide when to rely on configuration versus explicit input. However, it does not explicitly name an alternative tool or state when not to use this tool, so it falls just short of full guidance.

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