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, stating plainly that it 'opens nothing by itself.' Beyond that it discloses the return shape (screens, buttons, fields) and the external constraint that Housecall Pro's REST API is MAX-plan only with a limited-access key, which is real context an agent cannot get from structured fields. It stops short of saying what happens if the user is not logged in or lacks a Housecall Pro account.

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 critical fact — that this returns instructions and performs nothing — is buried in the second sentence after a first sentence that reads like a write operation. The API-plan note is useful rationale but is phrased as a digression with a verification date, adding length without changing how the agent calls the tool.

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 parameters, no output schema and a simple guide-returning behavior, the description covers what the agent needs: what comes back, that nothing is executed, and which tools to use next. The main gap is prerequisites (signed-in Housecall Pro account, Cloud Browser availability) before the follow-up browser calls will work.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies the call is argument-free by describing it as a lookup of guidance rather than an operation requiring invoice data.

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 the resource (an invoice in the user's own Housecall Pro account) and, crucially, clarifies that the tool returns a step-by-step how-to rather than performing the action. That correction is specific and distinguishes it from a real mutation tool, though the opening sentence ('Create invoice... from ChatGPT, Claude or any AI agent') briefly reads like an action and creates friction before the clarification lands.

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 an explicit workflow: call this to get the steps, then execute them with the cotlet_browser_* tools in the user's Cloud Browser. It also explains why direct API access is not an option (MAX plan, limited-access key), which implicitly justifies this route. It does not explicitly say when to prefer this over sibling tools like housecall_pro_create_estimate or housecall_pro_send_invoice, but those are clearly different resources.

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