Library of Alexandria

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is lower. The description adds pagination behavior ('up to 8 titles at a time, with a cursor for the next page'), which is useful context, but that largely restates the limit/cursor schema. It says nothing about ordering within a shelf (how 'popular' is ranked) or what an exhausted cursor looks like.

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 resource and its variants, then the return shape. No filler and nothing an agent must read twice.

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 four-parameter paginated browse tool with rich annotations and full schema coverage, the description covers the collection choices and paging contract adequately. Without an output schema, a hint about the title record shape would have closed the remaining gap, but the essentials for correct invocation are present.

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 baseline is 3, but the description earns extra credit by glossing the enum values in human terms — 'free books', 'reading levels', 'the titles with a 15-minute summary' — which tells the agent what 'with-summary' and 'challenging' actually mean. Limit and cursor semantics are left entirely to the schema, which already handles them well.

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 and resource ('Browse a ready-made shelf of the library') and enumerates the exact shelves available, so the agent knows precisely what it fetches. It does not explicitly distinguish itself from close siblings like list_free_shelf or search_books, even though 'free books' overlaps with one of them.

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 implied by the shelf enumeration — an agent can infer it should pick 'popular' or 'easy' when that's what the user wants. There is no explicit statement about when to prefer this over search_books or list_free_shelf, and no exclusions or prerequisites.

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?

Adds real context beyond the annotations: nothing is ordered or paid through the assistant, and no card or address is collected here – critical to prevent an agent from treating this as a transaction or asking for payment details. The readOnlyHint/idempotentHint annotations are consistent with this, though the description does not mention idempotency or the 24-hour quote window itself.

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 trigger ('Continue from a quote') and ending with the key guardrail. The middle clause ('the address of the page on libraryofalexandria.com where the person writes the message, sees the proof and pays') is slightly roundabout but earns its length by explaining the destination.

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, no-output-schema tool, the description says what is produced (a page address), what the user does there, and what this tool explicitly does not do (order, pay, collect card/address). Nothing an agent needs to call it correctly 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 only parameter, quote_id, already carries its own description including the 24-hour validity rule. The description adds no syntax, format, or failure-mode detail about quote_id, so 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?

States the action concretely: 'Continue from a quote: get the address of the page on libraryofalexandria.com where the person writes the message, sees the proof and pays' – an agent can tell this returns a URL to a hosted checkout/proof page. It does not distinguish itself from similarly-themed siblings such as quote_custom_print, get_print_options or get_cover_upload_link, so the 'create order' name could still be misread as placing an order.

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?

'Continue from a quote' implies a precondition (an existing quote) but never states it as a requirement or names an alternative path (e.g. quote_custom_print) for starting a new quote. Usage is inferable but not spelled out.

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, idempotentHint, and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: an unknown phrase does not error but returns the closest matching phrases, which is exactly the kind of degradation behavior an agent needs to know.

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, no filler, with the primary capability front-loaded and the fallback case appended where it belongs. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description still enumerates the three return components (meaning, origin, titles used in) and the near-miss fallback. Minor gap: it doesn't indicate result count or ordering for the 'closest phrases' case.

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%, with the phrase example and the full language enum plus its defaulting rule already documented in the schema. The description adds no additional param meaning, so 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?

Specific verb+resource ('Explain a saying or idiom') followed by the exact content returned: meaning, origin, and library titles that use it. That distinguishes it from book-oriented siblings like get_book or search_books, though no sibling is named explicitly.

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 implied by the resource type (idioms/sayings rather than books or passages), but the description never states when to prefer this over find_quote_source or search_books, nor any prerequisites. The nearest-alternative routing is left to inference.

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 read-only, idempotent, non-destructive and closed-world, so the safety burden is light. The description adds genuinely non-redundant behavior: results are limited to open texts and the book's own words are never returned, which sets the agent's expectations about coverage and output. It does not cover no-match behavior or how multiple matches are ordered.

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 purpose and followed by the return payload and the constraint. No filler or restated title boilerplate.

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 no output schema, the description carries the return-shape burden and does list the returned fields plus a read address. It is nearly complete for a simple two-parameter lookup, with only edge cases (no match, multiple matches) left implicit.

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 the schema already explains both the quote string and the language enum in detail. The description only echoes the six-word minimum, which is already in the schema, and says nothing extra about the language parameter. Baseline 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 names a specific verb and resource ('Find where a quotation comes from') and immediately states the output shape (title, chapter, paragraph, address). This clearly distinguishes it from siblings like explain_phrase or search_in_book, which do different jobs with text.

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 states the trigger ('give at least six words of it') and a hard scope limit ('answers only for texts that are open'), which effectively tells the agent when the tool will not help. It stops short of naming alternatives such as search_in_book for closed texts, so it is not a full when/when-not treatment.

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, idempotent, non-destructive, and closed-world behavior, so the bar is lower, and the description still adds real value: it discloses the language-fallback behavior (a language with no page on the site is simply omitted, so the list can be shorter than the catalogue's languages) and explains that `url_language` signals when `url` is in a different language than requested. These are non-obvious output-shape traits an agent would otherwise get wrong. It stops short of saying what happens when the id does not resolve.

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?

Front-loaded with the core action, then the returned fields, then the one edge case, so the agent can stop reading early. It is a single dense sentence plus a short follow-up with no filler. The long parenthetical about missing language pages is heavy but carries genuine information rather than padding.

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 no output schema, the description correctly takes on the job of enumerating return values, and it does so field by field, including the caveat about truncated language lists. Annotations handle the safety profile, so nothing critical is missing. The remaining gap is error behavior for an unknown id and any indication of whether print-edition data can be large.

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 both parameters carry thorough descriptions, including the enum labels and the default-language rule, so the baseline of 3 applies. The description largely restates the language behavior the schema already documents ('in the chosen language', 'url_language says when url is in another language than the one asked') rather than adding new syntax or format detail. It introduces `url_language`, but that is a return field, not a parameter.

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 ('Get the catalogue facts of one title') and enumerates the exact fields returned: title, subtitle, author, original title, cover address, print editions, and per-language title page addresses. That is far more specific than the name alone. However, it never distinguishes itself from close siblings such as get_book_facts, get_book_outline, or get_summary, so an agent cannot tell from the description alone which of these overlapping 'book facts' tools to pick.

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 contains no when-to-use, when-not-to-use, or alternative-tool guidance at all. It does not say that an id must first come from search_books (that hint lives only in the schema), nor does it steer the agent away from get_book_facts or toward get_book_outline for chapter-level content. Any usage context must be inferred entirely from the sibling list.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: unknown facts come back explicitly as 'not available yet' rather than being omitted, which tells the agent to expect partial payloads and not to treat gaps as errors.

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 verb and resource, then a dense field list that mostly earns its length by substituting for the absent output schema. The long inline enumeration is slightly run-on and would read better as a list, 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?

For a simple read-only lookup with no output schema, the description carries the return-shape burden itself by naming every fact category, and the schema fully covers both inputs. Nothing an agent needs in order to call this correctly and interpret the result 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 both parameters are richly documented in the schema itself — id format examples (top3500-00013) plus the fallback that a plain number means a main-list number, and the full language enum with a stated default. The description adds no parameter-level meaning of its own, 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?

States a specific verb and resource (reading facts of one title) and enumerates the exact fields returned — reading level, word count, reading time, page counts, audio length, chapter count, first publication year, summary availability — which effectively scopes it away from siblings like get_book, get_book_outline and get_summary. It never names those siblings explicitly, so the differentiation is implicit rather than stated.

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: fetch this when you have a title id and need quantitative reading facts. There is no statement of when to prefer get_book or get_summary instead, no prerequisite or cost note, and no exclusion. Adequate but leaves routing to the agent's inference.

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 and idempotency (readOnly, idempotent, non-destructive, closed world), so the bar is lower, and the description still adds real context: results are filtered to open titles and chapter text is deliberately excluded. It does not say whether a non-open title yields an empty list or an error, which is the one behavior an agent would still need.

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, no filler. The returned data is stated first, then the two hard constraints (open titles only, no chapter text), both front-loaded.

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 no output schema, the description correctly tells the agent what comes back (chapters and their access) and what does not (chapter text). For a simple two-param read tool this is nearly sufficient; the only gap is how the access value is shaped and what happens for restricted titles.

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 both parameters (id, language) carry detailed descriptions including format examples and default-language logic, so the schema does the work. The tool description adds nothing about parameters, which is acceptable at this coverage level but earns only the baseline.

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 ("List the chapters") plus the extra returned field (access) and the audience (signed-in member). It also bounds scope with "Only open titles are shown, and no chapter text is returned." It never names a sibling (e.g. get_book, get_chapter_summary, get_passage) to contrast with, so differentiation is inferred rather than stated.

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?

"for the signed-in member" implies an auth prerequisite and the open-titles constraint implies when results will be thin, but there is no explicit guidance on when to pick this over get_book or get_chapter_summary, nor what to do when a title is not open. Usage is implied by context, not spelled out.

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 the read-only, idempotent, non-destructive profile, so the description's added value is notable: it discloses summary length ('a few hundred words at most'), the chaining behavior ('points to the next one'), and the availability/lock state message for unopened summaries. That last detail is real behavioral context an agent would not otherwise know.

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?

Compact and front-loaded: the primary mode is stated first, followed by the list mode, then two short caveats about length and availability. No wasted sentences.

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 no output schema, the description carries the burden of explaining returns and does so reasonably: it characterizes the summary content, the chapter-list shape, and the not-yet-open state. Minor gaps remain around how the 'points to the next one' reference is expressed, but the essentials are covered.

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%, including the enum languages and the note that omitting chapter returns the list, so the schema does the heavy lifting. The description restates the chapter-omission behavior but adds no format or syntax detail beyond 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 ('Get the summary of one chapter, act or section') and clearly covers the dual mode of returning either a summary or a chapter list. It does not, however, distinguish itself from related siblings like get_summary or get_book_outline, so an agent must infer the granularity difference.

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 'without a number, the list of its chapters' clause gives implicit guidance on when to omit the chapter parameter, but there is no explicit statement of when to prefer this tool over get_summary or get_book_outline. Usage context is implied rather than stated.

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, openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavioral context: the cover upload is not live yet, so the returned link currently resolves to the personal-message page instead. That caveat is exactly the kind of disclosure the agent cannot get from structured fields, though it does not describe the response shape.

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 with no filler: purpose first, then the important current-state caveat. The phrase 'Uploading a cover opens here soon' is slightly awkward phrasing but carries real information, so nothing should be cut.

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?

There is no output schema, and the description leaves the return format vague — 'the answer points to the page' suggests a URL or page reference but does not say whether it is a string, an object, or a rendered page handle. The availability caveat is a strong addition, but for a link-returning tool with no output schema, one more sentence on what comes back 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 100%, so both the title `id` and the `language` enum are fully documented in the schema itself, including format examples and defaulting behavior. The description adds nothing about either parameter, so baseline 3 applies; no compensation is needed and none is given.

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 first sentence names a specific verb and resource: 'Get the page where a person can add their own cover picture to a printed copy.' That is a concrete artifact (an upload page for a custom print cover), and it implicitly distinguishes itself from siblings like get_listen_link and open_in_reader, which serve different media. It falls short of a 5 because it never names the sibling it complements (create_custom_print_order/quote_custom_print), leaving the routing inference to the agent.

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 implied rather than stated: an agent can infer it should call this when a person wants to personalize a printed copy's cover. There is no explicit when-to-use, no precondition (e.g. after an order or quote exists), and no named alternative. The fallback sentence clarifies behavior but is not guidance about selection.

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?

Beyond readOnly/idempotent annotations, it adds useful behavioral facts: no audio is returned and access is checked by the listen page, and access is tied to the signed-in member. It doesn't cover rate limits or error cases, but it meaningfully reduces ambiguity.

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 with the core purpose front-loaded and no filler. The 'no audio' clarification is brief and earns its place.

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-only link getter with fully documented params and rich annotations, the description supplies the key missing context: the return is an address, not audio, and access is delegated to the listen page. Nothing essential 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 description adds no parameter-level meaning beyond 'open title'; id, chapter, and language semantics are fully covered by the schema. Baseline 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?

States a specific verb and resource ('Get the listen page address of an open title') and scopes it to the signed-in member. It also clarifies the return is a page address, not audio, which helps distinguish it from reader/audio siblings, though it does not name an alternative outright.

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 implied context—signed-in member, open title, and no audio—but never states when to choose this over siblings such as open_in_reader or get_sample, nor any exclusions.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond them: the result is scoped to the signed-in member, passages are restricted to titles the caller can open, and consumption is capped by a daily word limit.

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 that front-load the primary output (plan and daily words left) and then qualify the scope. No filler or restatement of the title.

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 no output schema, the description does name the shape of the return (plan plus remaining word allowance) and the access constraint. It stops short of describing additional fields an agent might expect, such as words consumed today or reset timing, which for a quota tool would be useful.

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 nothing for the description to disambiguate; the baseline of 4 applies. It correctly implies the member identity is derived from the session rather than passed in.

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 (read) and two concrete resources: the member's plan and remaining daily words. That distinguishes it from the sibling read tools (get_passage, get_book, list_my_library), though 'the plan' is never defined and only the name/title disambiguate it as a reading plan.

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: mentioning 'daily words left' and a daily word limit hints that an agent should consult this before reading, but it never says when to call it, when not to, or names any alternative (e.g., list_my_library for the shelf contents).

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 a safe, idempotent, read-only lookup, so the description's main added value is the disclosure that today's answer merely points to the order e-mail and the libraryofalexandria.com account, with assistant-side tracking not yet available. That limitation is genuinely useful, but it is phrased so vaguely ("opens here soon") that the agent cannot tell what the tool actually returns versus what is deferred.

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 first sentence is tight and front-loaded, but the second is a run-on that mixes a partial output description with an unclear roadmap note ("tracking through an assistant opens here soon") that does not help an agent decide or invoke correctly.

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 no output schema, the description should clarify what comes back, and it only half does so in an ambiguous way. It omits failure behavior (e.g., what happens when the e-mail does not match the order) and does not state the prerequisite relationship between the two required parameters.

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 order_ref, email, and the language enum all documented in detail, so the schema does the heavy lifting. The description adds no meaning about parameter formats or the requirement that the e-mail match the order, 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?

"Check where a printed order stands" gives a specific verb and resource and clearly separates this from siblings like create_custom_print_order or get_my_plan. The second sentence, however, blurs what the tool actually returns, leaving the agent unsure whether it delivers tracking data or just a pointer to the account page.

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 explicit when-to-use or when-not-to-use guidance, and no mention of the prerequisite that both the order reference and the matching e-mail address are needed. The agent must infer the call context from the first sentence alone, with no routing to 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still contributes two non-obvious traits: per-call access re-checking (auth context) and a 400-word cap per passage. It does not describe error behavior when the locator has expired, which would complete the picture.

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 zero filler; the core action is front-loaded and the access and length constraints follow in order of decision relevance. Nothing is repeated from annotations or 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?

For a simple 3-parameter read tool with full schema coverage and no nested objects, the description covers what the tool returns (a passage plus neighbors, capped at 400 words) and the auth model. Only the failure mode for an expired/invalid locator is left unaddressed.

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 all three parameters (before, after, locator) are already documented with bounds, defaults, and the 24-hour locator lifetime — baseline 3. The description reinforces the 'nearby paragraphs' semantics of before/after and adds the word cap, but adds no format or edge-case detail beyond 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?

Specific verb + resource + scope: 'Read a located paragraph with nearby paragraphs for the signed-in member.' An agent can distinguish it from search_in_book (which produces locators) and from summary-oriented siblings. It stops short of naming an alternative explicitly, and the title merely restates the name.

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: 'located paragraph' plus the schema's note that locator comes from search_in_book suggests this is a follow-up call, but the description never states when to prefer it over get_chapter_summary, get_book_outline, or a fresh search_in_book. No exclusions or prerequisites are given in the description text itself.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that: prices are in US dollars, and the qualifiers 'where it exists' and 'where known' tell the agent that price, ISBN-13 and page count can be absent, which is important for handling partial results. It does not mention pagination or result ordering, keeping it at a 4.

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 sentence with zero filler, front-loaded on the verb and resource, with the return fields listed after. It is dense and slightly run-on with its nested parentheticals, but every clause carries information an agent needs.

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?

There is no output schema, so the description must carry the return contract — and it does, naming every returned field and flagging which are conditional. Combined with a fully documented two-parameter schema and complete annotations, an agent has everything needed to call and interpret this tool.

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% — the id format and the full language enum with per-code meanings and default behavior are already documented in the schema. The description only implies the 'one title' scoping of id and says nothing extra about the language parameter's effect, 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?

States a specific verb and resource ('Get the print editions of one title') and enumerates exactly what comes back: standard/large print, paperback/hardcover, USD price, ISBN-13, page count, product page URLs. This is clearly distinct from get_book or quote_custom_print, though it never names a sibling to contrast with, so it stops 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?

Usage is only implied: an agent can infer it should call this when it needs print-edition availability, price, or ISBN for a known title id. There is no explicit when-to-use guidance, no mention of quote_custom_print or create_custom_print_order as alternatives, and no stated preconditions (e.g., that the id must come from a search result).

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. With no output schema, the description usefully carries the return-content burden by naming the three fields returned, which is real added value beyond annotations. It stops short of describing format or whether the catalogue language list is full or a subset.

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 front-loaded sentence that names the verb and then lists exactly what comes back. No filler, no restatement of the name or title.

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 zero-parameter, zero-output-schema tool the description adequately covers both invocation (none needed) and return surface. The remaining gap is that it doesn't state that the result is for the one catalog publisher rather than a specified one, nor the shape of the returned languages/terms address.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The absence of any selector parameter is consistent with the description returning global publisher metadata, which is a reasonable silent implication.

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?

Specific verb ('Get') plus resource ('publisher info'), and it enumerates the actual payload: publisher description, catalogue languages, terms page address. It clearly isn't get_book or get_summary. The one ambiguity is that no parameter exists to select a publisher, and the description never says the info concerns the catalogue's single owning publisher, so an agent may wonder which publisher is meant.

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 enumerated return contents: call it when you need publisher metadata or terms-of-service links. There is no explicit when-to-use, when-not-to-use, or routing to siblings like get_book or get_summary, but the tool's scope is narrow enough that the intent is inferable.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: 400-word page limits, answers reporting page count and continuation, and a placeholder response while the text is not yet open.

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 three short sentences with the purpose front-loaded, followed by pagination behavior and the unavailable-text state. Every sentence carries useful information and 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?

For a simple paginated read tool with full schema coverage and explicit read-only annotations, the description covers purpose, pagination, and the 'opens here soon' state. It could say more about the response shape or error cases, but it is adequate for this tool.

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 the schema already explains id, page, and language thoroughly, including the language enum. The description reinforces pagination and the 400-word page size but adds little parameter meaning beyond what the schema provides.

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: reading the free opening / first chapter of one title, with pagination of at most 400 words. It does not explicitly distinguish this from the sibling tool read_free_chapter, so it stops 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?

Usage is implied by 'Read the free opening' and the instruction to pass 'page' for continuation, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as read_free_chapter or get_passage.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value beyond that: it discloses the exact return shape (first key idea full, other headings only) and, notably, that an unavailable title or language returns a soft 'opens soon' message rather than an error — a non-obvious behavior an agent needs to interpret results correctly.

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?

Three sentences, front-loaded with the core return description before parameter guidance and the availability caveat. Some phrasing is awkward ('answers that it opens here soon'), but there is little waste.

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 no output schema, the description does the work of explaining what comes back (full first key idea with heading, other headings only) and how language affects returned text. It stops short of explaining pagination or whether the headings themselves are actionable, but nothing critical to a correct call 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 enum lists every language code with names, so the schema carries the weight. The description adds only a little: it ties 'part' to choosing a key idea and implies part defaults to the first. Baseline 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?

States a specific verb and resource with scope: read the 15-minute summary of one title, returning the first key idea in full plus headings of the rest. That content shape distinguishes it from siblings like get_book_outline or get_chapter_summary, but the description never names an alternative explicitly, so an agent must infer the boundary.

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?

'Choose a key idea with part' gives usage for one parameter, and the note that unopened summaries respond that they will open 'here soon' implies availability handling. However, there is no explicit when-to-use vs. get_chapter_summary, get_book_outline, or get_book, and no stated prerequisites beyond the id.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. It does: it discloses the output granularity ('each in a few sentences'), that a full-guide address is included, and the edge-case behavior for titles/languages whose guide is not yet open.

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 verb and return contents, no filler. The second sentence's phrasing ('says that it opens here soon') is slightly informal but still earns its place by covering the unavailable-guide case.

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 no output schema, the description carries the burden of describing return values, and it does so specifically (themes, symbols, setting, motifs, guide address, per-item brevity). The unopened-guide case is also handled, leaving little an agent would need to guess.

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 the id format and the language enum/default fully documented in the schema, so the baseline is 3. The description only reinforces the single-title scope ('of one title') and does not add format or fallback detail beyond 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 ('Get the study guide of one title') and enumerates the exact contents returned: themes, symbols, setting, recurring motifs, plus the address of the full guide. This content list implicitly separates it from siblings like get_summary or get_book_outline, though none of those alternatives are named explicitly.

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: an agent can infer this is the tool for thematic analysis of a single title, and the note about guides 'not open yet' tells it what happens for unavailable titles. There is no explicit guidance on when to prefer this over get_summary, get_book_outline, or get_chapter_summary.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return shape — each title comes with the address of its reading page — which matters since no output schema 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?

One sentence, zero waste, with the core action front-loaded and the optional modifiers and return detail trailing in logical order.

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 three-optional-parameter read tool with full schema coverage and no output schema, the description covers purpose, filtering and a return detail. It does not explain what constitutes the 'free shelf' or note the 1–8 cap, but the schema handles the latter and the omission is minor.

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 enum for language is fully documented inline, so the schema carries the parameter burden. The description only echoes that language and subject are optional single-value filters and adds no format or default detail beyond 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 ('List the titles on the free shelf') plus the optional filter dimensions and a return detail ('address of each reading page'). The concept of a 'free shelf' is distinctive enough to separate it from search_books or list_my_library, though it never names a sibling to contrast against.

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 implied: call this to surface free-to-read titles, optionally narrowed by language or subject. There is no statement of when to prefer it over read_free_chapter or search_books, and no exclusions or prerequisites.

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 readOnly, idempotent, non-destructive, and closed-world, so the bar is lower. The description still adds real value: the 50-item page cap and the explicit statement that book text is never returned, which tells the agent to fetch get_book or get_passage for content.

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, no filler, with the core scope (whose books) front-loaded and the pagination and content-exclusion constraints immediately after.

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 no output schema, the description must say what comes back; it names the shape ('saved books with their reader addresses') and excludes book text, which is enough for an agent to know the payload. It could say more about ordering or pagination termination, but the essentials are present.

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% with per-parameter descriptions and an enum on status, so the schema already carries the semantics. The description's only added detail is the 50-item ceiling, which is already encoded as the limit maximum in 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 ('List the saved books of the signed-in member') and scopes it to the caller's own library, which implicitly separates it from search_books or browse_collection. It stops short of naming a sibling to route away from, so it is clear but not maximally differentiating.

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 this is the tool for the caller's personal saved books, but never states when to prefer it over search_books or browse_collection, nor any prerequisites or exclusions. The '5 at a time' pagination note is behavioral rather than usage 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 establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond that: the caller must be a signed-in member, only open titles are linked, and chapter access is checked by the reader itself. It stops short of describing error behavior for closed titles or expired access, so it is strong but not exhaustive.

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, both front-loaded with the essential operation and the key access constraint. There is no repetition of schema or annotation content and no unnecessary preamble.

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 low-complexity read tool with full schema coverage and annotations covering safety, the description supplies the crucial auth and access constraints. Without an output schema, a brief note on the address format or failure behavior for unlinked titles would complete it, but it is otherwise adequate.

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 the schema already defines id, chapter, language, and paragraph in detail. The description adds no parameter-specific meaning, so the baseline score 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 and resource: 'Get a chapter address ... to open in the reader', scoped to the signed-in member. It is clearly not a full book fetch or a free-chapter read, though it does not name sibling alternatives like read_free_chapter or get_book explicitly.

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 implied by 'to open in the reader' and the signed-in member constraint, but there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternative such as read_free_chapter for free chapter reading.

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 readOnly/idempotent/non-destructive, and the description reinforces this by making clear no order is placed here—the actual order happens on the linked page. It also discloses that shipping and tax are only shown at checkout, which is useful behavioral context not present in the 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?

A single dense but front-loaded sentence that leads with the core action and then lists the outputs. Every clause is informative; slightly long but 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?

For an 8-param tool with nested objects and no output schema, the description usefully narrates the return (price, total, order page URL) and the checkout caveat. Remaining gaps (id/country/language semantics) are covered by the reasonably rich 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?

With 75% schema coverage the schema carries most parameter meaning. The description adds the edition choices (paperback, hardcover, large print) and clarifies that quantity produces a total, but says nothing about id, country, language, cover mode, or gift fields beyond what the schema already documents.

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 action (prepare/quote a printed copy of one title with a personal message page) and enumerates what comes back: price per edition, total for the copies, and the page address for ordering. It is clearly distinct from browsing/searching, though it never names the sibling create_custom_print_order, so the quote-vs-order distinction is only implied.

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 context ('as a gift or for yourself') and implies this is the price-check step before ordering happens elsewhere ('the order is placed' on the site), but it never explicitly says when to use this versus create_custom_print_order or get_print_options. Usage is implied rather than spelled out.

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 establish that this is a safe, read-only, idempotent operation. The description adds useful behavior beyond that: pages are capped at 400 words, every answer points to the next page, and unavailable text reports that it opens here soon.

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 compact and front-loads the core action and scope. The later sentences about pagination and unavailable text are useful, though the final sentence is slightly indirect.

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 tool with complete schema coverage and no output schema, the description covers the essential context: what is read, page size, chapter numbering, defaults, and forward-page behavior. It does not fully describe the returned chapter payload, but the key behavioral expectations are present.

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 the parameters are already well documented. The description reinforces chapter-numbering semantics and the default first chapter, but adds little detail beyond what the schema already says.

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: 'Read one chapter of a title on the free shelf.' The 'free shelf' scope helps distinguish it from general book tools, but it does not explicitly name sibling alternatives such as get_sample or open_in_reader.

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 implies usage for free-shelf titles and explains the default chapter behavior, but it gives no explicit when-to-use guidance versus alternatives like get_sample, open_in_reader, or get_passage.

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 the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds real behavioral context: two distinct input interpretations, what is returned in each case, and the available filter dimensions. It stops short of describing result ordering, how limit interacts with the two modes, or ranking rationale.

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 tool name and the primary mode, with no filler. The semicolon-joined clauses make it slightly run-on, but every phrase (liked book, topic/mood, filters) 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 100% schema coverage and annotations, the description covers the essential decision points for a 5-parameter, single-required-param tool. Since there is no output schema, it could say more about the shape of a returned recommendation (beyond 'titles'), but the language parameter in the schema hints at returned fields.

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 schema itself documents all five parameters, including the dual meaning of query and the level/free_only filters. The description restates the query modes and filters but adds no syntax, format, or edge-case guidance beyond what the schema already provides, 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?

States a specific verb (recommend) and resource (classics/books) and spells out its two operating modes: a liked title/id yields readers-also-enjoyed titles, while a topic/mood yields matching titles. It does not explicitly distinguish itself from search_books or browse_collection, so an agent must infer that this returns recommendations rather than exact matches.

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 when to use it (you have a liked book, or a topic/mood) and adds filter guidance ('Filter by reading level or by the free shelf'). But it never names an alternative tool or states when not to use it, e.g. versus search_books for direct title lookup.

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, idempotent, non-destructive, closed-world. The description adds real context beyond them: a hard cap of 8 results, the field set returned (id, title, subtitle, author, language, print availability, page address), and that output language follows the asker. It does not discuss ranking, empty-result behaviour, or partial-match semantics.

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 searchable scope before the return description. Dense but readable; the enumerations of languages and returned fields make it longer than strictly necessary, yet each clause carries information an agent needs given there is no output 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 no output schema, the description compensates by listing the returned fields, and it covers the query, language and result cap. Missing only the edge cases — what a zero-hit response looks like and how results are ordered — which are minor for a catalogue search.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description earns an extra point by clarifying that the query accepts any catalogue language (with a note on Chinese scripts) and by reframing 'language' as the asker's language that drives the returned titles/authors — semantics beyond the raw enum list.

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 the catalogue of Library of Alexandria Press) and the exact matching semantics — title words, author name, or topic word, in any catalogue language including simplified/traditional Chinese. It also names the returned fields, which further distinguishes it from siblings like get_book or search_in_book.

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 establishes clear context: use it when the asker supplies words from a title, an author name, or a topic. It does not explicitly exclude or name alternatives (browse_collection, search_in_book, recommend_classics), so routing between siblings still requires inference.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add operational context — and it does: result count is capped at five short snippets, and output is constrained by 'word and reading limits', plus an access restriction to chapters open to the member. Minor gaps remain (ranking/relevance behavior, what an empty result looks like) but this is meaningful added context.

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, both front-loaded with the most decision-relevant information: first what it finds and where, then what comes back. No filler or restatement of the name.

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 no output schema, the description carries the return-value burden and does so at a high level (up to five short snippets, bounded by word/reading limits) while also disclosing the access constraint. It stops short of describing relevance ordering or empty-result behavior, but an agent has enough to call it 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 description coverage is 100%, so all four parameters are already documented, including the enum languages and the 2-80 character query constraint. The description only echoes the keyword nature of the query and the five-result cap; it adds no syntax, matching, or language-resolution detail beyond the schema. Baseline 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?

States a specific verb and resource ('Find paragraphs by keywords') and scopes it to 'chapters open to the signed-in member', which separates it from the sibling search_books (which searches across books, not inside one). It never names the alternative explicitly, but the 'in book' framing plus the required id parameter make the distinction inferable.

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 implied rather than stated: the description establishes the precondition that only chapters open to the signed-in member are searched, which is real guidance. It gives no explicit when-to-use/when-not guidance and doesn't point to alternatives like get_passage, find_quote_source, or search_books for locating the title id first.

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