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

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the mandatory-at-least-one-parameter constraint and the shape of the returned payload (ISBN, author, publisher, series, TOC, preview URL, price, review stats), which matters because there is no output schema.

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 purpose, then constraint, then return payload; every sentence carries information. The bilingual duplication doubles the length, which is defensible for a Japanese-market API but is still redundancy from a token-efficiency standpoint.

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 fields, and it covers the invocation precondition. Minor gap: no mention of pagination interaction between hits/page beyond what the schema states, and no note on empty-result behavior.

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 every parameter is already documented in the schema, including the enum for sort and the 1–30 / 1–100 bounds. The description restates the searchable fields and the no-free-text rule but adds no syntax or format detail beyond the schema, 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 (Search) and resource (Rakuten Books printed books) plus the exact search axes (title, author, ISBN, publisher, genre). It also explicitly distinguishes itself from books_total_search for free-text and from the other format-specific siblings (CD/DVD/magazine/foreign) by scoping to printed books.

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

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

Gives an explicit precondition ('at least one' of the listed fields) and an explicit exclusion with the alternative ('no free-text keyword, use books_total_search for that'). The genre parameter also points at books_genre_search for discovery, so routing decisions need no 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 readOnlyHint/openWorldHint/idempotentHint, so safety is covered. The description adds value beyond them by enumerating what is returned (artist, label, JAN, track list, list price, review stats), which helps the agent anticipate payload without an output schema. It does not mention pagination behavior or rate limits, so it is not complete.

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 single paragraph: purpose first, constraint second, return payload third. Every sentence carries information. The parallel Japanese translation doubles the length but is an intentional bilingual convention rather than padding, keeping it shy of 5.

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 filtered search tool this covers what an agent needs: queryable fields, the required-one constraint, the sibling to use for free text, and return contents. No output schema exists, yet return fields are described, and pagination is handled by well-documented hits/page params. Only minor gaps remain.

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. The description earns above baseline by surfacing the 'at least one of title/artist/label/JAN' constraint, which the schema does not enforce (0 required params), and by surfacing that no free-text keyword is accepted. It does not elaborate on sort enum or genre-id semantics, which remain schema-only.

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 (Search) and resource (Rakuten Books music CDs) with the searchable facets named (title, artist, label, JAN). It also differentiates from siblings: which sibling is not appropriate ('no free-text keyword, use books_total_search') and implicitly from books_book_search/books_dvd_search by scoping to CDs/music. An agent can distinguish this from the other ~27 siblings without opening a schema.

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

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

Explicitly states a usage precondition (at least one of title/artist/label/JAN) and names the alternative for free-text (books_total_search). This is clear context with an exclusion. It stops short of routing among the other near-identical media search siblings (books_book_search, books_dvd_search), so it is not a full 5.

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

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

Annotations already declare readOnly, idempotent and openWorld, so safety is covered. The description adds the non-obvious behavioral constraint that at least one search key must be supplied and that free-text is unsupported, plus what the response contains.

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 compact sentences that front-load the search scope before the exclusion, with the Japanese mirror being a convention of this catalog rather than filler. No sentence is wasted, though the bilingual duplication doubles length for monolingual readers.

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?

No output schema exists, so the description carries the return-value burden and does name the returned fields (performer, label, JAN, list price, review stats). Pagination and sort behavior are left to the schema, which is acceptable for an 8-param read-only 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 per-parameter meaning is already documented (baseline 3). The description adds value the schema cannot: the cross-parameter constraint that title/performer/label/JAN must include at least one, which is invisible given required=0.

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 (Search) and resource (Rakuten Books DVDs/Blu-ray), enumerates the usable keys (title, performer, label, JAN) and the return payload. It is clearly distinguishable from sibling media searches like books_cd_search or books_book_search.

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?

Explicitly states the when-not: no free-text keyword here, route that case to books_total_search, and it names books_genre_search as the way to discover genre IDs. The 'at least one of these fields' precondition is stated outright rather than 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 readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds two useful pieces of context not present in structured fields: the mandatory at-least-one-field rule (which is stricter than the schema's required: 0) and the return content, including a Japanese-translated title field when one exists. It stops short of describing pagination limits, though the schema covers those.

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 English text is two tight sentences with the scope and the sibling exclusion front-loaded. The bilingual duplication doubles the length, but it mirrors the schema's own bilingual field descriptions and does not bury the operative constraint.

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 eight-parameter read-only search with no output schema, the definition covers purpose, the required-input rule, the alternative tool, and the notable return field (japaneseTitle). Pagination and sort semantics live in the schema, so nothing essential is missing, though the description never states what a result set looks like structurally.

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 eight parameters are already documented with their bounds, defaults, and the enum for sort. The description only restates which fields can be searched (title/author/ISBN/publisher) and omits any detail on hits, page, sort, or booksGenreId. Baseline 3 is correct when the schema carries the parameter 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?

States a specific verb (Search) and a precisely scoped resource: foreign-language (non-Japanese) books in Rakuten Books, searchable by title, author, ISBN, or publisher. The non-Japanese scope cleanly separates it from books_book_search, and the explicit hand-off to books_total_search separates it from that sibling.

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?

Explicitly states the usage constraint ('at least one' of the four search fields) and names the exclusion plus the alternative for the excluded case: 'no free-text keyword, use books_total_search for that'. An agent can route between this tool and its sibling without any 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, open-world, idempotent behavior, so the safety profile is covered. The description adds value beyond that by disclosing the return payload (hardware, label, JAN, list price, review stats) in the absence of an output schema, plus the 'at least one filter' constraint that the schema does not enforce (required: 0). It stops short of mentioning pagination limits or rate limits.

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

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

Front-loaded with the action, then the accepted inputs, then the exclusion and return fields in two tight sentences. The Japanese mirror doubles the length but is a deliberate, useful choice for a Japanese-market catalog tool rather than 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 7-parameter search tool with no output schema, the description covers the return shape, the minimum-filter rule, and the discovery path for booksGenreId. Only minor gaps remain: pagination interaction between hits/page and the meaning of the sort enum are left entirely to the schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description echoes the title/hardware/JAN parameters and supplies platform examples, but those examples ('Nintendo Switch', 'PlayStation 5') already appear in the schema, and it adds nothing about hits, page, or sort 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?

Specific verb+resource ('Search Rakuten Books for video games') with the three accepted search axes named explicitly, and it explicitly names books_total_search as the sibling for the excluded free-text mode. An agent can distinguish this from books_book_search, books_software_search, and books_total_search without opening any schema.

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

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

States the selection condition ('at least one' of title/hardware/JAN) and an explicit exclusion with a named alternative ('no free-text keyword, use books_total_search for that'). It also routes genre-ID discovery to books_genre_search, giving concrete when-to-use guidance for two sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds behavioral details about the returned structure (parents and children for specific IDs, top-level for '000'), which is helpful beyond 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 three sentences, front-loaded with the action and examples, and includes a Japanese version for localization. No unnecessary words. Highly efficient.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description fully explains its functionality and usage. It covers all needed information 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 coverage is 100%, with the parameter already described in the schema (including examples and hierarchical levels). The description provides additional context about '000' and specific IDs, but this is marginal. 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 states the tool browses the Rakuten Books genre hierarchy. It specifies that passing '000' lists top-level genres and a specific ID fetches parents and children. This distinctly separates it from sibling tools like books_book_search or ichiba_genre_search.

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 when to use the tool (to browse genres or navigate hierarchy) and explicitly mentions it is useful for narrowing book searches. While it doesn't list alternative tools or when not to use it, the context from sibling names and the purpose makes the usage clear.

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, so the safety profile is covered. The description adds the non-obvious constraint that at least one of title/publisher/JAN is required (the schema encodes required: 0), which is real behavioral value, and it lists what the response contains. It omits rate limits and any note on what an empty result set means.

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 English sentence is front-loaded with purpose and the exclusion, then the return payload, and the Japanese mirror is an intentional bilingual duplicate rather than padding. The return-detail enumeration (publisher, JAN, publication cycle, preview URL, review stats) is slightly long but earns its place 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 7 optional parameters, no output schema, and full schema coverage, the description supplies the two things structured data lacks: the at-least-one-field requirement and the shape of the returned issue details. It does not explain pagination limits or how genre IDs interact with title filters, leaving minor gaps for a search tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains hits, page, sort and the genre-ID format. The description goes beyond that by imposing the 'at least one of title/publisher/JAN' rule that the schema does not express, which is genuine added meaning for a zero-required-parameter tool.

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 Rakuten Books for magazines) plus the three accepted filter fields, and explicitly distinguishes itself from books_total_search by excluding free-text keyword search. An agent can separate this from the many sibling book/media searches (books_book_search, books_cd_search, kobo_ebook_search) without opening a schema.

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

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

Gives a clear routing rule: no free-text keyword here, use books_total_search for that, and it names books_genre_search (in the schema) as the way to discover genre IDs. It does not spell out when magazine search is the wrong choice versus, say, kobo_ebook_search or books_book_search, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety is covered. The description adds genuinely non-schema context: the 'at least one of title/OS/JAN' constraint (schema lists 0 required params) and the shape of returned fields (target OS, label, JAN, list price, review stats). 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?

Front-loads the purpose, then the constraint and alternative, then the return fields; the JA mirror adds value for the target locale rather than padding. No wasted sentences, though the doubled bilingual text is somewhat long.

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 7-param, no-output-schema read tool, the description covers the core use case, the input constraint, the alternative tool, and the returned fields. Minor gaps remain around pagination and the sort/genre params, but nothing essential to correct invocation 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 each parameter is already documented. The description only reinforces title/OS/JAN and says nothing about hits, page, sort, or booksGenreId, adding no syntax or meaning beyond the schema. 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 (Search) and a precise resource (Rakuten Books computer software), and explicitly distinguishes itself from books_total_search for free-text queries. An agent can tell this apart from books_book_search, books_game_search, etc. without opening any schema.

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

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

Gives clear when-to-use (search by title, OS, or JAN, at least one required) and names an explicit alternative (books_total_search) for free-text. It does not cover the relationship to books_genre_search for the booksGenreId param or to the other media-type searches, so routing is clear but not exhaustive.

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 provide readOnlyHint, idempotentHint, openWorldHint. Description adds cross-category context but does not contradict annotations. No further behavioral details are needed.

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?

Description is concise, front-loads the main purpose, and includes a Japanese translation. Every sentence provides value without 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?

Despite no output schema, the description covers usage scenarios and parameter purpose. Could mention typical return fields, but overall adequate for agent use.

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 baseline is 3. Description does not add significant meaning beyond the schema's parameter descriptions.

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 it performs a cross-category search across Rakuten Books, listing all included categories. It distinguishes itself from sibling category-specific tools by specifying when to use each.

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?

Explicitly says 'Use this when you don't know which category contains the target item' and directs to category-specific tools for those use cases. This provides clear guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds useful detail on returned fields, but 'full details' slightly conflicts with openWorldHint. Minor issue, 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?

Two concise English sentences plus Japanese translation. Front-loaded with purpose, no fluff.

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 single-parameter tool with no output schema, the description adequately lists all expected return fields and usage context. Sufficient for agent 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 already covers the parameter fully (100% coverage). Description restates that ID comes from search but adds no extra meaning beyond 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?

Description clearly states the tool retrieves full details for a golf course by ID, listing specific fields (address, phone, designer, etc.). It distinguishes from sibling tools by explicitly mentioning use after gora_golf_course_search.

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?

Explicitly says 'Use this after gora_golf_course_search to drill into a specific course.' Provides clear usage context and sequence, though no direct 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 readOnlyHint=true and idempotentHint=true, so the description's behavioral burden is lower. The description adds context: it returns specific fields and includes a reservation calendar URL. No contradictions. It provides extra context beyond annotations, such as the return format (name, address, etc.).

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 succinct, with one paragraph in English and one in Japanese. It front-loads the key verbs and resources, and every sentence adds value. No wasted words.

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 7 optional parameters, 100% schema coverage, and no output schema, the description covers the tool's purpose, input options, output fields, and points to the sibling tool for more detail. This is complete for a search 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 coverage is 100%, so the input schema already documents all 7 parameters with descriptions. The tool description only mentions the search criteria types (area code, keyword, coordinates) but adds no new parameter details 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?

The description clearly states the tool's purpose: 'Search Rakuten GORA golf courses' by area code, keyword, or coordinates. It lists returned fields (name, address, etc.) and differentiates from sibling tool gora_golf_course_detail, which provides full details. This is a specific verb+resource with sibling differentiation.

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 to use gora_golf_course_detail for full information, providing a clear alternative. It implies this tool is for summary search results. Although it doesn't state exact when-not-to-use scenarios, the guidance is sufficient for an AI agent to choose between tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by detailing the return structure (plan name, price, inclusions, start time, points) and filtering capabilities, which goes beyond the safe-read designation.

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 English portion is 5 tight sentences that front-load the main action and immediately list return fields. The Japanese duplicate is reasonable for bilingual audiences. No wasted words.

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 fully explains the return structure (plans with price, inclusions, start time, points) and all major filtering axes. Pagination parameters (hits, page) are covered in the schema, which suffices. The context of comparing plans before reserving is well set.

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 descriptive parameter titles and descriptions. The description mentions filtering by areaCode, golfCourseId, playerNum, and budget, but does not add new meaning beyond what the schema already provides, so 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 starts with a specific verb ('Search') and resource ('Rakuten GORA reservation plans'), clearly distinguishing it from sibling tools like gora_golf_course_search (searches courses) and gora_golf_course_detail (gets course details).

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 advises using this tool to 'compare options across courses before reserving', providing clear use context. However, it does not explicitly mention when to avoid using it or name alternative tools for other tasks.

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

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

The description adds behavioral details beyond the annotations: fetching ancestors, siblings, and direct children for a given genre ID. The annotations already indicate read-only, idempotent, and open-world, and the description does not contradict them.

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

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

The description is two concise English sentences (plus Japanese translation) with no wasted words. It front-loads the purpose and then explains behavior.

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

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

The description is complete for a simple read-only browse tool: it explains what the tool does, when to use it, and the parameter behavior. It does not describe the output format, but given the tool's simplicity and lack of output schema, 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?

The single parameter genre_id has 100% schema coverage; the description adds the special behavior for value '0' (top-level) and drilling down, which is not explicitly in the schema description but is implied. This adds value 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?

The description clearly states the tool browses the genre hierarchy, specifies the verb (Browse), resource (genre hierarchy), and the effect of passing '0' vs a specific genre ID. It is distinct from sibling tools that search or rank items.

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 it is useful for narrowing item searches or discovering categories, providing clear context. It does not give explicit when-not-to-use or alternatives, but the sibling tools are sufficiently different.

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/openWorld, so the safety profile is covered. The description adds real value beyond that: the Rakuten-imposed mutual exclusion between genre and age/sex filters, and the shape of the payload (rank, price, review stats, purchase URL) in the absence of an output schema.

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 purpose, then constraints, then routing hint, then return contents — a sensible order with no filler. The only cost is the complete Japanese duplication of the same content, which doubles length without adding information for a single-language consumer.

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 4-parameter, all-optional read tool with no output schema, the description covers the ranking modes, the key cross-parameter constraint, and the returned fields. What is missing is only marginal — e.g. how the 1–34 page cap interacts with the ~1000-item ceiling, which the schema already states.

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

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

Schema description coverage is 100% and each parameter (age, sex, page, genre_id) is already documented in-schema with enums, defaults, and range limits. The description restates the genre/age/sex exclusivity that the schema already carries, adding no syntax or format detail beyond it. 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 Rakuten Ichiba realtime bestseller ranking') and immediately enumerates the three supported scoping modes (overall, genre, demographic). It also names the sibling ichiba_genre_search as the way to obtain genre IDs, so an agent can distinguish it from the other ichiba_* tools without opening schemas.

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

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

Gives clear operating context: the three ranking modes, the mutually exclusive genre vs. demographic rule, and a routing hint to ichiba_genre_search for genre IDs. It does not, however, say when to prefer this ranking tool over ichiba_item_search or ichiba_product_search, so the alternative-selection guidance is incomplete.

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 confirm read-only and idempotent behavior. The description adds value by specifying the output: 'Returns a paginated list of items with prices, review stats, images, and direct purchase URLs.' This goes beyond annotations, though it doesn't disclose rate limits or authentication needs.

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?

Extremely concise: two short paragraphs (English and Japanese) with front-loaded purpose. Every sentence adds value, and no superfluous information is present.

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 8 parameters and no output schema, the description covers core functionality, filtering, sorting, and response contents. It mentions pagination and key fields, but lacks details on error behavior or advanced usage. Adequate for most use cases.

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. The description does not add parameter-level details beyond what the schema already provides; it summarizes the supported features (price range, sorting, genre/shop restriction) but does not enhance understanding of individual parameters.

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 tool's purpose explicitly: 'Search products on Rakuten Ichiba by keyword.' It clearly specifies the verb 'search' and the resource 'Rakuten Ichiba products.' It distinguishes itself from sibling tools like ichiba_item_ranking (rankings) and ichiba_genre_search (genre browsing) by focusing on general keyword search with filtering and sorting.

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?

Implies usage context for general product search with keyword, but does not explicitly state when to use this tool vs alternatives like ichiba_product_search or when not to use it. No exclusions or prerequisites are mentioned, though the context is clear from the description.

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 provide readOnlyHint, openWorldHint, and idempotentHint, indicating safe, read-only behavior. The description adds that the tool groups products across shops and returns min/max/average prices and shop count, which is useful context beyond 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 languages, each sentence is meaningful and front-loaded. It efficiently covers purpose, usage, and an example filter with no wasted words.

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

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

The description explains the core function, when to use, and filter options. It does not detail pagination or sort behavior, but these are covered in the schema. No output schema exists, but the description outlines what is returned (min/max/average price, shop count).

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 baseline is 3. The description does not add significant new meaning to parameters beyond what the schema already provides, though it reinforces keyword vs product_id dependency and the purpose of maker_code.

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 searches Rakuten's Item Price Navi, a cross-seller product catalogue grouping identical products. It includes the verb 'search' and distinguishes itself from the sibling 'ichiba_item_search' by specifying it is for price comparison.

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?

Explicitly says to use this tool instead of ichiba_item_search when comparing prices or determining if a price is fair. It also mentions filtering by maker_code. Lacks explicit when-not-to-use statements, but the guidance is clear.

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 declare readOnlyHint, idempotentHint, and openWorldHint. The description adds context about return fields and the requirement to pass at least one parameter, without contradicting 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 English sentences plus a Japanese translation. The first sentence states purpose and returns, the second clarifies the requirement. No unnecessary words.

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

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

Despite no output schema, the description lists returned fields and input constraints. It covers essentials for a search tool, but could mention pagination or error handling.

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 bilingual descriptions. The description reinforces the 'at least one field' rule but adds no further 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 clearly states the tool searches Rakuten Kobo's eBook catalogue by multiple criteria and returns specific details. It is distinct from siblings like books_book_search and kobo_genre_search.

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 indicates that at least one search field is required but does not explicitly contrast with alternative tools or specify when to choose this over siblings like books_book_search.

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, so the tool is known to be safe and idempotent. The description adds context about the return structure (current genre, ancestors, children) but does not disclose additional behavioral traits beyond that. No contradiction with annotations.

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

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

The description is concise with two sentences in both English and Japanese. It is front-loaded, every sentence adds value, and there is no unnecessary 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?

Given the tool's simplicity (one parameter, optional, no output schema), the description fully covers purpose, usage, and output structure. It mentions the hierarchical nature and linkage to kobo_ebook_search, providing sufficient context 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?

The schema description coverage is 100%, and the description largely repeats the schema's explanation of the koboGenreId parameter. It adds marginal value ('Pass a child genre ID...'), so the baseline of 3 is appropriate.

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

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

The description clearly states it browses the Rakuten Kobo eBook genre hierarchy, specifies the top-level ID '101', and indicates it returns current genre, ancestors, and children. It also distinguishes from sibling genre search tools by emphasizing the Kobo domain.

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 how to drill down by passing child IDs and links to kobo_ebook_search. However, it does not explicitly exclude use cases or contrast with sibling genre tools like books_genre_search or ichiba_genre_search.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds valuable detail: hierarchy structure, parentCategoryId for tree assembly, payload sizes (~430KB for full tree), and Japanese translation for non-English users.

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 compact paragraphs (English then Japanese) front-load essential information. Every sentence adds value—no redundancy or fluff.

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

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

Despite lacking an output schema, description fully explains return structure (categoryId, name, URL, parentCategoryId for lower levels) and how to assemble the hierarchy. Sufficient for an agent to understand and use the 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 coverage is 100% with enum descriptions. Description enhances by explaining practical implications (payload size for 'all', top-level only for 'large') and the presence of parentCategoryId for medium/small levels.

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?

Clearly states it retrieves the Rakuten Recipe category hierarchy with three levels (large, medium, small) and their counts. Distinct from sibling search tools which focus on items or rankings.

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?

Explains when to use 'large' for smaller payload (top-level menu) vs 'all' (full tree). Could be more explicit about when to use medium or small depths, but provides sufficient guidance for typical use cases.

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

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

Annotations already indicate read-only, idempotent, and open-world hints. The description adds value by listing the specific return fields (title, ingredient list, cooking time, etc.) and noting it returns a direct URL. 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 concise with two sentences (plus Japanese translation), front-loading the core action. Every sentence serves a purpose with no wasted words.

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

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

Despite no output schema, the description fully explains the tool's behavior and return fields. It covers prerequisite knowledge and is complete for a simple single-parameter ranking 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?

The input schema has 100% coverage, describing 'categoryId' and referencing 'recipe_category_list'. The tool description reiterates this but adds no new semantic information beyond what the schema already 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 uses a specific verb 'Get' and clearly identifies the resource as 'top recipes in a Rakuten Recipe category'. It distinguishes itself from sibling tools by domain and explicitly references 'recipe_category_list' for category IDs, making its purpose unambiguous.

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

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

The description provides clear guidance on a prerequisite: using 'recipe_category_list' to find category IDs. While it doesn't explicitly state when not to use the tool or list alternatives, the simple nature of the tool and the single sibling in the same domain make this adequate.

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 mark it as readOnly, idempotent, and openWorld. The description adds the hierarchy structure, which is consistent and provides additional context without 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?

Two sentences in English (with Japanese translation) that front-load the purpose and include a usage note. No unnecessary words.

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 zero parameters and rich annotations, the description covers the essential behavior. However, the lack of an output schema means the agent may not know the exact response format, but the description hints at the code field names.

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?

No parameters exist, so the description cannot add meaning to them. However, it explains the output codes' structure, which compensates for the absence of an output schema. Baseline for 0 params is 4.

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 'Get the full Rakuten Travel area-code hierarchy' and explains the hierarchy levels (Japan→prefecture→city→district). It distinguishes itself from sibling hotel search tools by being the source of location codes.

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?

Explicitly instructs to use the returned codes as parameters in hotel search tools. While it doesn't mention when not to use it, the context makes it clear as a preliminary step.

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, openWorldHint. The description adds that it returns a list of chains with codes, consistent with the annotations. No extra behavioral details beyond what annotations provide.

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 clear sentences in English plus a Japanese translation. No superfluous words; front-loaded with the primary purpose.

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 zero complexity (no parameters, no output schema), the description fully covers what the tool does and what it returns. The annotation set is rich enough that additional context is unnecessary.

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?

No parameters exist, so schema coverage is 100%. The description effectively explains the output (list of hotel chains with codes), compensating for the lack of output schema, thus adding value beyond the input 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?

The description explicitly states the tool lists all Rakuten Travel hotel chains with their codes, naming examples like Marriott, Hilton. It clearly distinguishes itself from sibling travel search tools by focusing on chain listing.

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?

Suggests use for filtering or grouping search results by chain, implying it's a preliminary step before other travel searches. While not specifying when not to use it, the context of sibling tools makes its purpose clear.

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. The description adds value by specifying that the output includes per-axis ratings and detail fields not present in search results, giving the agent a clearer expectation of the response beyond the schema.

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 very concise: two sentences in English and a Japanese translation. Every word serves a purpose, clearly stating the action, input, and output distinction from search endpoints.

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 single-parameter tool with thorough annotations and no output schema, the description covers the essential purpose and behavioral differences. It could mention error cases or data availability, but the openWorldHint implies variability, so it is 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 coverage is 100% for the single parameter (hotelNo), so the description does not need to add further semantics. The description itself does not elaborate on the parameter beyond what the schema provides, meeting the baseline expectation.

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 it fetches detailed information for a specific hotel using hotelNo, and explicitly distinguishes itself from search endpoints by noting that it returns the same Hotel shape with additional per-axis ratings and detail fields. This specificity helps an agent differentiate it from sibling search 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 implicitly tells when to use (when a hotelNo is available from search results) but does not provide explicit when-not or alternative tool references. However, given the sibling tools are all search-oriented, the use case is fairly clear.

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, so the description adds value by listing the returned fields (rank, name, area, review stats, URLs). No contradictions.

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 waste, front-loaded with the core purpose and extended with genre options. Japanese translation concisely mirrors the English.

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 adequately summarizes the return fields. Though it lacks details like pagination or result count, for a ranking tool this is sufficient given the open-world hint.

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 single parameter 'genre' has a comprehensive schema with enum and default. Schema coverage is 100%, so the description adds little beyond restating the enum values. Bilingual text is helpful but doesn't add new meaning.

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 it retrieves 'top-ranked hotels on Rakuten Travel' with options for overall or genre-specific rankings. It distinguishes itself from sibling tools like search tools by focusing on rankings.

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 specifies that it can be used overall or by genre, providing clear context for when to use. It doesn't explicitly exclude alternatives, but given the distinct ranking focus among sibling search tools, usage is well implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds minimal behavioral context, such as noting it returns the same Hotel shape as another tool. It does not 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 clear sentences in English and a Japanese translation. It is front-loaded with the key action and purpose, every sentence 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?

The tool has three parameters and no output schema. The description covers purpose, usage context, and return shape (same as another tool). It is complete for a search tool, though it could mention pagination behavior.

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 descriptions for all three parameters. The description does not add additional meaning beyond what the schema provides; it merely restates the keyword parameter's purpose.

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

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

The description clearly specifies the action (search), resource (Rakuten Travel hotels), and the method (free-text keyword). It also distinguishes from sibling travel_simple_hotel_search by noting it returns the same Hotel shape and is useful when the area code is unknown.

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 indicates when to use this tool ('when you don't know the area code'), providing clear context. However, it does not mention when not to use it or offer alternative tool names besides the implicit comparison.

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 safe read-only, idempotent, open-world behavior. The description adds meaningful return context—hotel summaries with prices, addresses, review stats, and ratings—which matters because there is no output schema; it still omits auth, rate, and full pagination behavior.

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

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

The English portion is front-loaded and efficient: purpose, return contents, then prerequisite. The Japanese translation duplicates the same content, which adds length but may be intentional localization; otherwise 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?

Given the rich parameter schema and safety annotations, the description covers the key missing pieces: purpose, return contents, and the area-code discovery prerequisite. It is sufficient for calling the tool correctly, though explicit alternative-routing guidance and pagination/output details are absent.

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 nine parameters are already documented in the schema. The description reinforces the area-code hierarchy and points to travel_get_area_class, but adds no syntax or format details 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?

States a specific verb and resource: search Rakuten Travel hotels by area-code hierarchy or latitude/longitude. It is clear what the tool does, but it does not explicitly distinguish itself from sibling search tools such as travel_keyword_hotel_search or travel_vacant_hotel_search.

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 one useful prerequisite: use travel_get_area_class to discover area codes. However, it does not explain when to choose this tool over keyword, vacancy, ranking, or detail-search siblings, nor does it state 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description still adds real behavioral context: it enumerates the returned room-plan fields, and critically warns that 'Prices are for a single night, not the whole stay' and that chargeBasis can be per_person or per_room — non-obvious semantics that would otherwise cause misreporting. No output schema exists, so this disclosure carries weight.

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 verb and constraint, then return contents, then the per-night price caveat. The bilingual duplication is expected for this tool family and each sentence carries content. Slightly padded by restating the parameter-sharing note.

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 steps in to describe the return shape (hotel + room plans with plan name, price, chargeBasis, breakfast flag, reserve URL) and the price-basis caveat. Combined with a fully documented 13-parameter schema, an agent has enough to call and interpret it, though routing guidance versus sibling search tools remains thin.

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 every parameter including checkinDate/checkoutDate formats, hits, page, roomNum, adultNum, and the class codes is already documented. The description adds only that area/coordinate parameters match travel_simple_hotel_search, which is minor. 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 ('Search Rakuten Travel for hotels') plus the defining constraint ('with rooms available on specific check-in/check-out dates'), which is what separates it from travel_simple_hotel_search and travel_keyword_hotel_search. The reference to sharing parameters with travel_simple_hotel_search signals the family relationship but never explicitly says how the two differ.

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

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

The description implies usage via the required check-in/check-out dates and the note that area/coordinate parameters mirror travel_simple_hotel_search, but it never states when to pick this over travel_simple_hotel_search, travel_keyword_hotel_search, or travel_hotel_detail_search. Guidance is inferable rather than explicit.

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