library_desk_watch

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

The annotations already indicate idempotentHint true and destructiveHint false, but the description does not disclose important behavioral details like whether the periodic refresh runs in the background, how to stop it (library_desk_stop sibling exists), or what side effects might occur. The 'long-running task' language implies ongoing behavior, but the lifecycle and eventual stop behavior are left unspecified.

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 concise: two short sentences, no fluff, and each sentence carries practical information. The first sentence declares the core action and context, the second gives follow-up guidance. It is well front-loaded and easy to parse.

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?

The description conveys the primary purpose and provides a pointer to library_desk_refresh, but given the tool's 8 parameters and no output schema, more lifecycle and invocation context would be needed for an agent to use it fully. It omits mention of stopping the watch, return behavior, and the role of key parameters like subject, keep_open, and token_budget. Still, for a starting-a-refresh action it is not severely incomplete.

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?

The input schema has 8 parameters and only 25% description coverage. The tool description adds minimal parameter-related meaning: 'immediately and periodically' relates semantically to interval_seconds, but subject, keep_open, max_books, session_id, token_budget, and catalog_filters are not explained in the description. Since the schema lacks descriptions for most parameters, this is a significant gap.

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+resource: 'Refresh a reading desk immediately and periodically thereafter', which clearly identifies the tool's action and differentiates it from the one-shot library_desk_refresh. It also places it in the context of 'a long-running task', adding scope that helps distinguish it from related library tools.

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 gives clear guidance on when to use this tool: it is for long-running tasks that need immediate and periodic refreshing. It also explicitly states that after a focus change, one should call library_desk_refresh or restart this tool, providing an actionable alternative. It lacks an explicit 'when not to use', but the provided context is sufficient.

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