publish_model_choices

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

Beyond the annotations (destructive, non-idempotent), the description discloses real behavior: publishing bundles other pending changes to this global choice, it does not replay a save, and it does not verify UI behavior. These are non-obvious side effects and limits. It stops short of describing the response or the eligibility checks performed during preview.

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?

Purpose and scope come first, followed by sibling routing and behavioral caveats; each sentence carries content. Some jargon ("native PublishXml", "never replays a save") costs clarity without adding much, but there is no filler.

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 mutation with no output schema, the description covers preview defaults, bundled side effects, and sibling routing, which is solid. It omits prerequisites (publisher/solution context, permissions) and gives no hint of what a preview or publish returns, leaving the agent to discover that empirically.

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 two dryRun/dry_run parameters are already fully described in the schema, and the only description statement about them ("Default preview") merely repeats that. The choice-name parameters have no schema description at all, and the split into global_choice_name/globalChoiceName aliases plus the anyOf required pattern is never explained, so the description does not compensate for the 50% coverage gap.

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 states a specific verb and resource ("Publish one entire shared global choice") and scopes it to the global-choice case, explicitly distinguishing it from the sibling publish_model_table that handles local choices. An agent can tell the two publish tools apart without inspecting either 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?

It names the alternative tool and the condition that routes to it (local choices -> publish_model_table), and notes that the default is preview, so an agent knows execution requires an explicit change. It doesn't spell out the typical trigger (e.g., publish after create/update of choices), leaving some inference.

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