Create Plan Revision Log

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

The description goes well beyond the annotations by disclosing non-idempotent behavior, the successful HTTP 201 response shape, and common failure payloads (401/403/404). It also explains the project_id defaulting behavior and attachment upload nuances, giving the agent a clear behavioral model.

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 dense but includes several distinct pieces of information: purpose, link to guide, default behavior, idempotency, error semantics, required parameters, and endpoint. It is not as lean as it could be, but every sentence contributes useful operational detail.

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 lack of an output schema, the description adequately covers return value, error cases, required parameters, and non-idempotency. It does not enumerate the fields of the nested plan_revision_log object, but the schema and linked guide partially compensate for that.

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%, so the baseline is 3, but the description adds value by noting project_id defaults to the procore_set_config value and explicitly listing required parameters. It also links to the Daily Log guide for attachment details, which helps with the complex plan_revision_log object.

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 single Plan Revision Log,' a specific verb and resource, and clarifies that each call creates a distinct record. It also identifies the Procore API endpoint, distinguishing this create operation from sibling list/update/delete plan revision log tools.

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 creates one plan revision log, returns the new record with its id (HTTP 201), and warns that calling it again creates another record. It does not explicitly name alternatives, but the create-vs-list/update/delete distinction is evident from the endpoint and behavior.

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