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

Goes well beyond the annotations by disclosing the destructive consequence: stopping parks the client service, which detaches phone numbers from the voice agent under the existing parking policy. This concretely explains what destructiveHint=true means in practice, and the permission requirement is stated. The idempotent behavior is consistent with a set-to-value operation and nothing contradicts the annotation profile.

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?

Three tight sentences, front-loaded with the primary action before the conditional stop behavior, then preconditions, then side effects. Every sentence carries distinct information: operation, authorization, and consequence.

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 three-parameter mutation with an output schema, the description covers the gaps that matter: required role, preconditions for the start path, and the collateral damage of the stop path. Return values need not be explained because an output schema exists.

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 100%, and the schema already documents that plan is a partner plan key or null to stop the client plan. The description restates that null means stop but adds no format, sourcing, or validation detail beyond the schema, so the 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 concrete verb and resource: it puts a partner-created client on an agency-billed plan, and the inverse operation (stop) is defined in the same sentence. The plan=null condition makes the two modes unambiguous, so an agent can distinguish this from sibling billing tools like agency_billing_set_automatic_collection or agency_billing_setup_collection without opening their schemas.

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?

Gives explicit prerequisites: the caller must be an agency owner who is also a client admin, and starting a plan requires accepted terms plus a ready collection method. That is strong when-to-use context. It does not explicitly name a sibling alternative for cases where those preconditions fail (e.g. accepting terms via agency_billing_accept_terms), so it stops short of full routing guidance.

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