RALE Command (full; read + write)

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds value beyond them: every call surfaces as a toast in Dev Studio, the mixed read/write nature is spelled out ('the tool as a whole is not read-only'), and concrete destructive command examples are given. No contradiction with annotations; the description reinforces and extends them.

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?

Four sentences with no wasted words: purpose and destructive scope are front-loaded, followed by catalog pointer, toast behavior, and read/write routing advice. Every sentence earns its place and the structure moves from most critical (what it does) to supporting detail.

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 high-complexity dispatch tool with open-world semantics, no output schema, and a dynamic args object, the description provides strong coverage: destructive warning, catalog discovery path, side-effect visibility (toast), and sibling routing. It could note that output shape varies by command or describe error behavior, but the list_rale_builtins pointer substantially mitigates that gap for a generic runner.

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%, so the schema already documents all three parameters including the shape-dependent args object. The description adds a few illustrative command names (getNodeById, getRegistry, clearRegistry) and points to the args template in list_rale_builtins, but it doesn't add substantive parameter semantics beyond the schema — baseline 3 is appropriate.

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 opens with a specific verb and resource ('Run any built-in RALE command against the active App Connector session') and explicitly flags destructive capability. It differentiates from siblings by naming rale_get_node_by_id as the plain-read alternative and list_rale_builtins as the catalog source, so an agent can select it correctly without opening 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?

The description gives clear context: use this for any built-in command including destructive ones, consult list_rale_builtins for the catalog, and prefer rale_get_node_by_id for plain reads. It names an explicit exclusion (plain reads) and the alternative, though it doesn't enumerate when-not-to-use cases beyond reads or address overlap with other write-capable siblings.

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