Prepare saving/unsaving a job

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

Beyond the annotations, the description discloses the key behavioral distinction: it 'changes local state only; performs NO external action' and returns 'a PENDING action with a preview.' It also explains the confirmation workflow required before execution, which is crucial for a non-idempotent, non-destructive prepare 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?

The description is front-loaded with a bracketed PREPARE warning, then states purpose, behavior, usage constraint, and execution path. Every sentence adds necessary information; none 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?

Given the output schema exists, the description needn't explain return values fully, yet it still notes the PENDING action and preview. With annotations and schema present, the description covers the essential local-state-only behavior, confirmation workflow, and sibling execution tools, leaving no critical gaps.

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%: the url parameter is documented in the schema, but the mode enum lacks a description. The description's wording 'saving or un-saving' loosely maps to the save/unsave modes, but it adds no syntax, default behavior, or constraint details beyond the schema.

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 states a specific verb and resource: 'Prepares (does NOT perform) saving or un-saving a job on LinkedIn.' It immediately distinguishes itself from the actual execution tools by naming linkedin_save_job and linkedin_unsave_job, so an agent can tell it apart without opening schemas.

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 gives explicit when-to-use guidance ('only prepare this when the user asked to save it'), a when-not condition ('Recommending a job does not require saving it'), and the exact execution path ('the user confirms in their terminal, then call linkedin_save_job / linkedin_unsave_job'). Alternatives and sequencing are both covered.

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