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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description focuses on what annotations can't say: the response envelope ('operation get_holdings', 'record_type holding'), the per-item fields including extra.library_id and extra.catalog_url, and the crucial semantic caveat that HOLDINGS_NONE_REGISTERED means zero holdings are registered, not that no library holds the item. That last point materially prevents misreading an empty result.

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 tight blocks: purpose first, then what each returned item contains, then filter scope and the zero-holdings caveat. Dense but front-loaded and free of filler; the parenthetical endpoint/date details are the only mildly expendable content.

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

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

With an output schema present, the description needn't document return values, and it correctly spends its budget on the empty-result semantics and filter scope instead. Remaining gaps are minor: no mention of how pagination behaves beyond the schema's count/start, and no note on rate limits or whether an NCID lookup can fail for non-NACSIS records.

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?

Reported schema description coverage is 0% at the top level (the sole 'params' wrapper is undocumented), yet the description compensates by grouping the filter families in prose — ILL participation, copy/loan service, Japan–US and Japan–Korea ILL, and journal year/volume/number — and flagging that the last three are journals-only. It does not cover pagination (count/start), which is left entirely to the nested 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?

Opens with a specific verb and resource: 'List the libraries that hold a book or journal, by its NCID', plus the upstream source (NACSIS-CAT via CiNii Research) and endpoint. This is clearly distinguishable from every sibling, all of which are search_* or get_record 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?

Usage is implied rather than stated: the NCID requirement and the reference to 'cinii_search_books' (in the schema) tell an agent this is a follow-up call after a search, and the filter paragraph sketches when to narrow. But the description never explicitly says when to call this instead of cinii_get_record or cinii_search_libraries, and offers no exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that it returns the unified envelope with operation 'get_record', which is mild context, but says nothing about error behavior for a bad CRID, unknown URLs, or result size.

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

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

Two short sentences, front-loaded with the action and resource. The second sentence about the envelope is partly redundant given a full output schema exists, keeping it from a 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 one-parameter read tool with annotations and an output schema present, the description covers the essentials: what it fetches, the input formats accepted, and the return envelope. Only failure modes and CRID format details are 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 reported as 0% for the single parameter, so the description must carry some weight; it does clarify that either a full URL or a CRID is accepted. However, it gives no format examples, no valid CRID pattern, and no guidance on the 2000-character limit.

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 ('Fetch a single CiNii record') and distinguishes itself from the search siblings by emphasizing a single record looked up by URL or CRID rather than a query. It does not name a sibling 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?

Usage is only implied: an agent infers this is the follow-up call after a search returns a record URL/CRID. There is no explicit statement of when to prefer it over re-searching, and no note about what to do if the lookup fails.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world behavior, so the description earns credit for disclosing something structured fields cannot: that records carry mixed types drawn from each record's own dc:type and that a missing dc:type is reported as 'article'. This is non-obvious, agent-relevant output 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?

Three short sentences, front-loaded with the core purpose and the return shape, then the type caveat. No filler, though the second sentence ('The cross search mixes types') partly restates the first.

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

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

An output schema exists, so return values need not be explained, and the type-mapping note is a useful completion. However, for a broad multi-filter search with a notoriously silent-ignore sort parameter, the description gives no guidance on result ordering caveats or how the filters interact with the mixed types.

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?

Reported schema description coverage is 0%, so the description carries the burden of compensating for undocumented parameters, and it adds nothing at all about sort codes, query, date ranges, data_source, or researcher_id. The nested schema does describe most of these fields in reality, but the description itself contributes no parameter 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?

States a clear verb and resource: 'Cross-type search across all CiNii content', which implicitly distinguishes it from the type-specific siblings (cinii_search_articles, cinii_search_books, etc.). It does not name any sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The word 'cross-type' and 'all CiNii content' imply the tool is for broad queries where the type is unknown or mixed, but the description never says when to prefer it over the nine typed siblings, nor whether filters behave differently here. Usage is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the safety profile is free. The description earns its keep beyond that by disclosing that multi-word queries are ANDed, that un-indexed compounds silently return zero, that SCRIPT_LATIN_QUERY means romanized-metadata-only matching, and that results differ from J-STAGE full text — all real behavioral traps not visible in 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?

Purpose is front-loaded in sentence one, and the diagnostic paragraph, though long, is dense with non-obvious failure modes rather than filler. Minor waste in "Returns the unified envelope," which is vague enough to add little without the output schema in hand.

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

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

An output schema exists, so return values need not be explained, and the description covers the tool-specific gotchas an agent would otherwise get wrong (false negatives, romanized-only matching, cross-database comparison). Only the response-language and paging parameters are left entirely to the schema, a small gap for a single-param wrapper.

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?

Although top-level coverage reads 0% (the single `params` object is undocumented), the nested schema documents most fields well, and the description adds meaning the schema does not carry: how `query` is matched (AND, romanization), and that `language` keys off catalogued languageType rather than query language. The `language` explanation partly repeats the schema's own field description, and `lang`/`count`/`start` behavior is left to the schema.

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

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

The first sentence names a specific verb and resource ("Search CiNii Research for journal articles") and immediately scopes it against a sibling by stating "Foundational monographs sit in cinii_search_books, not the article index." An agent can tell this apart from the books and other typed-search 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?

It gives explicit conditional guidance — a ZERO_CONJUNCTION diagnostic means vary the rendering rather than concluding the literature is absent, and the book alternative is named outright. It does not cover the other eight siblings (dissertations, data, all), so it stops short of a full routing rule set.

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 safety is covered. The description adds that the call returns "the unified envelope" and that identifier-only lookups are permitted, which is genuinely useful. It does not mention the sortorder codes that CiNii silently ignores, which is the main behavioral trap for this tool.

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

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

Four short sentences, front-loaded with the verb and resource, then the identifier shortcut and the follow-up routing. Tight overall; "Returns the unified envelope" is the only phrase that is a bit opaque without prior context.

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

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

An output schema exists, so the description needn't explain return values, and it correctly focuses on entry paths and the holdings hand-off. What it omits (pagination limits, sort-code pitfalls) is documented in the schema, so an agent can still 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?

Reported schema description coverage is 0%, but the description only clarifies two inputs (ncid, isbn) and says a query is optional alongside them. The other filters (sort, data_source, resource_type, from_year/to_year, has_fulltext) get no mention in the description, relying entirely on the schema.

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

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

States a specific verb and resource ("Search CiNii Research for books and monographs") and names the underlying collections (NACSIS-CAT, NDL Search). It distinguishes itself from search siblings by resource type, though it never explicitly contrasts with cinii_search_articles or cinii_search_all.

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 concrete alternate entry path ("A book can be looked up by `ncid` or `isbn` without a query") and explicit routing for the natural follow-up ("To find which libraries hold it, pass its NCID to cinii_get_holdings"). No exclusion rules are given against the other search_* tools, so it stops short of a full when/when-not statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds provenance and the fact that records are typed from their own dc:type, but 'Returns the unified envelope' is unexplained and pagination/sort caveats are left to 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?

Verb and resource are front-loaded in the first clause, and the following sentences add real scope information rather than filler. The KAKEN date note is a slightly odd detail but is genuinely informative about coverage.

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?

Output shape is covered by an output schema and safety by annotations, so the description's job is scope — which sources are indexed and how records are typed — and it does that. Nothing an agent needs in order to call this correctly is missing.

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

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

The description contributes nothing about the filters (data_source, dataset_format, has_fulltext, sort, paging), but the nested schema carries rich per-field descriptions for most of them, including the dataSourceType and datasetFormat mappings. With the schema doing the work, this sits at the baseline 3.

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 CiNii Research for research data (datasets)'), which is enough to separate it from the articles, books, dissertations and KAKEN siblings by resource type. It stops short of explicitly contrasting itself with cinii_search_all, which overlaps in coverage.

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

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

Usage is implied only: the reader can infer 'use this when you want datasets', and the source list (DataCite, JDCAT, IRDB, KAKEN) narrows expectations. There is no explicit when-not-to-use, and no statement about whether cinii_search_all also returns these records.

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/non-destructive, so the safety profile is covered. The description adds little beyond that: "Returns the unified envelope" signals a shared response shape (and an output schema exists), and "as catalogued" hints that degree filters are exact catalogue strings rather than fuzzy matches, which is genuinely useful. Rate limits, paging behavior, and empty-result behavior are unmentioned.

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 short, front-loaded lines: purpose first, then response shape, then the two filter semantics. "Returns the unified envelope" is the weakest sentence because it names a concept the reader may not know, but nothing is bloated.

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 takes a 13-field nested parameter object and an output schema exists, so return values need no explanation. However, the description omits that `query` is optional when another criterion is supplied, and says nothing about sort validity scope or the start/count paging limits — all things that affect a correct call.

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

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

The description only touches two of the many nested fields (award_institution, degree), leaving query, author, sort, count, start, from_year/to_year, language, data_source and has_fulltext unaddressed. The example values (博士（文学）, 博士（教育学）) are a real addition over the schema, but the coverage gap is too large for the description to compensate at the reported 0% 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?

States a specific verb and resource ("Search CiNii Research for doctoral dissertations") and implicitly distinguishes itself from the other cinii_search_* siblings by resource type. It never names a sibling, so the differentiation relies on the reader inferring that dissertations != articles/books/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?

Usage is only implied by the resource name; there is no statement of when to prefer this over cinii_search_all or cinii_search_articles, and no prerequisites or exclusions. Adequate for a single-resource search tool, but no active guidance is given.

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 and non-destructive, so the safety profile is covered. The description adds some value by naming the return shape ('unified envelope, record_type project'), but says nothing about pagination (start/count limits), empty-result behavior, or the sort-order validation quirks the schema hints at.

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 short sentences, front-loaded with the purpose and followed by the return type and the lookup shortcut. Nothing is padded, though 'unified envelope' is project-specific jargon an outsider may not decode.

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

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

An output schema exists, so return values needn't be described, and annotations cover safety. What remains thin is filter semantics for a 13-field input model and the lack of sibling routing; the description covers only the identifier shortcut.

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 reported schema description coverage is 0% for the top-level parameter, and the description only elaborates on one of the inner fields (project_id, with an example). The other inner options — researcher, institution, from_year/to_year, data_source, lang — get no explanation in the description, so the agent is left working from bare field names.

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?

Names a specific verb and resource ('Search KAKEN (科研費) research projects') and states the record type it returns. It does not, however, distinguish itself from the close sibling cinii_search_projects_and_products, which also returns projects — an agent must guess which to pick for a projects-only query.

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

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

One concrete usage path is given: 'A project can be looked up by project_id ... without a query'. That is genuinely useful and would be hard to infer. But there is no guidance on when to prefer this over cinii_search_projects_and_products or cinii_search_all, which is the main routing decision an agent faces.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds useful behavioral context: the live endpoint, the unified envelope with record_type 'library', and where the library ID appears.

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 tight sentences with the core action front-loaded, followed by the useful integration detail. There is 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?

Given the annotations, input schema, and existing output schema, the description supplies the missing operational context: endpoint currency, envelope shape, and the key output field used by a sibling tool. Nothing needed to call it correctly appears 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?

The input schema itself documents the name partial-match behavior, page parameter mapping, and sort semantics, so the description does not need to repeat them. The description adds cross-tool meaning for extra.library_id, but it does not add parameter usage details 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 states a specific verb and resource: finding NACSIS-CAT member libraries by name. It also explicitly relates the tool to cinii_get_holdings via extra.library_id, helping distinguish it from generic search siblings.

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

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

It clearly implies use when looking up libraries by name and explains that the returned library ID is consumed by cinii_get_holdings. It does not explicitly say when not to use it versus other cinii_search_* tools, but the context 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 already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds that results come back as a 'unified envelope' and that records are typed from their own dc:type — genuinely useful, but the envelope's shape, pagination and the fact that unrelated record types share one result list are left implicit.

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 short lines, front-loaded with the core purpose before the usage note. The trailing 'Records are typed from their own dc:type.' is a sentence fragment that reads as an afterthought, but nothing is padded.

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

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

An output schema exists, so return values need not be described. Still, for a 15-parameter cross-entity search, the description omits pagination, sort scope interactions and what 'unified envelope' yields — an agent knows roughly what it gets but not how to navigate the results.

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?

Top-level coverage is reported at 0%, so the description carries some burden, and it does highlight researcher_id as the key lever for this mode. However it says nothing about sort, count, start, language, data_source or has_fulltext, which are documented only in the nested schema; the description adds one useful hint but does not compensate for the coverage gap.

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

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

States a specific verb and a specific resource pairing ('Search KAKEN projects together with their research products ... in one result set'), which is more precise than the sibling cinii_search_kaken or cinii_search_articles alone. It does not name those siblings, leaving the agent to infer that this is the combined-search tool rather than being told so.

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

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

One usage hint is given: 'Useful with researcher_id to list a researcher's grants and outputs together.' There is no statement of when to prefer this over cinii_search_kaken, cinii_search_articles, or cinii_search_all, and no exclusions, so the routing decision is only loosely guided.

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 a read-only, idempotent, non-destructive, open-world search. The description adds useful non-obvious behavior: it returns the unified envelope with record_type 'researcher', and it warns that affiliation is absent from the record schema while the researcher name and profile URL appear in specific fields.

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

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

The description is compact and front-loaded: it states the purpose first, then gives the most important schema caveat and sort constraints. Every sentence adds information without filler.

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

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

The tool has an output schema and complete safety annotations, so the description need not explain return values in detail. It covers the key researcher-specific schema quirk and sort options, though it leaves usage alternatives and several nested input fields unaddressed.

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

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

Top-level schema description coverage is reported as 0%, so the description should compensate. It does clarify researcher-specific sort options (NAME_ASC/NAME_DESC, PROJECTS_DESC/PROJECTS_ASC, PRODUCTS_DESC/PRODUCTS_ASC, NEWEST, RELEVANCE), but it does not explain other search criteria such as query, institution, or researcher_id.

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

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

The description opens with a specific verb and resource: 'Search for researchers in CiNii.' It also states the returned record_type is 'researcher', which clearly distinguishes it from sibling searches for books, articles, projects, libraries, etc.

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

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

The description states what the tool searches but gives no explicit when-to-use guidance, prerequisites, or comparison with alternatives such as cinii_search_all or cinii_search_projects_and_products. Usage is only implied by the resource name.

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