Store a summary for a leased item

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

Goes well past the annotations: it discloses the network side effects (verifying primary_url, looking up GitHub mentions and cataloguing them as separate items), the failure mode (prompt-injection rejection returns a reason), and the post-failure state ('the item stays leased to you, so fix the fields and call again'). That matches openWorldHint=true and non-idempotency while adding retry semantics the annotations cannot express.

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 critical scope and exclusion come first, then the parameter notes, then the network behaviour — a sensible order with no filler sentences. It is dense to the point of being a run-on, with a long mid-section of parameter clauses that could be ordered more scannably, but every clause carries 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?

For a 13-parameter mutation tool with no output schema, the description covers the lease lifecycle, the language/depth convention, per-field intent on the non-obvious parameters, network side effects, and what happens on rejection. An agent has everything needed to call it correctly and to recover from a failure.

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%, so the baseline is 3; the description earns an increment by adding guidance not in the schema, notably that category 'is ignored when the reader filed the item by hand' and that content should follow 'the language and depth the lease brief gives'. Most of the remaining notes (name untranslated, highlights are facts not marketing, primary_url only if seen) largely restate existing schema descriptions.

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 specific verb and resource (store the summary for a leased item) plus the side effect of ending the lease, and names the sibling that handles the alternative case (driftnet_refresh_item). An agent can distinguish this from driftnet_update_item or driftnet_save_link without opening either 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 precondition ('Only for leased items that have no summary yet') and an explicit alternative for the excluded case ('to redo an existing card use driftnet_refresh_item'). The prerequisite tool (driftnet_lease_items) is named as the source of the id, closing the loop on when this is callable.

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