fabric_connector_patch

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 so thoroughly. It discloses that this is a gated mutation, requires a specific environment variable, is experimental, and follows a read-before/write/read-after pattern with noOp detection. It also warns that a 200/204 on a probe is a stop condition, not a success. This is exemplary behavioral disclosure for a high-risk operation.

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 dense but every sentence carries safety- or usage-critical information. It front-loads the core action and mutation status, then logically progresses through gating, operational pattern, probe instructions, and references. The only minor issue is slight redundancy between 'MUTATION — GATED' and the explicit refusal condition, but this emphasis is justified for a destructive operation.

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 complexity and risk, the description covers all needed context: gating requirement, environment variable, experimental status, read-before/write/read-after pattern, noOp detection, legacy route probing, and pointer to shared semantics. An output schema exists, so return value details are not required. The agent has enough to decide whether and how to call this tool safely.

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 explains 'body: the JSON request body' and that confirm must be true. For host/path/site/scope, it explicitly defers to fabric_connector_get, which is acceptable reuse of shared semantics. While not every parameter is described inline, the delegation and key requirements give an agent enough to understand the parameters.

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 opens with a specific verb and resource: 'Relay a PATCH (partial update) through the Fabric connector.' It clearly identifies the operation as a mutation and distinguishes it from siblings by naming the GET twin and pointing to fabric_connector_put and fabric_connector_get. This gives an agent a precise understanding of what the tool does and how it differs from 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 gives explicit conditions: 'Refused unless BOTH confirm=true AND UNIFI_ENABLE_CONNECTOR_WRITE are set.' It also explains the read-before/write/read-after pattern and defers to fabric_connector_get for host/path/site/scope semantics. It even provides a probing procedure for the legacy route, including a stop condition. This is far beyond minimal usage guidance.

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