xae_build

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real behavioral context beyond them: save_first runs File.SaveAll and refuses to build if session edits are not persisted in source files, plus what the result contains (error/warning items with file:line, output tail). The link_check behavior is disclosed but the mechanism is left ambiguous.

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 is front-loaded in the first two words, and each subsequent sentence carries information (guard behavior, return shape, alternative mode, link diagnostics). It is dense and somewhat parenthetical-heavy, but no sentence is pure filler.

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?

With an output schema present the description need not re-explain return values, yet it does so usefully. The real gap is that two of four parameters (clean, rebuild) are undocumented and the link_check reference is orphaned from the schema, leaving an agent uncertain about non-default configuration.

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 0%, so the description carries the burden of explaining the four parameters. It explains save_first and check_all_objects well, but clean and rebuild are never mentioned, and it references a "link_check" behavior that has no corresponding parameter, which could confuse an agent about what is configurable.

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 opening "Build the solution" states a specific verb and resource, and the surrounding detail (VS error list / Build output pane, PLC compile semantics) makes it unmistakably the build tool among siblings like xae_command or proj_lint. An agent can identify it without opening the schema.

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 contrasts the default save_first path with check_all_objects=true, which is genuine selection guidance, but it frames these as internal options rather than telling the agent when to reach for xae_build versus alternatives such as xae_command or xae_plc. No exclusions or prerequisites for invoking it are given.

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