Get All Defect Line Items

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

Annotations already declare safety (readOnlyHint, destructiveHint), and the description adds useful behavior on error status codes and default values for company_id/project_id. However, the major behavioral gap is the contradictory return-type description (paginated list vs single JSON object), which undermines confidence in what the tool actually yields.

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 moderately long and front-loaded with the core action, but it contains a contradictory statement about the return value and some redundancy (e.g., 'Read-only' duplicates the annotation). It could be more concise and structured to avoid confusion.

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?

With 13 parameters and no output schema, the description must clarify the response format, but it gives conflicting signals (paginated list vs single object) and fails to explain pagination semantics. It does provide error codes and defaults, but the overall ambiguity leaves the agent poorly equipped to handle the tool correctly.

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?

The schema already provides 100% description coverage for all 13 parameters, so the baseline is 3. The description adds value by explaining the defaulting behavior for company_id and project_id via procore_set_config and by showing the URL path structure, which helps the agent understand parameter usage beyond the schema.

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 first sentence clearly states it returns a paginated list of defect line items across all defects, but the description then contradicts itself by saying it returns a single JSON object. The usage guidance also implies it is for a specific line item, which is inconsistent with the 'across all defects' scope. This muddies the purpose despite a generally clear opening.

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 offers a usage suggestion ('Use this when you already know which defect line item you want') but this conflicts with the tool's actual breadth of returning line items across all defects. No alternative tools are named or contrasted, leaving the agent without clear decision criteria for choosing this over siblings like get_defect_line_items_by_defect_id.

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