ghl_clientportal_get_app_customization

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

Adds genuinely useful state semantics (revision vs. appliedRevision vs. status, and that 409 means a cloud build owns the sandbox or it isn't running). But the leading 'side-effecting: opens/edits sandboxes and starts builds' text belongs to sibling sandbox tools and risks making an agent think this read-only getter mutates state — noise that partially works against the readOnlyHint.

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 sentence is buried behind a paragraph of sandbox/checkpoint/409 guidance that does not apply to a GET. Several sentences (edit only when ready, checkpoint after edits) earn no place in this tool's definition and dilute the front-loading.

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?

Read-only with a single param and no output schema, so the main missing element is what the response contains; the description only implies revision/appliedRevision/status fields through the publish rule. Adequate but not fully sufficient for an agent that must decide what to do with the result.

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?

One parameter (projectId) with 100% schema description coverage and a documented pattern, so the schema does the work. The description adds no format detail beyond the URL template, which is the expected baseline here.

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 specific verb+resource: 'Get which revision of an app is newest, applied and published', and names the endpoint GET /ai-builder-api/projects/{projectId}/app-config. It is distinguishable from the sibling publish_app_customization, though the opening line about sandbox editing is about the API family rather than this operation.

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 real sequencing guidance: check this after a run, then publish with POST .../app-config/publish only when `appliedRevision` equals `revision` and `status` is `ready`. It names the follow-on tool's endpoint and the precondition, though it never explicitly says when NOT to call this getter.

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