square_create_refund

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

Annotations already signal a non-read-only, destructive, idempotent operation, and the description does not contradict them. It adds minor context about Spring verifying the claimed effect and approval_ref being used when resuming a write, which is useful, but it does not describe the actual financial consequence (issuing a refund) or any authorization/approval prerequisites in concrete terms.

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 compact and well-structured, with a short opening and a bullet-style Args list. It avoids verbose filler, though the parameter list largely mirrors information that could reasonably live in the schema.

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?

Since an output schema exists, the lack of return-value detail is acceptable. But the description is not sufficient for correct invocation: it does not explain what must go inside `arguments`, whether approval_ref is mandatory for this write, or what effect value should be claimed. For a mutating financial operation, these are significant gaps.

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?

With 0% schema description coverage, the description compensates by giving each top-level parameter a semantic role: idempotency_key is a "stable business-action identity," approval_ref is an "approved platform task UUID," and effect is a claimed read/write effect verified by Spring. However, the crucial `arguments` field is only described as a JSON string, with no Square create_refund fields (e.g., payment_id, amount_money, reason) specified, leaving the actual operation payload underspecified.

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 identifies this as the Square `create_refund` connector operation, and the tool name plus the Square prefix distinguish it from siblings like `stripe_create_refund`. However, it mostly restates the operation name rather than explicitly stating what creating a refund does (e.g., reversing a payment), so an agent must infer the actual purpose from the name.

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 only guidance is the routing constraint: "Routes only through the exact project/account governed connector authority." That is a scoping rule, not a when-to-use instruction, and no alternatives or exclusions are mentioned. The description does not help an agent decide between this tool and related Square or refund-management siblings.

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