xae

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

With no annotations, the description discloses important behavior: open_solution's closeExisting/discardChanges semantics, error_list's default limit and filter-before-cap behavior, dialog_probe being read-only, and dialog_resolve's auto-remember refusal for destructive prompts. However, it remains silent on side effects for actions like save_all, clear_error_list, and list_commands.

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 description is a single dense paragraph that packs a lot of vital behavioral detail, but the lack of structure (e.g., bulleted actions) makes it hard to scan. Every clause earns its place, yet formatting could dramatically improve readability.

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 10-parameter, multi-action tool with no output schema, the description thoroughly documents open_solution, error_list, dialog_probe, and dialog_resolve, but omits expected return values or side effects for status, save_all, active_document, selected_items, clear_error_list, and list_commands. This leaves significant gaps for the agent to infer.

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?

The schema covers only 20% of parameters with descriptions; the text compensates by explaining solutionPath, closeExisting, discardChanges, limit, severityFilter, filter, button, and remember within the context of their actions. This embedded documentation adds practical meaning (e.g., severityFilter 'errors'|'warnings' with true total count) beyond the bare schema enum.

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 clearly identifies the tool as an 'XAE shell' command dispatcher, enumerating the distinct operations it supports (status, open_solution, error_list, dialog_probe, etc.). It differentiates from sibling tools by listing these shell-specific actions, though it lacks a single declarative sentence stating the tool's core purpose (e.g., 'Execute XAE shell commands').

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 provides use-case context for individual sub-actions (e.g., dialog_probe checks for a blocking modal, dialog_resolve clicks the chosen button), but it does not explain when to use this tool over specialized siblings like xae_build, tc_system, or plc_download. There is no explicit guidance on when not to use it or which alternative to pick for a given scenario.

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