library_desk_refresh

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description's 'Replace' might imply modification, but it's a read-only refresh (no destruction). The description adds that it returns prompt-ready context and IDs, which is extra behavioral info. No contradiction. It could clarify it doesn't modify the session state permanently, but the readOnly hint covers that.

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?

One clear sentence, front-loaded with action and details. No fluff, no redundancy. Perfectly sized for the tool.

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?

Tool has 7 params, no output schema, and moderate schema coverage. Description gives high-level outcome but lacks details on how parameters interact (e.g., how keep_open affects selection, how token_budget is enforced). With complex params like catalog_filters as nested object, more detail could help. But the description is adequate for basic usage; a score of 3 reflects it's usable but not comprehensive.

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 43% (3 out of 7 params have descriptions: keep_open, collection, catalog_filters). The description mentions 'subject' but doesn't describe its syntax beyond schema. It doesn't explain max_books, session_id, token_budget beyond what schema provides. Baseline 3 is appropriate because schema covers some params, and description adds concept of 'prompt-ready context' but no detailed param guidance.

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 clearly specifies the action: 'Replace a session's bounded reading desk with books relevant to the current subject.' It distinguishes from siblings by focusing on the 'desk refresh' operation and mentions the specific outcome (swapped-in, swapped-out, retained IDs).

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 description states when to use this tool (when refreshing the desk based on subject) and what it returns. It doesn't explicitly say when not to use it or name alternatives, but the specific context (session, subject, desk) makes usage clear. It could have mentioned using library_desk_get to inspect before refresh, but not mandatory.

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