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

Goes meaningfully beyond the annotations: the job is auto-numbered, starts Unassigned, contact/phone/site_address are inherited from the customer, and critically 'It reaches no one and stays inside Tradify' tells the agent no notifications are dispatched. It does not explain the idempotency implication of auto-numbering (duplicate calls create duplicate jobs), which is the main remaining gap.

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 first three sentences say the same thing twice ('New job for a customer. It starts as Unassigned.' followed by 'Creates a job for a customer, as New Job does... It starts Unassigned'), and the 'as New Job does' aside references something the agent cannot see. Restatement crowds out the details that would actually help.

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 no output schema, the description should say what comes back — particularly the new job's identifier, since the agent needs it to call schedule_appointment or update_job_status next. That is missing, though the creation semantics (state, numbering, inheritance) are otherwise adequately covered for a 6-param creation tool.

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 schema already documents all six parameters including defaults for contact, contact_phone and site_address. The description restates the defaulting rule but adds no format, constraint, or interaction detail beyond the schema; 'reference' and 'description' are untouched. Baseline 3 applies.

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?

States a specific verb and resource ('Creates a job for a customer') and pins down the initial state ('starts as Unassigned') and numbering behavior, which distinguishes it from siblings like create_quote or schedule_appointment. The opening fragment 'New job for a customer. It starts as Unassigned.' is then largely restated, but the substance is unambiguous.

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?

It points forward to schedule_appointment ('books staff on it'), which implies the natural next step, but never says when to prefer create_job over create_quote/from-quote paths or what preconditions exist (e.g. customer must already exist). Usage 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.