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

Goes beyond the annotations by explaining that the same tool is effectively read-only in one invocation shape and destructive in another, and by stating the guard (confirm_change) for Pixel/site switches, which directly explains the destructiveHint=true. Minor tension between 'read-only' wording and readOnlyHint=false, though the conditionality makes it consistent rather than contradictory; prerequisites like 'connected project' are asserted but not defined.

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?

Four tight sentences, each carrying distinct information, with the discover-vs-configure fork stated first and the guard/exclusion following. No repetition of schema or annotation content.

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?

With no output schema, the description usefully indicates that the read-only path 'returns setup guidance', and it covers the mutation path's guard. It leaves gaps on what happens with an unknown/invalid pixel_id or what a 'connected project' prerequisite actually requires before calling.

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 coverage is 100%, so the baseline is 3, but the description adds real relational semantics the schema cannot: pixel_id only triggers a save on a connected project, and confirm_change governs switching an existing Pixel or site. It does not clarify checkout_domains or the name default beyond what the schema already states.

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?

'Discovers or configures reviewed v2 setup for a site' gives a specific verb pair and resource, and the dual-mode explanation makes the tool's identity concrete. It never names a sibling (e.g. setup_status, check_live_setup) it should be preferred over, so differentiation is inferential rather than explicit.

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 clearly splits usage by input: URL-only for guidance, real Pixel ID on a connected project for saving, and confirm_change when switching. 'Does not approve, install or activate tracking' is an effective exclusion but the alternative tools it defers to (approve_*, verify_install) are not named.

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