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

The description goes well beyond the annotations by detailing side effects: sync is an idempotent replace of the source's own rows, rebind wipes rows from detached branches, update can re-fetch and re-stage, and `deletable_items` are proposed but never auto-deleted. It also states that credentials are never sent over MCP and that read-only keys are unsupported. These details give the agent a precise mental model of what the tool changes and what it preserves, with no contradiction against `readOnlyHint: false` or `destructiveHint: false`.

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 long and dense, but nearly every clause earns its place by covering an operation, a side effect, or an exclusion. It is front-loaded with the central `by op` concept and then expands each operation in a logical sequence. Minor readability cost comes from long parenthetical chains and run-on sentences, which prevents a perfect score.

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 complex three-operation tool with nested config, nine parameters, and no output schema, the description is remarkably complete. It tells the agent what each operation returns (`unmapped`, `proposed_window`, `deletable_items`, `cutover_changes`, `warnings`), references the sibling tool needed to pin a cutover, and clarifies both setup prerequisites and operational constraints. Nothing essential is missing for correct invocation.

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?

The input schema already provides 100% parameter coverage with detailed descriptions, so the baseline is strong. The tool description adds meaningful semantic context on top by tying parameters to operations (`branch_ids` to `rebind`, `target_branch_id` to `sync` for unbound connections, `config` to `update`) and by explaining consequential behavior like 're-fetches + re-stages' versus 're-project'. It does not need to repeat the schema's config-level details.

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-plus-resource statement ('Sync or reconfigure a data source') and then enumerates the three distinct operations (`sync`, `rebind`, `update`) with concrete meanings. It also differentiates itself from sibling tools by explicitly pointing to `layerz_delete_integration` for disconnecting a source, so an agent can distinguish when this tool is appropriate.

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 explains when each `op` should be used, including edge cases: `dry_run` for previews, `target_branch_id` for unbound connections, `rebind` for re-pointing to branches, and `update` for renaming or changing config. It explicitly names exclusions: new credentials should be set up in the web app, and the tool is unavailable to read-only API keys, which is strong usage guidance.

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