write_fhir_resource

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

With no annotations provided, the description carries the full burden and does well by detailing steps like validation, endpoint determination, and error handling. It discloses behavioral traits such as validation using fhir-validator and handling of errors, which are beyond basic functionality. However, it misses some details like rate limits or authentication requirements, preventing a perfect score.

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 with bullet points and sections for Args and Returns, making it easy to scan. It's appropriately sized with no redundant information, but the bullet points could be more concise, and some sentences are slightly verbose (e.g., 'Returns validation errors or server errors for correction').

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 the tool's complexity (write operation with validation and custom headers), no annotations, and an output schema present, the description is mostly complete. It covers purpose, steps, parameters, and returns, but could benefit from more details on error types or success conditions, especially since the output schema exists but isn't described in the text.

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 must compensate. It adds meaning by explaining that 'resource' is a FHIR resource as a JSON object and 'custom_headers' is optional with a specific example for Zus servers. This provides practical context beyond the schema's basic types, though it could elaborate more on resource structure or header constraints.

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 writes a FHIR resource to a FHIR server, specifying the action (write) and resource (FHIR resource). It distinguishes from sibling tools like read_fhir_resource and search_fhir_resources by focusing on creation/update. However, it doesn't explicitly differentiate from potential siblings like update_fhir_resource or create_fhir_resource if they existed, keeping it at 4 instead of 5.

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 implies usage for writing FHIR resources, with a note about Zus servers for multi-tenant access, suggesting context-specific application. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., no mention of when to use POST vs. PUT or how it differs from sibling tools like read_fhir_resource). The guidance is present but not comprehensive.

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