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

Annotations already declare this is a non-read-only, non-destructive open-world action, so safety framing is partly covered. The description adds two valuable traits beyond that: the availability precondition and a mandatory user-confirmation step. It still omits what happens on a ready-hold borrow (whether the hold is consumed/converted into a loan) and failure behavior, which matter for a write operation.

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, zero waste, with the action and its precondition front-loaded before the safety instruction. Nothing is padded or repeated from the schema.

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 an output schema and annotations present, the description only needs to cover trigger, preconditions and side effects. It covers trigger and precondition well; the one remaining gap is the hold-consumption side effect, which an agent borrowing a ready hold would benefit from knowing.

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 100%, with days, library and title_id all documented in-schema (including the 1-21 range and the "defaults to the card's preference" note). The description adds no parameter-level meaning, so the baseline 3 applies.

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?

"Borrow an available title, or a hold that is ready" gives a specific verb plus the two resource states it operates on, which meaningfully separates it from place_hold, renew_loan and return_loan. It stops short of naming those siblings, so the differentiation is implied rather than explicit.

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 sets a clear precondition (the title must be available, or a hold must already be ready) and adds an operational rule: confirm with the user first. It does not say what to do in the negative case, e.g. route to place_hold when nothing is available, so it is good context without explicit alternatives.

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 flag destructiveHint=true, so the safety profile is partly covered; the description still adds real value by disclosing the concrete consequence — the user loses their place in the queue — and by requiring user confirmation before invocation. It stops short of saying whether the cancellation is reversible or whether the hold can be re-placed at the same position.

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 clauses, consequence front-loaded after the action, and the confirmation requirement stated last. No filler; every phrase 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?

With annotations covering safety, a full output schema, and 100% parameter documentation, the description supplies the one thing structured data lacks: the user-facing consequence and the confirmation requirement. Only the reversibility of the cancellation is left unstated.

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 100% and both parameters (library, title_id) are documented in the schema, so the description need not carry parameter detail. It adds nothing beyond the schema, which is the expected baseline when coverage is complete.

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 ('Cancel a hold') with the added consequence of losing queue position, so the agent knows exactly what operation is performed. It does not name or contrast with siblings like place_hold or return_loan, so it falls short of 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 instruction 'Confirm with the user first' is a genuine usage prerequisite for a destructive action and is the most valuable guidance here. However, there is no explicit when-to-use/when-not or comparison to alternatives (e.g., vs. return_loan or place_hold), so usage context is only implied.

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 a non-read-only, non-destructive, open-world operation, so the mutation profile is covered. The description adds that the call returns library cards, but says nothing about failure modes for an invalid/expired code, idempotency, or what re-linking does to existing state.

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 sentences, front-loaded with the action and with a useful note on the return value. The return-value sentence is slightly redundant given an output schema exists, but it costs little.

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?

A single-parameter tool with full schema coverage, an output schema, and annotations needs little more from the description. What is missing is mild: behavior on an invalid code and whether the call can be re-run safely.

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% and the sole parameter is fully documented in the schema, including its provenance ("Libby's 'Copy To Another Device'"). The description adds no semantics beyond that, so the baseline 3 applies.

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?

A specific verb and resource ("Link the user's Libby account") plus a statement of what comes back ("linked library cards"). It is distinguishable from get_account, which reads existing account data, but the description never names a sibling, so differentiation is by inference.

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?

"one-time setup code" implies this is a first-time onboarding step rather than a repeatable operation, which is useful context. However, there is no explicit guidance on when to call this instead of get_account, or what to do if the account is already linked.

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 and openWorldHint, so safety is covered. The description adds genuinely useful behavior beyond that: results may be ambiguous because branches, consortia, and special collections all match, and a user confirmation step is required before consuming the key. It omits ranking or result-count behavior, keeping it below a 5.

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 action and return value, followed by the ambiguity warning. Nothing is redundant or padded.

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 one-parameter read tool with a full output schema and existing annotations, the description covers the only real risk: ambiguous matches requiring user confirmation before the key is used downstream. No essential calling information is missing.

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% and the single query parameter is already documented as 'Library name, city or postal code.' The description restates that same set without adding format details such as the two-character minimum or fuzzy-match behavior, so it stays at the baseline for schema-documented params.

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 (find libraries), the matching criteria (name, city, postal code), and what is returned (keys). No sibling tool in the list performs library resolution, so the tool is unambiguous against search_titles, get_availability, connect_account, etc.

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 clear operational guidance: multiple libraries can match, and the agent should confirm the correct one with the user before using its key. It does not explicitly state prerequisites or when-not-to-use (e.g., when a key is already known), so it stops short of full when/when-not routing.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful detail about what fields come back (due dates, queue position), but says nothing about the requirement for an authenticated/connected account – a real gap given a connect_account sibling exists.

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?

A single, dense sentence with zero filler, and the most important content (cards, loans, holds) is front-loaded. It reads as a noun fragment rather than a complete statement of action, which slightly weakens the framing but not the economy.

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 an output schema present, the description needn't enumerate return fields in full, and it correctly stays brief. The one thing an agent needs that is absent is the prerequisite that an account must already be connected/authenticated before this call succeeds.

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 tool takes zero parameters, so there is no parameter meaning for the description to carry. Baseline 4 applies; nothing is missing or misleading on this dimension.

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?

It names the specific resource set returned – library cards, current loans with due dates, and holds with queue position – which lets an agent distinguish it from get_history and get_availability. It lacks an explicit verb ('retrieve'), so the framing is a content listing rather than a stated action, but the resource is unambiguous.

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?

There is no when-to-use statement and no named alternative, despite siblings like get_history, connect_account and get_availability that overlap in scope. The agent must infer that this is the go-to call for a full account snapshot versus loan history or availability checks.

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 and openWorldHint=true, and the description is consistent with a pure read. It adds interpretation context (a missing library means no ownership of that edition; waits are estimates), but says nothing about batching limits, rate limits, or how live the 'current' data is.

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 tight sentences with the main capability front-loaded and the caveat second. Slightly clipped phrasing ('A library missing from a title's list') costs a little clarity but there is no 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?

With an output schema present and annotations covering the safety profile, the description only needs to add result-interpretation and routing, which it does. The remaining gap is operational detail (batch size of 50 title_ids, data freshness) rather than anything essential for correct 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?

Schema description coverage is 100%, so both parameters are already documented, including that title_ids are edition-specific OverDrive ids and that libraries overrides defaults. The description reinforces the edition/library scoping but adds no new syntax or formatting detail, making baseline 3 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 names the concrete payload (current copies, holds, estimated wait) scoped to 'specific editions at each library', which is far more specific than the tool name alone. It implicitly separates this lookup from mutation siblings like place_hold or borrow, though it never says outright that it only reads data.

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?

It explicitly routes the agent: if a library is absent from a title's list, that library doesn't own the edition, and search_titles is the way to find other editions. That is a real when/when-not rule with a named alternative, though no guidance is given about follow-up actions (e.g. place_hold) once availability is known.

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 cover read-only and open-world, and the description adds substantive context beyond them: which fields exist, that history is raw and unordered for formatting, and that `progress` costs 'one lookup per title'. It still omits cost/volume limits at limit=500 and any pagination or failure 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?

Purpose and ordering are front-loaded, followed by a bulleted field glossary. The length is justified by genuinely non-obvious interpretation heuristics (marker vs. heard, gap thresholds), though a few sentences such as the ebook note could be trimmed without loss.

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 read-only raw-data tool with a full output schema, the description supplies everything an agent lacks elsewhere: the presence and meaning of derived metrics and how to read ambiguous cases. Nothing needed to call it or interpret its output is missing.

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, but the description meaningfully elaborates the `progress` flag by enumerating exactly the derived fields it unlocks (marker_percent, listened_percent, marker_gap_percent, pace, minutes_spent, sessions). `limit` and `library` are left entirely to the schema.

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 ('Everything the user has borrowed in Libby') plus an ordering guarantee ('most recently borrowed first'), which cleanly separates it from search_titles, get_title, and get_account. An agent can identify the tool without opening the 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?

Usage is only implied by the scope statement (browsing/analyzing a user's borrow history); there is no explicit 'use this when...' or 'instead use X for...' routing despite eleven sibling tools. The bulk of the text is field interpretation rather than tool selection 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered. The description adds only the field list, which duplicates what the output schema already provides, and says nothing about not-found behavior or data freshness.

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?

A single short sentence with the resource and returned fields front-loaded and no filler. Slightly phrase-like ('Full details for one title:') rather than a full clause, but nothing is wasted.

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 one-parameter read tool with annotations and an output schema, the description covers purpose and returned content adequately. The only gap is routing guidance versus sibling lookup tools, which is minor at this complexity.

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?

There is a single required parameter with 100% schema description coverage ('OverDrive title id', with a numeric pattern). The description adds no information about title_id, so the baseline of 3 applies.

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 ('Full details') and resource ('one title') and enumerates the fields returned (description, series, narrators, publisher, ISBNs). It is clearly distinct from search_titles or get_availability in spirit, though it never explicitly contrasts itself with those siblings.

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 one title' implies use after a search identifies a title id, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the close alternatives search_titles and get_availability that an agent must choose between.

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 and openWorldHint=true, so safety is covered. The description adds the sort order (largest first) and a handoff to search_titles, but says nothing about result size, truncation, or how media_type narrows output.

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 tight sentences, zero filler, and the core resource plus ordering is front-loaded. No restructuring needed.

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?

An output schema exists so return shape is covered, and the tool has no required parameters. However, for a tool that supports media_type filtering and multi-library selection, the description omits anything an agent would need to pick parameters correctly.

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% — media_type has no schema description at all — and the description never mentions either parameter. It does not compensate for the gap, leaving the filtering behavior of media_type and the library default undocumented anywhere.

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 the resource clearly ('Subjects (genres) in a library's collection') plus a meaningful ordering ('largest first'). The listing verb is implied rather than stated, and no sibling is named as an alternative, so it falls short of 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?

'Use the ids with search_titles' gives a downstream workflow hint, which is useful. But it does not say when to call this versus calling search_titles directly, nor any conditions or prerequisites for its own use.

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 a non-destructive write to an open-world system; the description adds a meaningful confirmation requirement before execution. It does not disclose failure modes (already-held, card limits) or idempotency, so the added context is helpful but thin.

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 with zero waste; the action is front-loaded and the confirmation instruction follows immediately.

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 full output schema and 100% parameter coverage, the description only needs to convey purpose and any pre-execution caveat, which it does. Minor gap: it doesn't mention the single-linked-card/library nuance, but that is covered by the schema.

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 100%, so both parameters (title_id, library) are fully documented in the schema. The description adds nothing beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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+resource ('place a hold on a title'), distinct from siblings like cancel_hold or borrow. It doesn't explicitly contrast with borrow/renew, but the action is unambiguous.

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?

Adds a workflow prerequisite ('Confirm with the user first'), which is useful, but gives no guidance on when to choose hold over borrow or what conditions make a hold appropriate (e.g., title unavailable). Usage is implied rather than explained.

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 this is a non-read-only, non-destructive, open-world mutation. The description adds meaningful context beyond that: renewal is only possible from the renewable_on date, and the agent must confirm with the user before acting. It still does not describe the effect of renewal (e.g., due-date extension) or failure conditions like renewal limits.

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 front-loaded sentences with no wasted text. The parenthetical 'its renewable_on date' is slightly ambiguous because renewable_on is not a parameter, but overall the structure is efficient.

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 three-parameter mutation with an output schema, the description covers the essential precondition and confirmation requirement. It leaves out what happens on failure (e.g., renewal limits) and what the renewal actually changes, which would be useful for a mutation tool even with annotations and schema coverage.

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 days, library, and title_id are already fully documented in the schema. The description adds no parameter-specific guidance beyond the timing context, which is appropriate given the schema does the heavy lifting.

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 and resource ('Renew a loan'), which is clearly distinct from siblings such as borrow, return_loan, and place_hold. It adds a timing qualifier ('possible from its renewable_on date'), but does not explicitly contrast itself with any sibling tool.

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?

It gives a concrete precondition ('possible from its renewable_on date') and a workflow rule ('Confirm with the user first'), which tells the agent when renewal is allowed and that user confirmation is required. It does not name alternatives or explain what to do when renewal is unavailable.

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 flag destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds a critical behavioral requirement: confirm with the user before acting. It could say more about reversibility or effects on history, but it adds meaningful context beyond the 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?

Two short, front-loaded sentences with no filler. The action is stated first and the confirmation requirement follows immediately.

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 an output schema present, annotations covering safety, and full parameter documentation, the description supplies what an agent needs to act safely. It doesn't elaborate on post-return state or edge cases, but enough context is available elsewhere.

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 both the optional library key and required title_id are fully documented in the schema. The description doesn't add syntax or format details, which is acceptable given the schema's completeness.

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 and resource ('Return a loan early'), which distinguishes it from renewing or borrowing. It doesn't explicitly name siblings like renew_loan, but the 'early' qualifier gives it a distinct scope.

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?

It provides a necessary prerequisite ('Confirm with the user first'), which is useful for a destructive action. However, it doesn't say when to prefer this over renew_loan or cancel_hold, nor does it describe exclusions or alternatives.

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 cover safety (readOnlyHint) and open-world scope, yet the description still adds non-obvious behavior: editions are merged by title/first author/format and ranked by best position across libraries, and availability is reported per library. It stops short of describing pagination or how limits interact across multiple libraries.

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 tight sentences with the core capability front-loaded and the result-shaping behavior second. Minor waste in the line-broken formatting, but every sentence 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?

With an output schema present and near-complete parameter descriptions, the description only needs to explain the search model and result merging, which it does. A note on multi-library result grouping or limits per library would round it out.

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 89%, so parameters are largely documented in the schema itself (sort semantics, 'Results per library', 'Omit to browse', subject ids source). The description adds nothing parameter-specific, so the baseline 3 applies; the undocumented media_type remains unaddressed in both places.

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 ('Search' titles) and adds real scope detail: one or several libraries, with availability per library. It never names the sibling it differs from (e.g. get_title for a single known title vs get_availability), so it falls short of 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?

Usage is only implied: 'Search one library or several at once' suggests a discovery context, and the schema note 'Omit to browse' hints at browsing mode, but the description gives no explicit when-to-use or when-to-prefer-get_title/get_availability guidance.

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