Create A New Classification

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

The description explicitly states that calling the tool again creates another record (non-idempotency), which goes beyond the idempotentHint:false annotation by explaining the consequence. It also discloses payload transformation (top-level arguments nested under work_classification), the project_id default, success response with HTTP 201 and new id, and common error statuses (401, 403, 404). This is substantial behavioral context beyond what annotations provide, with no contradictions.

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 compact and front-loaded with the core purpose. Each subsequent sentence adds a distinct, valuable detail (payload handling, defaulting, non-idempotency, error behavior, required parameters, API reference). No wasted words or repetition of schema fields.

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 create tool with no output schema, the description covers the essential ground: what is created, the scope, required parameter, response format (201 + new id), non-idempotency, and error scenarios. The schema and annotations fill in the remaining parameter details. The inclusion of the endpoint and API location provides enough context for an agent to integrate without needing additional documentation.

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?

With 100% schema coverage, the schema already describes each parameter. The description adds critical usage semantics: that fields are passed as top-level arguments (and nested in the payload automatically), that project_id defaults to the configured value when omitted, and that project_id is required. This clarifies how to invoke the tool and reduces ambiguity around payload structure.

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-resource pair ('Create a new classification associated with the specified project'), clearly indicating scope (project-level) and distinguishing from other classification tools by emphasizing project association and the endpoint path. It also explicitly notes that repeated calls create new records, further clarifying its non-idempotent creation semantics.

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 conveys usage context through the project association and the required project_id parameter, plus the default behavior from procore_set_config. It does not explicitly name alternative tools, but the project-scoped endpoint and 'associated with the specified project' make it clear when to choose this over company-level classification tools. Some guidance on when not to use it is implied rather than stated.

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