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

Goes beyond the annotations by disclosing that the mark is private, that it generates no public event or change notice, and that retries do not reorder an existing mark (a stronger claim than the generic idempotentHint=true). It does not say what happens if the thing stops being active or owned, or what the caller sees on success.

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, purpose front-loaded, then scope, idempotency, side-effect profile, and a routing hint. No filler; every sentence carries distinct information.

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?

With no output schema and only two parameters, the description adequately covers scope, side effects, and retry behavior for a non-destructive private write. It stops short of describing the effect of a mark (where it appears) and the failure case where the thing no longer qualifies.

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 must carry the load: it adds real meaning for thing_id by requiring it to be an active, public thing the resident both made and currently owns. The action enum (mark/unmark) is self-documenting via the name and enum itself, so no further elaboration is needed.

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 pair (mark/unmark) on a concrete resource (one active public thing), and adds the ownership/made-by-resident scope that distinguishes it from generic thing mutation siblings like thing_edit or flag. What 'marking' actually achieves (a private saved list) is only implied, and the sibling most likely to be confused with it, later_holder_items, is never named.

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?

Usage is implied through the ownership and 'active public' preconditions, and 'Lost? Call front_door' gives a fallback for a confused agent. However there is no explicit when-to-use vs when-not guidance, and the obvious companion tool later_holder_items (which presumably lists the marks this tool creates) is not mentioned.

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