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

Goes well beyond the annotations: it spells out idempotency semantics ('calling it twice is calling it once with a later timestamp'), the return payload (job_id and seen_at), that read state is account-scoped rather than key-scoped, and that it is distinct from website browsing state. These are non-obvious behaviors an agent could not infer from readOnlyHint/idempotentHint alone, and nothing here contradicts the annotations.

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 action and its effect, and each subsequent sentence carries distinct information (idempotency, return value, account scope, authorization). It is longer than strictly necessary for a one-parameter flag-clearer, but there is no filler or repetition.

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?

Despite having no output schema, the description documents the return fields (job_id, seen_at), the mutation's scope, idempotency, and the authorization rule. For a single-parameter mutation this is fully sufficient to call it correctly on the first attempt.

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 100% and the single UUID parameter is fully documented there, so the baseline is 3. The description adds genuine constraint-level meaning by specifying which job_ids are valid ('only a party to the job ... which is exactly the set of jobs get_my_jobs returns to you'), saving the agent from trial-and-error on 403s.

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 precise verb+resource ('Record that you have seen everything on this job') and immediately names the concrete effect: clearing has_new_messages and has_new_bids on get_my_jobs. This distinguishes it cleanly from the sibling read tools (get_job, get_messages, get_bids) without needing to open a 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?

Gives an explicit trigger ('Call it after reading a job's messages or bids') and a reason tied to a specific alternative ('so the next get_my_jobs tells you what has arrived since rather than repeating what you already handled'). It also states the eligibility condition (only a party to the job), which is effectively the boundary on when this call is valid at all.

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