Creates A New Direct Issue Document.

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses key behaviors: line items auto-expand from inventory, company_id/project_id default from procore_set_config, HTTP 201 with new id, non-idempotency, and common error statuses (401, 403, 404). This gives the agent a full picture of what to expect.

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 well-structured with the core action first, followed by key behaviors, error handling, and endpoint info. It's slightly dense but each sentence contributes value without unnecessary fluff.

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 the tool's complexity (6 parameters, no output schema), the description covers the essential behavior: creation semantics, line item expansion, defaults, non-idempotency, errors, and endpoint. It doesn't detail the return payload beyond the new id, but the lack of an output schema makes that acceptable. Overall, it's quite complete.

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 provides 100% coverage with generic descriptions, but the tool description adds meaningful semantics: it explains that company_id and project_id default from config, and that item_ids drive automatic line item expansion. This goes beyond the schema's generic 'JSON request body field' labels.

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 'Creates a new Direct Issue document', clearly stating the verb and resource. It further specifies that line items are automatically expanded, distinguishing it from related tools like adds_line_items_to_an_existing_direct_issue. The purpose is unmistakable.

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 clear usage context: it defaults company_id and project_id from config, warns that calling it again creates another record, and notes required parameters. It implies this tool is for new document creation, and the automatic line item expansion tells the agent when this tool is appropriate. It doesn't explicitly name alternatives, but the context is strong enough.

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