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

Annotations declare non-destructive and idempotent but leave the cost/persistence profile open; the description fills that gap by stating the call is free, saves nothing and spends no credits, and that a stable clientRequestId is expected. It still doesn't say whether anything is cached server-side or what happens on a repeated id after the underlying selection changes. There is a mild tension between 'saves nothing' and readOnlyHint=false, but it is explainable as no editor project being persisted, not a direct contradiction.

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?

Three short sentences, front-loaded with what is returned, then the call contract, then the cost guarantee. Slightly redundant phrasing ('selected complete guides', 'plus the authoring contracts') but no filler sentences.

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 3-parameter tool with a large nested input object and no output schema, the description says what comes back only at a high level ('guides', 'media guidance', 'authoring contracts') and never positions this step in the editor workflow. An agent still has to infer how the returned contracts feed soclo_editor_edit or soclo_host_plan_import.

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?

Top-level parameter descriptions are absent (coverage reported 0%), though the nested schema is richly self-documented. The description does add meaning by constraining 'input' to the owner-selected payload rather than agent-invented data, and by requiring clientRequestId be a stable UUID for idempotency. The optional third parameter, catalogueVersion, is never mentioned anywhere the agent would look.

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 concrete verb and output set: it returns selected complete guides, media guidance and the authoring contracts for authoring an editor project. That is clearly a read/prepare operation distinct from the mutation tools (soclo_editor_edit, soclo_editor_export). It does not, however, distinguish itself from near-neighbours such as soclo_host_plan_prepare, soclo_host_plan_guides and soclo_editor_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?

'Free; saves nothing and spends no credits' implies this is a safe pre-flight call before committing to authoring, which is real usage signal. But there is no explicit statement of when to call this versus soclo_host_plan_prepare or soclo_editor_schema, and no exclusions or prerequisites beyond passing owner-selected input.

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