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

Beyond the destructive/openWorld annotations, it discloses the concrete side effect ('moves the staged file into place'), the blocking behavior ('nothing runs before this call succeeds'), and an auth requirement ('Requires creator scope') — all things annotations cannot convey. It also warns that the audience_id path has no inference fallback, which is real behavioral risk information.

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 purpose and the approval prerequisite are front-loaded, then the branching rules follow in order of decision. Sentences are dense with constraints rather than filler, and nothing is repeated except the ordering rule, which is reinforced for safety.

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 destructive, non-idempotent staging tool with an output schema, the description covers preconditions, ordering, scope, and branch-specific parameter rules. The one gap is retry/re-entry behavior: it does not say whether calling again after a partial failure is safe or what happens to the staged file, despite the non-idempotent and destructive hints.

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; the description earns extra credit by adding the mutual-exclusivity constraint between segment_id and audience_id (not encoded via oneOf in the schema) and by explaining the server-side resolution of audience_id to a matched member segment. Most of the column_mappings requirements, however, are already duplicated in the schema property description rather than added here.

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?

Names a specific verb and resource ('Confirm column mappings for a staged matched-segment upload') and states the downstream effect ('starting identity resolution'). This distinguishes it cleanly from analyze_audience_upload (preview) and wait_for_segment (polling), so an agent can place it in the workflow without opening any schema.

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?

Gives explicit preconditions ('Call this after analyze_audience_upload has been reviewed with the user and they approve'), explicit sequencing ('Only call wait_for_segment after this returns ok'), and an exclusivity rule ('Pass exactly one of segment_id or audience_id') with a decision rule for which branch to pick.

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