bw_area_get_xml

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this well: it states the active version (/a), explains the outputPath side effect (writes a file and returns a summary envelope), describes the raw-XML-versus-JSON distinction, and notes that pagination/projection is skipped when outputPath is set. This is substantial behavioral context beyond a generic 'get XML' statement.

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 concise and front-loaded with the core purpose. The second sentence, however, is somewhat cryptic and references a hypothetical future save tool, which slightly hurts clarity. It is compact but not perfectly clean.

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 read-only get-style tool with three parameters, no output schema, and no annotations, the definition is complete enough for an agent to invoke it correctly. It covers what the tool returns, how format affects inline responses, when to use outputPath, what the outputPath envelope contains, and how this tool fits into the broader get_xml family. No critical invocation details are missing.

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 already covers all three parameters with descriptions, so the baseline is 3. The tool description adds meaningful extra semantics: it reveals that the returned XML is the active version (/a), advises preferring outputPath, and hints that output can later be reused as xmlPath. Those additions justify one point above the baseline.

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+resource+output: "Get InfoArea raw XML (active version /a)." This makes the tool's purpose immediately clear and scopes it to a particular object type (InfoArea) and output format (raw XML), distinguishing it from create tools and from get_xml tools for other object types like ADSO, transformation, and DTP.

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 explicit usage guidance: "Prefer outputPath," and clarifies that create tools use structured parameters rather than raw XML. The outputPath schema description adds strong routing guidance, telling agents to use the matching bw_*_get_xml family when raw XML is needed versus parsed XML-to-JSON tools. However, the guidance about "Reuse as xmlPath only if a future save tool is added" is conditional and speculative, so it is not a fully crisp when-to-use vs. when-not-to-use statement.

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