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

The description adds real behavioral context beyond the annotations: contracts are scoped to a catalog version and reusable within it, no craft-guide read is needed, and reading grants no edit or generation authority. However, annotations declare readOnlyHint=false and destructiveHint=true, and the description frames this purely as a read with no side effects, never explaining why a destructive classification applies — an inconsistency the agent must resolve on its own. Prerequisites such as the session-bound work_id and request_key are also undisclosed.

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 short sentences, front-loaded with what the tool returns and then how to use it; every sentence carries a distinct instruction (what, when, when-not, reuse). Slight density of domain jargon ('revision-bound direct-action delegation') costs a point but nothing is redundant.

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?

An output schema exists, so return values need no explanation, and the catalog-version reuse rule covers staleness. But for a 6-parameter, session-bound tool with nested objects, the description never explains where work_id, request_key, or read_skills must come from, and it does not reconcile the 'read-only' framing with the destructive annotation.

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 description coverage is 50%, so the description must compensate and it only partly does: the examples of action_type values give meaning to the otherwise undocumented 'action_types' string array, and 'for this catalog version' gestures at expected_catalog_version. work_id, request_key, and publication_proposal_id get no mention in either the description or schema, leaving half the parameters opaque.

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 uses a specific verb+resource ('Read exact payload schemas for named Film action_types') and grounds it with three concrete action_type examples. It also distinguishes itself from the apply path by noting that 'an apply tool already includes its common payloads in full', so the agent can separate it from native.apply_film_studio_actions and native.call_studio_tool. The abstraction 'action contract' remains somewhat jargon-heavy, keeping it short of a 5.

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 states the exact triggering condition ('when this host has no apply tool') and the exclusion (an apply tool already carries its common payloads, so this read is unnecessary). It also gives a reuse rule ('Reuse returned contracts for this catalog version; no craft-guide read is needed'), which prevents redundant lookups. This is explicit when/when-not guidance with a named alternative.

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