processDefinition_getXmlByKey

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

No annotations are provided, so the description carries the full disclosure burden. It adds valuable behavioral context by specifying 'latest deployed version' (indicating version selection behavior) and 'BPMN 2.0 XML source' (format). However, it omits operational details like whether this is read-only (implied by 'Retrieve' but not stated), idempotency, or potential errors.

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?

Single sentence with no waste. Front-loaded with the action verb. Every phrase earns its place: 'BPMN 2.0 XML source' specifies format, 'latest deployed version' specifies version scope, and 'by key' specifies the identification method.

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?

Given no output schema exists, the description reasonably covers the return value by specifying 'BPMN 2.0 XML source'. It adequately handles the domain complexity (BPMN/process definitions) by mentioning the specific standard and deployment version. Could be improved by explicitly stating the return type (string vs object).

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 input schema contains zero parameters (baseline 4 for empty schema). The description compensates by specifying 'by key', which implicitly signals that a process definition key is required for operation, adding semantic meaning that the empty schema fails to convey.

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 uses a specific verb ('Retrieve') and clearly identifies the resource ('BPMN 2.0 XML source'). It distinguishes scope ('latest deployed version') and methodology ('by key'), clearly differentiating it from siblings like processDefinition_getXmlById (by ID) and processDefinition_getByKey (likely returns metadata, not XML source).

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 implied usage through the 'by key' and 'XML source' qualifiers, distinguishing it from siblings. However, it lacks explicit guidance on when to prefer this over processDefinition_getXmlById or processDefinition_getByKey, and does not mention prerequisites like needing the process definition key.

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