preview_job_preferences_update

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

With no annotations, the description must carry the behavioral burden. It does add genuinely useful availability context: the tool is disabled by default and gated on an advertised approved mutation capability. It stops short of saying whether the preview performs any write, what it returns (a diff? a plan token?), or how it fails when the capability is absent, which matters for a mutation-adjacent tool.

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?

Two short sentences, zero filler, with the purpose front-loaded and the availability constraint immediately following. Every clause carries information the agent needs.

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?

A nested-array mutation-preview tool with no annotations, no output schema, and zero parameter descriptions needs considerably more than two sentences. The description explains availability but leaves the entire `changes` payload contract and the tool's return/confirmation behavior undocumented.

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 0%, so the description needs to compensate and does not. It says nothing about the `provider` enum (linkedin/naukri) or about the `changes` array structure: which field names are legal for job preferences, what `set` versus `remove` does to `value`, or that the array is capped at 25 items.

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 names a specific verb ("Preview") and resource ("a job_preferences mutation"), so the operation is unambiguous. It does not, however, distinguish itself from the many sibling preview_* tools (preview_profile_update, preview_visibility_contact_update, etc.), leaving the agent to infer that this one is scoped to job preferences only.

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 gating condition ("disabled by default and available only when the provider advertises an approved mutation capability") implies the agent should first consult a capability check, presumably discover_provider_capabilities, but never names it. Likewise it never states that this preview should precede execute_confirmed_mutation, so the preview-then-confirm workflow is only implied.

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