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

Annotations already cover the safety profile (not read-only, not destructive, open-world), so the description's added value is strong: it discloses that agents see only published revisions and that saving does not publish, which is exactly the mutation-scope context a caller needs. It does not address conflict handling when expected_version is stale.

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 sentences, action-first, with the most decision-relevant constraint (never publishes) placed last for emphasis. The two runner-type sentences are dense but each carries distinct information rather than restating the schema.

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 6-parameter mutation with no output schema and a free-form nested definition, the description covers the domain model well but omits what a successful save returns (draft id/version) and how the expected_version mismatch surfaces. Those are meaningful gaps for a write tool.

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 50% and the description adds real meaning to the nested definition object by explaining runner http vs runner agent and what fields each implies. But it says nothing about key, company, or environment, and the definition's actual field list is deferred to an external doc path.

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?

States a specific verb pair (create or edit) plus resource (company action draft) and the optimistic-concurrency contract (expected version). The final line, 'Saving never publishes,' implicitly separates it from summer_actions_company_publish, though no sibling is named outright.

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?

Usage is implied by the draft/publish distinction and the runner-type explanation, so an agent can infer this is the draft-write step in a save-then-publish workflow. However, it never explicitly states when to pick this over summer_actions_prepare, summer_actions_stage_update, or summer_actions_company_test.

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