Propose FHIR Write

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

The description goes beyond the annotations by disclosing critical runtime behavior: it requires an X-Step-Up-Token header supplied by the deployment, and the agent cannot obtain or pass it itself. It also specifies the exact return condition 'requires_step_up' when the token is absent and instructs the agent to inform the patient rather than attempt another route. The annotation readOnlyHint=true already covers the non-committing nature, but the description adds significant operational details, making behavior fully transparent.

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 well-structured and front-loaded with the core purpose ('Propose a write — validates the resource and returns a preview'). It then covers the non-commit behavior, the token requirement, and the contingency plan in a compact sequence. Every sentence earns its place, and it avoids fluff. It is slightly longer than strictly necessary but remains efficient and clear.

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 that there is no output schema, the description mentions that it 'returns a preview' but does not specify the structure or content of that preview. This could be a gap for an agent expecting to interpret the result. However, it does mention the error condition 'requires_step_up' and the necessary authorization context. For the tool's complexity (nested resource, single operation enum), the description is largely complete, but the lack of preview detail leaves it one step short of full completeness.

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 provides 100% coverage for both parameters (resource and operation) with clear descriptions and an enum for operation. The tool description does not add any additional meaning beyond the schema—it doesn't explain resource structure or operation options more deeply. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema already carries the semantic load.

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 states the tool's purpose: 'Propose a write — validates the resource and returns a preview.' This uses a specific verb (propose/validate) and resource (write) and distinguishes it from the committing sibling (fhir_commit_write) by explicitly noting it 'Does NOT commit.' The agent can immediately grasp what this tool does and how it differs from other write-related tools.

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 clear context on when to use the tool ('Propose a write') and notes that it does not commit, implying it is for previewing before an actual commit. It also explains the step-up token requirement and directs the agent on how to handle the 'requires_step_up' response. However, it does not explicitly name an alternative like 'use fhir_commit_write to actually commit,' relying on the sibling list and context signals to make that connection. This is a minor gap.

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