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

Adds substantial behavior beyond the annotations: the change is recorded internally only and never touches the site or Search Console (consistent with openWorldHint=false), it cannot be undone from here, it is restricted to owners/admins, a changed opportunity is refused via the fingerprint, and a two-step preview→confirm flow with a confirmation_id gates the actual write. That is exactly the kind of context annotations cannot carry.

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?

Front-loaded with the three modes and the two-step flow, and nearly every clause earns its place (side effects, permissions, refusal, preview protocol). Minor waste from repeating 'as on the SEO page' twice and a long first sentence.

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 10-parameter tool with nested plan/application objects and three conditional modes, the description covers mode-specific payloads, the preview/confirm sequence, permissions, and failure conditions; an output schema exists so return values need not be explained. The only soft spot is 'some opportunities need a plan for every choice', which tells the agent a rule exists without a way to predict it 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 already 90%, so the baseline is 3, but the description adds real meaning: pass candidate_fingerprint plus the same window the opportunity was read with, plan is optional for plan_to_do unless the opportunity requires it, and the preview needs only opportunity_id, candidate_fingerprint, choice, with confirmation_id used solo on the second call. This conditional parameter routing is not fully derivable from the schema alone.

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+resource ('Plans an SEO opportunity ... reports it as already done ... or closes it') and enumerates the three outcome modes (plan_to_do, already_did, will_not_do) with the payload each needs. An agent can distinguish this from onelence_get_seo_opportunity / onelence_list_seo_opportunities purely from the description, since this is the commit action rather than a read.

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 clear boundaries: 'It goes to SEO Work in OneLence; nothing changes on the site or in Search Console', 'Owners and admins only', and a refusal case ('Some opportunities need a plan for every choice ... refused with param plan'). The one gap is that it never explicitly points to the sibling read tools (list/get_seo_opportunity) as the way to obtain opportunity_id and candidate_fingerprint, only implying it via 'the window the opportunity was read with'.

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