publish_agent_marketplace_action

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses stale-contract rejection, permission/tier re-checking, immutable idempotent revision creation, and the absence of activation/installation side effects. It also exposes visibility and pricing restrictions that are not inferable from the schema.

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 dense but efficient: purpose first, then workflow, then behavioral constraints and limitations. Every sentence earns its place, and code-formatted tool/parameter names aid scanning.

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?

Given the tool's complexity, absent annotations, and weak schema, the description covers the required workflow, retry semantics, permission context, and non-effects of publication. The return shape is appropriately left to the output schema.

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 0%, so the description must compensate. It adds crucial meaning for expected_contract_digest (must come unchanged from preview), visibility (PUBLIC is partner-tier gated), pricing_model (INCLUDED-only), and idempotent retry behavior. However, fields like domain, action, and the exact relationship of name/slug/version to the preview contract remain implicit, leaving a minor 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 first sentence names a precise verb and resource: 'Publish exactly the action contract returned by the preview tool.' It also explicitly distinguishes the operation from activation and installation, so an agent can separate it from siblings like install_agent_marketplace_action and activate_agent_marketplace_action.

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 gives an explicit precondition: call preview_agent_marketplace_action_publication first and pass its expected_contract_digest unchanged. It also tells the agent what the operation does NOT do, which helps it decide between this tool and install/activate tools.

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