ghl_saas_remove_attached_config

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

Beyond the annotations it discloses the exact fields that get cleared, a state side effect (payment_pending set to false), the required Agency token, the OAuth scope, and the endpoint/version. It does not address repeat-call behavior, which matters since idempotentHint is false and the description never says whether a second call is a no-op or an error.

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?

Front-loaded with the action and its effect, followed by endpoint, auth and scope as supporting metadata lines. Four short segments, no filler; only the OpenAPI source citation is arguably noise.

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 mutation tool with no output schema, it covers what is removed, the precondition, auth, and scope. The one unresolved ambiguity is the 'and/or' wording versus a body that exposes only companyId — an agent cannot tell whether it can clear a plan without also clearing rebilling.

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% and both locationId and companyId are described with examples, so the schema carries the parameter burden. The description adds field-level meaning (what 'attached config' actually covers) but also names attachPlanId/attachPriceId, which are not parameters of this tool — a minor risk of the agent looking for a way to pass them selectively.

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 uses a specific verb ('clears') with concrete resources — attached SaaS plan fields (attachPlanId/attachPriceId) and rebilling config — plus the sub-account state it applies to (setup_pending) and the side effect on suspendedInfo.payment_pending. Very clear on what it does, but it never names a sibling (e.g. ghl_saas_allow_attach_rebilling, ghl_saas_update_rebilling) to differentiate itself.

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 states the eligibility condition (sub-account must be in setup_pending) and the caller requirement (Agency/company-level token, saas/company.write scope), which tells an agent when it can run. It does not, however, give any when-not condition or point to alternatives for the reverse operation (attaching rebilling).

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