Creates A New Shipment.

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

Annotations already indicate a non-read, non-idempotent, non-destructive operation. The description adds useful context: it details success and error return types (200 OK with shipment details, error payloads with 401/403/404 statuses), and reveals that omitted company_id and project_id default to procore_set_config values. This goes beyond the annotation hints and gives the agent a clearer picture of expected outcomes and failure modes.

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 contains several pieces of useful information (endpoint, error codes, defaults) but also includes filler like 'Acts on the shipment and returns Procore's response for the operation,' which is vague and not informative. The sentence 'This method handles HTTP POST requests' is redundant given the endpoint specifies POST. It could be tightened without losing meaning, but it is not excessively long and is reasonably structured with the endpoint at the end.

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?

The tool has no output schema, so the description correctly states that successful creation returns shipment details and errors return status payloads. It also covers the API version and resource module (Procore API v2.0, Resource Management > Materials Management) and the exact endpoint. It does not explain the request body structure in detail, but the schema fully covers that. For a create operation, this is a fairly complete description, though it could mention potential side effects or prerequisites beyond the ones already disclosed.

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 baseline is 3. The description adds value beyond the schema by stating that company_id and project_id are required and can default to procore_set_config values, which is not present in the schema. However, it does not elaborate on the other request body fields (e.g., name, vendor, properties), but those are already described in the schema, so the extra defaulting info justifies a score above baseline.

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 identifies the tool as creating a shipment via HTTP POST, specifying the exact endpoint and success criteria ('successful creation returns a 200 OK response with the shipment details'). It names the resource (shipment) and the verb (POST), which aligns with the tool name and title. It also distinguishes this from read or update operations by stating the method and the creation outcome.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or preferred scenarios. It provides some usage context by noting that company_id and project_id default to procore_set_config values and listing required parameters, but it lacks direct guidance on choosing this tool over sibling shipment-related tools like get_all_shipments or updates_properties_on_a_single_shipment.

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