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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description is consistent with them while adding real context: it returns a step-by-step walkthrough of screens and fields, and performs no action itself. The note about Housecall Pro's MAX-plan REST API is background rationale rather than behavior the agent needs. It does not describe the shape of the returned instructions.

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?

Sentences are long and clause-heavy, and the key fact ('opens nothing by itself') is buried mid-sentence rather than front-loaded. The final paragraph about the official REST API, MAX plan and a 'checked 14 Oct 2026' date does not change how the agent calls the tool and is largely wasted for a decision an agent has to make now.

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 zero parameters and no output schema, the description carries the return-value burden and does address it generically ('returns how to do it step by step – screens, buttons, fields'). It also points to the execution path via cotlet_browser_*. It leaves open whether the cloud browser must already be open on the Housecall Pro app and what details the agent must gather before driving the UI.

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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description needs to explain inputs, and none is misrepresented. One residual gap is that with no arguments the agent cannot know what job details (customer, address, schedule) it should supply when it moves to the browser tools.

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 opening clause 'Create job in the user's own Housecall Pro account' reads like a mutating job-creation tool, which is what the name and title imply, while the second sentence reveals it only returns step-by-step instructions and 'opens nothing by itself'. The true purpose (return a walkthrough for a job in Housecall Pro, to be executed via cotlet_browser_* tools) is stated clearly but only after the misleading lead. An agent skimming the first sentence could easily mis-select it.

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 usable sequencing guidance: call this to get the screens/buttons/fields, then perform the action with the cotlet_browser_* tools. It implicitly rules out expecting the job to be created here ('opens nothing by itself'). It does not compare against sibling onboarding tools like housecall_pro_create_estimate or housecall_pro_create_invoice, but the when-to-use path is clear.

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