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

With no annotations, the description carries the disclosure burden and does well: it states that the first term's invoice is created immediately, optionally sent via send_first, and that future invoices are created automatically and sent when auto_send is on. It also explains that visits_per_term creates service due dates. It omits permissions, reversibility, and failure behavior.

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 front-loaded with the purpose, then explains invoice lifecycle and visit due-date behavior in a tight sequence. Every sentence adds operational information, and there is no repetition or filler.

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 complex mutating tool with ten parameters, no annotations, no output schema, and low schema coverage, the description covers the core lifecycle: plan creation, first invoice behavior, recurring invoices, and service due dates. It still omits some invocation details such as term date semantics, tax defaults, and required permissions.

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 description coverage is only 30%, so the description needs to compensate. It adds useful meaning for lines, send_first, auto_send, and visits_per_term, including workflow implications, but leaves job_id, name, term_months, starts_on, tax_rate_id, and visit_title unexplained or only covered by sparse schema descriptions.

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 states a specific verb and resource: starting a maintenance plan for a job's customer (owner or office). It distinguishes the tool from siblings like maintenance_cancelPlan, maintenance_listPlans, and maintenance_setVisits by describing first-term invoice creation and automatic future-term invoices.

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 gives clear context for when to use the tool: setting up a plan for a job's customer and writing priced lines for one term. It also warns that lines are never filled in by AI and directs actual visit scheduling to visits.create and due-date viewing to services.listDue. It lacks explicit when-not-to-use guidance or named alternatives.

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