fabric_connector_put

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

There are no annotations, but the description fully discloses behavioral traits: the tool is gated and refused unless both confirm=true and UNIFI_ENABLE_CONNECTOR_WRITE are set; it does a read-before and read-after the write; the result carries readBefore / readAfter / noOp, with a diff-based noOp flag for identical writes; and it is marked EXPERIMENTAL for undocumented legacy routes until persistence and rollback are proven live.

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 yet information-dense, leading with the core action and safety gate, then the read-before/after behavior, then an example usage, then a scope guard, then the experimental caveat, and finally a pointer to the sibling for parameter semantics. Each sentence earns its place without repetition.

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?

For a generic relay tool with no annotations, it covers the critical operational context: mutation risk, gating requirements, scope guard, experimental status, and where to find parameter semantics. It also references an output schema to handle return values, so nothing necessary for an agent to safely invoke it is missing beyond the cross-referenced sibling details.

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 burden is on the description. It explains that host/path/site/scope semantics are covered by sibling fabric_connector_get and that 'body' is the JSON request body. It names the confirm parameter as a required safety gate. It does not individually document each parameter with syntax details, but combined with the cross-reference, it provides enough meaning for a generic relay tool.

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 explicitly states 'Relay a PUT (full replace) through the Fabric connector' and differentiates it from 'fabric_connector_get', 'fabric_connector_post', 'fabric_connector_patch', and 'fabric_connector_delete' siblings. It also clarifies that PUT has a GET twin at the same resource path, making its purpose distinct from other mutation 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?

It gives explicit when-to-use guidance: 'Use this for reversible per-device config probes' with an example, and defines exclusion constraints ('scope='device' guards against selecting a site-global setting route', 'Refused unless BOTH confirm=true AND UNIFI_ENABLE_CONNECTOR_WRITE are set'). It also cross-references fabric_connector_get for host/path/site/scope semantics, clearly routing the agent.

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