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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false; the description extends this by adding 'without changing the reading desk' and revealing the hybrid ranking mechanism. It still omits return/pagination behavior, but with strong annotation coverage this is acceptable.

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 sentence, front-loaded with the search action and resource, then compact behavioral details. Every phrase earns its place with no fluff or redundancy.

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 core purpose and safety profile are clear, but with five parameters, a nested catalog_filters object, and no output schema, important operational details such as result format, ranking thresholds, and filter semantics are left to inference. The description is adequate for basic selection yet incomplete for confident invocation.

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?

Only collection and catalog_filters have schema descriptions; subject, max_books, and minimum_relevance are undocumented. The description's ranking phrase only loosely hints at relevance but does not explain thresholds, limits, or query formats, so it fails to compensate for the 40% schema coverage.

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 opens with the specific action 'Search the off-desk Library' and names the ranking behavior (hybrid vector, lexical, importance, recency), making the tool's function unmistakable. The phrase 'without changing the reading desk' distinguishes it from desk/context siblings such as library_desk_get and library_context_*. This is a clear, specific purpose statement.

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 conveys a clear read-only search context and explicitly notes no desk state change, which helps select this tool over mutation-style siblings. However, it does not name alternatives or state when not to use it, so the guidance is contextual rather than explicit.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable behavioral context: 'Durably append' signals persistence, and 'outbox indexes it asynchronously while the recent ring makes it immediately visible' explains visibility and indexing behavior. This goes beyond annotations without contradicting them.

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 two sentences and front-loads the purpose. It efficiently conveys the core action and a key behavioral note without unnecessary detail. No redundancy or filler.

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?

Given the tool's complexity (12 parameters, no output schema, low schema coverage), the description is incomplete. It does not indicate what the tool returns, how errors are reported, or the role of many parameters. While it mentions asynchronous indexing and immediate visibility, it lacks essential details for safe and correct usage, especially for a write operation with multiple tunable settings.

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 only 25% (3 out of 12 parameters have descriptions). The description does not explain any parameters beyond implying 'assistant or tool result' for the content/role. For a tool with 12 parameters, the description should compensate for the low schema coverage, but it does not clarify key parameters like max_books, protected, importance, token_budget, etc. 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 clearly states the tool's purpose: 'Durably append the assistant or tool result after a governed model call.' This specifies the verb (append), resource (assistant or tool result), and context (after a governed model call). While it is clear, it does not explicitly differentiate from sibling tools like library_context_prepare or library_context_protect, so it lacks a direct contrast.

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 implies usage when needing to commit results after a model call, but it does not provide explicit when-to-use vs. when-not-to-use guidance or name alternatives. The sibling tool names suggest other operations (e.g., prepare, protect, release), but no exclusions are given. The guidance is implied rather than explicit.

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

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

The description explains the core behavior (waiting for embedding/indexing) and mentions the 'durable outbox' and 'watermark', which give some insight into side effects. However, it does not mention timeout behavior (despite a timeout_seconds parameter), potential failures, or what happens if the operation is interrupted. It is consistent with the idempotent annotation, but lack of detail on blocking semantics limits transparency.

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 a single, concise sentence with no redundant wording. It is well-structured and front-loaded with the primary action ('Wait until'), making it easy to parse. No other tools are referenced, keeping it focused.

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 is too terse for the apparent complexity. It does not define key terms like 'durable outbox' or 'recorded watermark', nor does it mention return values, errors, or timeout behavior (which is directly relevant given the timeout_seconds parameter). Given the existence of many sibling context operations, this level of detail is insufficient for an agent to know when and how to use it effectively.

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 description adds no information about the three parameters. The schema already provides a description for 'collection' and obvious defaults for the others, but 'session_id' and especially 'timeout_seconds' lack explanation (e.g., what does timeout do? what is a session id?). With low schema coverage (33%), the description should compensate but does not, so parameter understanding is left incomplete.

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 states the action (wait until) and the resource (the thread's durable outbox) with a specific outcome (embedded and indexed through its recorded watermark). It distinguishes itself from siblings by indicating a blocking/waiting operation, though the exact meaning of 'flush' is not directly explained.

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 provides no guidance on when to use this tool versus the many sibling context operations (e.g., prepare, commit, release). It does not mention scenarios such as needing to ensure persistence or consistency, nor does it state the tool is appropriate after mutations. The usage context is entirely absent.

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

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

Given annotations only state readOnlyHint:false, openWorldHint:false, idempotentHint:false, and destructiveHint:false, the description adds meaningful behavioral context: operations are durable ('Durably append'), outputs are bounded via a paging envelope, and the model should replace its message set with the returned value. It does not contradict the annotations (a write is consistent with readOnlyHint:false) and adds beyond what annotations provide, though it omits details on the envelope's structure or edge cases.

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?

Two terse sentences with zero filler. The first declares the primary action and return value; the second provides a critical usage warning. Both sentences earn their place and critical information is front-loaded. Ideal concision.

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 tool with 14 parameters, no output schema, and low schema coverage, the description is far too thin. It explains none of the parameters (token budgets, focus, max_books, etc.) and the 'semantic-paging envelope' behavior is never structurally defined. The brief note about the envelope is helpful context, but it does not adequately enable an agent to select this tool over siblings or safely set advanced options.

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 only 21% (3 of 14 params), and the description provides no parameter-level explanation whatsoever—so 11/14 params (focus, max_books, token_budget, importance, etc.) are undocumented in both the schema and the description. The description does not compensate for this significant gap. It earns a 2 because the bare names and types are present, but the intent/format of most parameters is left to guesswork.

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?

Description names a specific verb+resource ('durably append a user turn', 'return... semantic-paging envelope'), and the second sentence clarifies an important behavioral consequence ('Send only the returned messages to the model'). It's clear this is a write-then-return-context operation, but heavy jargon like 'bounded semantic-paging envelope' and lack of explicit sibling differentiation keep it from a 5.

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 phrase 'for the next model call' and the instruction 'Send only the returned messages to the model' imply this is the standard context-preparation entry point and convey a constraint on how to consume results. However, no explicit when-to-use guidance, exclusions, or named alternatives are given (e.g., when to use library_prompt_build or library_context_commit instead). With 15 siblings, explicit differentiation would materially help.

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

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

With no readOnlyHint, the tool is indeed a write/persist operation, consistent with descriptions of others like library_shelve. The description adds context beyond annotations: 'remains eligible for every governed prompt until released' reveals persistence duration. It also mentions 'protected' and 'critical', which implies weight. However, it does not detail failure modes, idempotency, or implications of multiple books, but this is reasonably rich for a tool with no annotation coverage.

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?

Single sentence, concise, front-loaded with the action ('Persist') and resource ('critical instructions, decisions, active plans, or unresolved state'). No fluff, yet packs essential notion of persistence across prompts. Ideal conciseness.

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 many parameters (11), the description suffices given the complexity: it fully explains the purpose and lifecycle (persistent until release). Output schema absent, but the return is unspecified; the description doesn't need to explain output. The tool's function is clearly mapped to its name and purpose. High completeness given the abstract context.

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 only 9%, meaning the description adds meaning beyond schema. The description implies the purpose of 'content' (critical instructions, decisions) but does not elaborate on parameters like 'importance', 'token_budget', 'role', or 'label'. It does explain the concept of 'protected context' that is preserved for every prompt. Given low coverage (9%), the description sets the conceptual framing but leaves parameter-specific details to the schema names. This is a moderate compensatory effort.

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 states that the tool persists critical items (instructions, decisions, plans, unresolved state) as protected context. The verb 'Persist' plus specific resources (instructions, decisions, plans) distinguishes it from siblings like library_shelve or library_context_commit, and the phrase 'remains eligible for every governed prompt until released' clarifies the lifecycle.

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 implies usage: persist critical context that must survive across prompts. It does not explicitly name alternative tools, but the context signals include sibling tools like library_context_release (opposite action) and library_context_prepare/commit (different actions). The term 'until released' alludes to the release tool, and 'protected context' differentiates from unprotected context. However, it lacks explicit 'use this when...' or 'don't use for...' guidance.

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

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

The description adds behavioral context beyond the annotations: it states the durable event is retained and that the event becomes paged normally. This complements the idempotentHint and destructiveHint:false annotations without contradicting them.

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 two short sentences that front-load the action and its outcome. Every part earns its place; no filler or repetition of schema details.

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 tool is simple and the core behavior is clear, but there is no output schema and no return value or error behavior described. Given the sparse annotations and sibling context, the description is adequate but not complete.

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 only 33%, with event_id and session_id undocumented. The description mentions 'one protected event' but does not explain parameter meanings or formats, so it does not compensate for the low coverage.

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 ('Release') and resource ('one protected event') with the effect ('so it can be paged normally'). It clearly distinguishes from siblings like context_protect and context_flush by clarifying the protected/durable nature.

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 intended scenario is implied: release a previously protected event when normal paging is desired. However, there is no explicit when-to-use guidance, alternative naming, or exclusion wording compared with sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's mention of 'Read' aligns without contradiction. However, it adds no additional behavioral details (e.g., error conditions, rate limits, or side effects) beyond what the annotations already convey.

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 a single, concise sentence with no redundancy or extraneous information. It efficiently communicates the core functionality without verbosity.

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 simple read-status tool, the description conveys the essential action and scope. However, it omits any mention of output format, typical use cases, or prerequisites (e.g., must have an active session), leaving some gaps in completeness for a fully self-contained definition.

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 description does not explain the parameters at all. While 'collection' has a schema description, 'session_id' lacks one, and the tool description fails to clarify how these parameters relate to 'one agent thread.' The low schema coverage (50%) is not compensated, leaving the meaning of 'session_id' ambiguous.

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 states the tool's verb ('Read') and enumerates the specific resources it accesses (context-governor watermarks, queue occupancy, prompt pressure, worker health) along with the scope ('for one agent thread'), making its purpose unambiguous and distinct from sibling 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 provides no explicit guidance on when to use this tool versus alternatives, such as when a status check is preferred over a stop or shelve operation. It lacks contextual cues like 'use this when you need to monitor progress' or 'for real-time metrics.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by specifying the resource type ('bounded reading desk snapshot') and scope, which helps set expectations for what the tool returns. No contradiction with 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?

The description is a single, front-loaded sentence with no redundancy. Every word contributes to the meaning, making it efficient 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?

For a simple read tool with rich annotations and only two optional parameters, the description is sufficiently complete. It lacks details about the snapshot's structure or handling of missing sessions, but given the tool's simplicity and the absence of an output schema, it does not require more. The description is adequate for its scope.

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 50%: collection has a description but session_id lacks one, and the tool description does not elaborate on either parameter. The sentence 'for a session' hints at session_id's role but does not clarify its format or default behavior. The description adds no parameter meaning beyond the schema, leaving a gap for session_id.

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 states the verb ('Read'), the resource ('latest bounded reading desk snapshot'), and the scope ('for a session'). It distinguishes itself from siblings like library_desk_refresh (which likely refreshes) and library_desk_watch (which likely watches), establishing a unique purpose.

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 implies usage when you need to read a snapshot, but it does not explicitly contrast with alternatives or provide when-not-to-use guidance. Sibling names like refresh and watch hint at alternatives, but the description itself offers no direct comparison or selection criteria.

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

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.

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

Annotations provide idempotentHint=true and destructiveHint=false. The description adds the valuable detail that 'the current snapshot remains available,' reassuring the agent that stopping the refresh does not discard data. It also clarifies the operation is non-destructive. This goes beyond what annotations alone convey and aligns with them.

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?

Two short sentences, front-loaded with the primary action, and a useful clarifying sentence about the snapshot. Every word serves a purpose; no redundancy or filler.

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 simple idempotent stop operation, the description is sufficient: it explains the outcome and clarifies that the snapshot remains. It does not describe return values, but no output schema exists and the operation has no side effects that need disclosure. The use of 'session' aligns with the session_id parameter, so the missing parameter documentation is contextually supplied. Could mention behavior when called again, but idempotentHint already covers that.

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 only 50% because session_id lacks a description. The tool description does not mention or explain either parameter. 'Collection' and 'session_id' are left to be inferred by their names and defaults. The description adds no meaning beyond the schema, and for the under-documented session_id, it provides zero elaboration.

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 uses a specific verb+resource: 'Stop periodic refresh for a reading-desk session.' This clearly indicates the action and target. It also distinguishes from sibling tools like library_desk_refresh and library_desk_watch by stating it stops the periodic refresh, not starts or retrieves.

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 implies usage: it is meant for stopping a periodic refresh that presumably was started by library_desk_watch or similar. It does not explicitly state when to avoid using it or mention alternatives, nor does it note that the session may continue to exist for other operations. Thus, it provides some implied context but not thorough guidance.

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

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.

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

Annotations are minimal (all false), so description carries the burden. The description says 'Shelve one conversation message' which implies a write operation (consistent with readOnlyHint=false). It adds context about external model gateways and recording replies, but doesn't disclose details like whether this replaces existing messages, if there are size limits, or if it handles different roles (though role is in schema). No contradiction with 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?

The description is concise (two sentences) and front-loaded with the core action. No wasted words, but it's slightly terse given the tool's complexity and the need to clarify parameter semantics.

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?

Given 5 parameters, only 2 required, and no output schema, the description is thin. It doesn't explain what happens after shelving (return value?), how roles are handled, or the significance of 'importance'. The tool's purpose is clear, but the description lacks completeness for an agent to use it effectively without digging into schema defaults.

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 low (20%) - only 'collection' has a description. The tool description doesn't elaborate on any parameters besides saying 'one conversation message'. It fails to explain the meaning of 'importance', 'session_id', or the role/content relationship. The description adds minimal value beyond the schema, leaving the agent to infer semantics from the enum and defaults.

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 states the tool's purpose: to shelve one conversation message for a virtual-context session. It identifies the resource (conversation message) and the action (shelve/record). It distinguishes from siblings by mentioning 'virtual-context session' and specifying 'assistant replies', though it doesn't explicitly differentiate from library_shelve or library_shelve_document.

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 provides a clear usage context: 'External model gateways should record assistant replies after each response.' This specifies when to use (after each response) and for what (assistant replies). It doesn't explicitly exclude other tools or mention alternatives, but the context is clear enough for an agent.

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

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

The description adds some behavioral context by noting the operation is 'stateless' and that 'full history remains shelved on disk', implying it does not grow the live prompt or modify persistent state. However, it does not disclose permissions, side effects, or failure modes, and the annotations provide no hint (readOnlyHint is false), so the description only partially clarifies the behavior.

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 two sentences and mostly front-loaded, but the metaphor 'reading desk' and 'shelved' may obscure meaning without prior library context. It is concise yet could be clearer for the agent, warranting a middle score.

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 a complex tool of 8 parameters, 13% schema coverage, no output schema, and no annotations, the description is insufficient. It does not explain the return format, parameter usage, or any side effects. A tool this complex requires richer description to be usable.

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 only 13%, leaving seven of eight parameters undescribed. The tool description does not mention any parameter names or meanings, making it impossible for the agent to understand inputs like 'max_books', 'token_budget', or 'system_prompt'. The description entirely fails to compensate for the schema 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 clearly states the tool 'builds a complete stateless model-input envelope' from bounded recent turns and a replacement reading desk, conveying the core function. However, it does not explicitly differentiate it from similar library tools like library_context_prepare or library_desk_get, leaving its unique role somewhat ambiguous.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions. The description only states what it does, not when it should be invoked, leaving the agent without usage direction.

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

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

Annotations already convey read/write and non-destructive naturechers (readOnlyHint=false, destructiveHint=false). The description adds the 'durable' framing but does not disclose potential side effects like overwriting an existing book_id or limitations on size. It does not contradict annotations, but also goes beyond them minimally.

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 two sentences, front-loads the purpose, and is free of fluff. Every sentence contributes to understanding the tool's role and scope.

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 write-oriented tool with no output schema and several optional parameters, the description gives enough to understand the top-level function but leaves parameter semantics to the schema. It is a minimum-viable description, but given the tool's complexity and low schema coverage, it falls short of fully informing usage.

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 low (29%), and this description adds no parameter-specific meaning. It only hints at content type ('concise book') but does not explain text, source, book_id, importance, or shelf_life_seconds. Since coverage is low, the description should compensate, but it does not.

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 pair ('Persist ... to the local Library') and clearly defines the domain (durable context, not chatter). It distinguishes itself from siblings like library_desk_stop and library_consult by focusing on persisting a book of context.

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?

Provides explicit positive guidance ('Use for durable decisions, constraints, findings, and user-approved memories') and negative guidance ('not transient chatter or secrets'), which helps an agent decide when to invoke it. However, it does not mention alternatives or exclusions relative to sibling tools (e.g., library_shelve_document).

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

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

Annotations already declare destructive and idempotent behavior. The description adds valuable context by explaining the chunking behavior and that replace_edition replaces prior chunks from the same source, which clarifies the destructive semantics beyond the annotation flags.

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?

Two concise sentences front-load the core purpose and add the single most important behavioral caveat. There is no redundancy or filler.

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 core chunk-and-persist flow and replacement behavior are covered, and annotations provide the safety profile. However, with 8 parameters, 25% schema description coverage, and no output schema, the description leaves important operational details—like how importance, chapter_tokens, and overlap_tokens affect output—to inference.

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 only 25%, and the description only elaborates on replace_edition. Parameters like chapter_tokens, overlap_tokens, importance, and catalog semantics remain under-specified; their names give hints, but the description does not compensate for the low schema coverage.

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 states the action ('Chunk and persist') and the resource ('a larger local text document'), with a distinctive outcome ('as multiple books'). This distinguishes it from sibling tools like library_shelve, which likely handles a single unsplit document.

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 context: use this for larger local text documents that need chunking, and use replace_edition to update previously persisted chunks. It does not explicitly name alternatives or give when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds context about what is inspected (health, usage, cache counters, embedding config), which is useful, but it does not disclose details like whether the operation may be slow or trigger background refresh, which could be relevant for a stats tool.

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 a single sentence, front-loaded with the key verb 'Inspect' and lists the key data categories. Every word earns its place, with no fluff or redundancy.

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?

Given the tool's low complexity (only one optional parameter, no output schema), the description is sufficiently complete: it names the key inspection areas. The lack of an output schema means the agent might not know the return format, but that is not required when no output schema is provided.

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 schema provides 100% coverage for the single parameter 'collection', describing it as an optional namespace. The description does not add any additional meaning beyond what the schema provides; thus the baseline score of 3 is appropriate.

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 states the tool inspects library tier health, usage, cache hit/miss counters, and embedding configuration, which is specific enough to distinguish it from siblings like library_shelve and library_consult. It doesn't explicitly mention the optional 'collection' parameter in the description, but the purpose is clear.

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 implies a read-only inspection tool, but does not provide explicit guidance on when to use this tool versus alternatives like library_desk_get or library_desk_status. There is no explicit mention of when not to use it or which sibling tools to prefer for other tasks.

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