Post Instances Rfi

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, and openWorld=true. The description adds real value beyond those: it discloses that submission is standalone and does not change instance or onboarding status, and it specifies the error shape `{ success: false, reason }` with guidance to refetch rather than retry.

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?

Three front-loaded sentences, each carrying a distinct point: the action, the side-effect scope, and the error-handling behavior. Minor jargon ('Standalone:') and vague phrasing ('flat response object') keep it from a 5, but there is no filler.

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?

There is no output schema, and the description usefully covers the error return and the fact that submission has no status side effects. However, for a non-idempotent POST with a free-form nested requestBody and 0% schema coverage, the description leaves the agent without the payload shape it needs to call the tool correctly.

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 carry parameter meaning. It only calls the requestBody a 'flat response object' without naming any fields or expected keys, and it says nothing about the required instance_id beyond what the schema example and length constraints show. That is not enough to guide construction of a nested free-form request body.

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?

States a specific verb and resource: submit a flat response for the open instance RFI. It implicitly distinguishes the instance-level RFI from the customer-level sibling (PostV1InstancesCustomersRfi) by naming the instance scope, though it never explicitly names the alternative.

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?

Usage is implied: call this when an open instance RFI exists and needs a response. The description adds handling guidance for the no-pending-RFI case (refetch instead of retry), but it does not explicitly state prerequisites, when to prefer a sibling, or what happens if called with no open RFI beyond the error return.

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