ghl_clientportal_publish_app_customization

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

Beyond the annotations, it discloses side-effecting nature, the sandbox status=ready gate, checkpoint ordering, what 409 means, and the required OAuth scope clientportal-ai.write. However, the opening lines ('opens/edits sandboxes and starts builds') belong to the broader API and may mislead an agent about what this specific publish endpoint does.

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 purpose and alternatives are front-loaded and useful, but the tool carries a large generic API preamble (sandbox edit/checkpoint rules, endpoint/Swagger source) whose relevance to a publish call is unclear, adding noise an agent must filter.

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 side-effecting publish operation with no output schema, it covers prerequisites, platform branching, the sibling alternative, and auth scope well. It does not describe what the publish call returns or how to confirm success, which is a minor remaining gap.

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% so the schema already documents both fields, but the description adds real meaning: mobile installs over the air, the revision must come from app-config once appliedRevision matches and status is ready, and the platform default of web selects ClientPortal config apps.

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 core sentence 'Publish a saved revision of an app to its members' states a specific verb and resource and distinguishes web vs mobile publishing. The surrounding API preamble about opening/editing sandboxes and starting builds describes other sibling operations rather than this tool, slightly blurring its identity.

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 explicitly names when to use mobile ('send platform: mobile') versus the default web, and names the alternative for coded web apps ('publishes with POST .../promote-to-production'). The revision source (GET .../app-config) and APK dependency for agent-written screens are spelled out.

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