bw_trfn_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. It discloses key behavioral traits: outputPath writes full XML to disk, inline responses vary by format, the tool skips inline pagination/projection when outputPath is set, and the raw XML file is directly reusable as xmlPath. It also clarifies a subtle family-wide behavior (only bw_*_get_xml writes raw XML as plain text). Minor gap: it doesn't state whether the operation is read-only or has side effects, but the description strongly implies a read operation.

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 dense but well-structured: the core instruction is front-loaded ('ALWAYS prefer outputPath'), followed by mode explanations and a family clarification. It is longer than average, but every sentence adds distinct value; the outputPath paragraph is verbose but necessary to disambiguate a critical behavior.

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 tool with 4 params, no output schema, and no annotations, the description covers the essential decision points: when to use outputPath, what each format returns, what the version enum means, and how the result feeds into save_and_activate. It doesn't describe the exact inline response structure for format='xml' or 'summary', but the outputPath envelope is described. The read-modify-write context is clear.

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 75%, and the description adds significant meaning beyond the schema: it explains the format enum's effect ('Only affects inline responses'), the version enum's meaning (m/a/d), and the outputPath behavior in detail (writes full result, returns summary envelope, skips pagination/projection). The id parameter is not elaborated, but it is a required identifier and self-evident.

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 states a specific verb ('Get raw transformation XML') and resource ('for PUT updates'), and immediately distinguishes it from sibling tools by naming the bw_*_get_xml family and contrasting with other *_get tools. It also frames it as 'Step 1 of read-modify-write', which clearly positions its role.

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 when-to-use guidance: 'ALWAYS prefer outputPath', explains the two modes (with/without outputPath), and explicitly names the alternative family (bw_*_get_xml vs other *_get tools) and the downstream consumer (bw_trfn_save_and_activate). It also tells when to use outputPath (large responses).

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