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

Annotations already establish that the operation is read-only and idempotent. The description adds useful behavioral context beyond that: newest-first ordering, 20-per-page pagination, edition names appearing on each comment, and the fact that edition_id filters the fetched page. 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?

Two focused sentences carry all essential information with no filler. The core purpose and ordering/pagination are front-loaded, followed by the edition-related nuance and parameter guidance.

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, 3-parameter tool with no output schema, the description gives enough information to understand what will be returned: comments, sorted newest first, paginated, with edition context. It could be slightly more complete about the id parameter's dual role as book_id or edition_id, though the schema covers that.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description restates the edition_id filtering behavior but adds little beyond the schema, aside from clarifying that filtering applies to the fetched page.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource (reader comments on a book) and adds scoping details (newest first, 20 per page, edition labeling). It does not use an explicit verb like 'list' or 'get', and it never names sibling tools to contrast against, so it falls just 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 description implies when to use the tool (when reader comments are needed) and gives specific guidance on passing edition_id to filter. However, it does not explicitly distinguish book_comments from close siblings like book_details or book_editions, nor state when not to use it.

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 readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is established. The description adds useful behavioral context: it returns a vote-weighted rating, an editions summary with buyability and pricing details, and a compact list. It also mentions 'compact' to set expectations about output size, which goes 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?

The description is a single, information-dense sentence that front-loads the core purpose ('Everything about one book') before enumerating the specific data points. It ends with a clear routing instruction to book_editions. Every clause earns its place with zero redundancy.

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

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

For a read-only summary tool with annotations covering safety and schema covering parameters, the description is complete. It clearly defines the output scope and the alternative for deeper data. The absence of an output schema is compensated by the description's enumeration of what is returned, and no critical usage condition 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 description coverage is 100%, so all three parameters (id, editions_limit, include_description) are already documented in the schema. The description does not add meaning beyond what the schema provides; it mentions 'compact list' which relates to editions_limit, but that's already implied. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's scope: 'Everything about one book (work)' and enumerates the exact contents (description, highlights, categories, rating, editions summary, compact list). It distinguishes itself from the sibling tool book_editions by explicitly noting it provides a summary rather than full per-edition 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?

The description explicitly says 'Use book_editions for full per-edition data and filters,' providing a clear when-not condition and naming the alternative. This tells an agent exactly when to choose this tool over its sibling, leaving no ambiguity.

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 as read-only, idempotent, and open-world, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: full data per edition, price and discount in Toman, stock state, earliest delivery, and the important interpretation of print run as a popularity indicator. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense and front-loaded with the main purpose before the field enumeration. The field list is long but each item adds practical value, and the closing question succinctly captures the tool's decision-support role. It is slightly long, but not wasteful.

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 enumerating the returned data fields, including units, Persian terms, and the print-run interpretation. The schema covers parameters, and annotations cover safety and idempotency. It does not describe errors or edge cases, but for a read-only comparison tool this is acceptable.

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 documents all six parameters thoroughly. The description adds some interpretive context (e.g., print run meaning, 'cheapest/available' aligning with sort and only_available), but most parameter semantics remain in 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?

The description clearly identifies the resource: all editions of one book, with a full list of per-edition fields. It also states the core use case: answering which translation is best, cheapest, or available. It stops short of a 5 because it lacks an explicit verb like 'list' or 'get' and does not explicitly name a sibling tool to differentiate from, though 'one book' helps distinguish it from search and browse tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when comparing editions or translations of a specific book and deciding among them. It does not explicitly state when not to use it or name alternatives, but the 'one book' scope and the quoted comparison questions make the intended usage obvious.

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 carry the read-only/idempotent/open-world safety profile, so the description rightly focuses on behavior the annotations do not express: that entries are editions priced in Toman with discount, and the operational nuance that 'no_current_offer: true' usually signals out of stock. This adds real value beyond the structured fields without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose first, then provenance, then output format plus a stock caveat. Mild redundancy exists between the sourcing sentence and the schema's tag_id description, which trims a point, but the structure is tight and 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?

For a read-only browse tool with no output schema, the description compensates well by describing the return shape (editions, price in Toman, discount) and flagging the stock edge case. Required tag_id, pagination, and sort options are all covered by schema or enum, so 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 75% and tag_id already carries provenance text, so the baseline is near the 3 anchor. The description adds concrete example ids that give the abstract tag_id a concrete meaning, but much of the sourcing sentence duplicates the schema's own tag_id description, adding only marginal value.

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 verb 'browse' with the resource 'one iranketab category/genre/list' is specific, and the concrete tag examples (152, 328) anchor the meaning. It is clearly distinct from search-based and similarity-based siblings in spirit, though it never names a sibling to differentiate itself explicitly, 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?

The description offers genuine routing guidance: tag ids 'come from book_details tags or find_author_publisher_or_tag' and 'confirm with book_editions' for stock. However, it never states when to prefer this over search_books or similar_books, leaving the primary selection criterion implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds value by explaining the tool is a resolver (name → id) and that the id is meant to be fed into other tools, which is behavioral context beyond the annotations. It doesn't describe pagination or result format, but for a read-only resolver with annotations covering safety, this is a minor gap.

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. The core purpose is front-loaded ('Resolve a name to its iranketab id'), the kind semantics are compactly explained with examples, and the downstream routing is stated in the second sentence. Every clause 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 read-only resolver with no output schema, the description covers the essential context: what it does, what the kinds mean, and how to use the result. The main gap is that it doesn't describe the output shape (e.g., whether it returns a list of {name, id} objects), but since the tool is explicitly a resolver and the downstream tools are named, an agent can infer the output is an id. Given the tool's simplicity and annotation coverage, this is nearly complete.

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

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

Schema description coverage is only 33% (only limit has a description; query and kind lack descriptions). The description compensates by explaining kind's enum values in detail (person = authors AND translators, publisher = publishers, tag = categories/genres) and giving examples. It also implies query is a name string. However, it doesn't explicitly describe the query parameter's semantics beyond 'a name', and limit's semantics are already in the schema, so the description adds meaningful but not complete parameter coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Resolve') and resource ('a name to its iranketab id'), and explicitly enumerates the three kinds (person, publisher, tag) with examples. It also distinguishes itself from siblings by naming the downstream tools (person_books, publisher_books, browse_tag) that consume its output, so an agent can tell it apart from search_books and browse_tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use this tool to resolve a name to an id, then feed that id into person_books, publisher_books, or browse_tag. It also clarifies that kind=person covers both authors AND translators, and kind=tag covers categories/genres with examples. This effectively routes the agent to the correct sibling tools and prevents misuse.

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

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

The description provides some behavioral context beyond annotations: it explains the 'no_current_offer: true' field and its typical meaning, which is helpful. The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to repeat that. It adds value by explaining a specific field in the output, even though it's not a full behavioral contract. It doesn't contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two sentences. The first sentence states the core purpose, and the second provides a practical tip. It is front-loaded with the main function. However, it could be slightly more structured, but it's still efficient and to the point.

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

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

Given the tool's complexity (4 parameters, one required, and a rich output with pricing), the description is fairly complete. It clarifies the author/translator nuance and hints at output fields. An output schema is not provided, so the description helps interpret responses. It lacks explicit details on pagination or sorting, but those are in the schema. Overall, it's adequate for an agent to select and use the tool 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 75%, meaning most parameters are described in the schema. The description does not add much about the parameters beyond the schema; it doesn't explain 'page' or 'limit' semantics further, but the schema already does. The description adds value by mentioning that entries are editions with price and discount, and the 'no_current_offer' field, which helps interpret results. For the 'person_id' parameter, the schema says it comes from find_author_publisher_or_tag or book_editions, which is clear. So the description adds slight value by explaining output semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this tool returns every edition an author wrote or a translator translated, distinguishing it from other tools like publisher_books and browse_tag. It also mentions the nuance that iranketab treats authors and translators as one profile, which is specific and informative. The verb 'find' is implied but the resource is very clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that the tool is for both authors and translators, and hints at using it when you need editions by a person. It mentions confirming out-of-stock status with book_editions, which gives context for when to use that alternative. However, it doesn't explicitly say when not to use this tool compared to similar_books or search_books, but the sibling list is small and the description gives enough context to make a decision.

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, openWorldHint, and idempotentHint. The description adds meaningful behavioral context beyond those annotations: entries are editions with pricing in Toman and discount, and `no_current_offer: true` usually means out of stock, with book_editions as a confirmation path. This does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. The core purpose is front-loaded, and each clause contributes either output semantics or a practical caveat. Nothing is redundant or extraneous.

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 list tool with one required parameter, enum sort, pagination, and safety annotations, the description supplies the key output semantics and the important out-of-stock caveat. It does not enumerate every possible return field or pagination behavior, but with no output schema and strong annotations, the provided information is sufficient 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 75%, with page, limit, and publisher_id already described; sort has an enum but no gloss. The description does not add parameter-level guidance beyond the schema, so it neither compensates for nor detracts from the schema documentation. A baseline of 3 is appropriate given the high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific scope ('the catalogue of one publisher') and the result unit ('editions with price in Toman and discount'), making the tool's role clear. It is distinguishable from broad search tools, though it does not explicitly name a sibling alternative or use an action verb beyond the noun 'catalogue'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: get a single publisher's catalogue. The only explicit usage guidance is the caveat that `no_current_offer: true` usually means out of stock and that you should confirm with book_editions. There is no explicit statement of when to prefer publisher_books over related tools like search_books, browse_tag, or person_books.

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, and open-world hints, so the bar for extra disclosure is lower. The description adds useful behavioral facts beyond annotations: results are capped at 100 hits and search cards omit pricing. This helps the agent set expectations without contradicting 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?

Four tight sentences front-load the main purpose, then add return-value context, a sibling-tool pointer, and a key limitation. Every sentence contributes information with no filler or repetition.

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 covers the main return elements (works with author line, matched edition ids) and the important caveats (no price, 100-hit cap). It stops short of describing the full card structure or pagination behavior, but the essential information for invoking correctly is 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 67%, and the description adds meaning by explaining what query can contain (title, author, keyword, Persian or English), reinforcing the schema's examples. The sort enum is self-explanatory, and the description does not need to restate it. There is minor room for more detail on how sort interacts with the 100-hit cap, but the core semantics are clear.

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 ('Search iranketab.ir for books'), the resource, and the search dimensions (title, author, keyword in Persian or English). It also distinguishes itself from book_details by explicitly noting that search cards carry no price.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this for broad search by title/author/keyword, and explicitly routes price/translator/stock needs to book_details. It does not enumerate when to use sibling search tools like similar_books or find_author_publisher_or_tag, so some alternative guidance is left implicit.

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, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds the specific detail that recommendations come from the 'related' shelf, which is useful behavioral context beyond annotations. No contradiction.

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 with no wasted words. It communicates the core action and the source of recommendations efficiently.

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

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

The tool is simple (2 parameters, no output schema), and annotations cover safety. The description lacks explicit information about the response format, but given the simplicity and the clarity of the purpose, it is sufficiently complete for an agent 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 coverage is 100% — both 'id' and 'limit' are described with types, ranges, and defaults. The description adds no extra parameter semantics, 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?

The description clearly states the verb 'recommends' and the resource 'books', and specifies that it is based on a given book's 'related' shelf. This distinguishes it from siblings like search_books or book_details, which have different purposes.

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: when you need books recommended alongside a specific book. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a full 5.

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