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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real value: returns raw Elsevier JSON, entitlement-gated access, and that no linked records or additional pages are fetched automatically—non-obvious operational constraints.

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 dense sentences, front-loaded with the core action and identifier, followed by return format and constraints. Every sentence carries information; only minor tightening is possible.

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 details need not be restated, yet the description still characterizes the response. Combined with the entitlement caveat and the no-auto-pagination note, this is nearly complete for a retrieval tool with a rich conditional 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 the schema itself documents all 8 parameters, making 3 the baseline. The description reinforces that 'view' controls one page of related documents/authors and that no additional pages are fetched, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Retrieve a Scopus institution profile') and pins the identifiers ('by affiliation_id or eid'), which cleanly separates it from the sibling affiliation_search. An agent can select this over affiliation_search/author_retrieval without opening the schema.

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

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

It implies usage via the identifier and view parameters, and notes that DOCUMENTS/AUTHORS views pull related records, but it never explicitly says when to choose this tool over affiliation_search or which view to pick for which intent. Guidance is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds beyond that: it returns one page of native Elsevier JSON including pagination, and access is gated by Scopus entitlements — real behavioral context an agent needs before calling.

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 purpose and response shape, then the query example, then the entitlement caveat. Every sentence carries information; only the example slightly duplicates the schema's query pattern.

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, return values need not be detailed, and the description correctly says only that one page of with pagination is returned. The pagination cap (start + count <= 5000) lives in the schema, and the entitlement precondition is stated, leaving little an agent needs beyond what's provided.

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% across all 10 parameters, so the schema fully documents sort, count, start, facets, view, etc. The description only restates the query example (AFFIL(...) AND AFFIL(...)), which the schema already carries, so it earns the baseline 3 without adding parameter-level 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 specific verb (Search) plus a specific resource (Scopus institution profiles) and the query dialect (native affiliation query syntax). An agent can distinguish it from siblings like author_search or affiliation_retrieval without opening either 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?

The description supplies an entitlement caveat ('Access depends on your Scopus entitlements') and notes credentials come from the environment, which is useful context, but never states when to prefer this over affiliation_retrieval or scopus_search. Usage is implied by the tool name rather than 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 the safe read-only, idempotent, open-world profile, so the bar is lower, and the description still adds real behavioral context: comma-separated author_id/eid collapse into one native batch request, the response is raw Elsevier JSON, and availability is gated by entitlements. The closing clause about pagination and superseded-profile resolution is useful but terse ('are explicit' does not say what actually happens).

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 identifiers and batch behavior before the caveats. Slight deduction because 'Pagination and superseded-profile resolution are explicit' is a vague signpost rather than an informative statement.

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, return values need not be explained, and the annotations carry the safety profile. The description still covers the essentials an agent needs for a 10-parameter retrieval call: accepted identifier forms, batching, entitlement gating, and the existence of explicit pagination/alias controls.

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 (view, alias, startref, refcount, field, ver, reqId) is already documented in the schema; the baseline of 3 applies. The description adds only the batch semantics of comma-separated IDs and the entitlement caveat, not new per-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 specific verb and resource ('Retrieve Scopus author profiles') plus the three lookup keys (author_id, eid, orcid), which implicitly separates it from the sibling author_search. However, it never names author_search or otherwise explicitly contrasts the two, so the differentiation is left to inference rather than stated.

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

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

Usage is only implied: the presence of specific identifiers suggests when this tool applies, and 'view access depends on entitlements' hints at a prerequisite. There is no explicit when-to-use/when-not guidance and no pointer to author_search when only a name is known, which is the key routing decision an agent faces with these siblings.

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 genuinely useful context beyond that: one page of native Elsevier JSON with search-results and pagination, plus entitlement-gated access from server-side credentials.

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 purpose and routing rule in the first sentence, then return shape and auth in two compact sentences. The inline query example is redundant with the schema parameter description, a minor wasted sentence.

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

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

With an output schema and rich annotations present, the description only needs to add routing rules and environment facts, which it does (precedence, credentials, entitlements, pagination). Nothing critical for correct invocation is missing, though the boundary with author_retrieval stays implicit.

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

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

Schema description coverage is 100% and the description largely mirrors it (the AUTHLASTNAME/AUTHFIRST example appears verbatim in the query parameter). Precedence of co-author over query is restated from the schema rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Search Scopus author profiles') plus the two input modes (native query or co-author). The search framing clearly separates it from the retrieval-oriented siblings, but no sibling is named explicitly, so an agent must infer the boundary with author_retrieval.

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 conditional guidance: use a native query, or supply co-author to find collaborators, and states that credentials come from the server environment and access depends on Scopus entitlements. It does not name alternative tools (e.g. author_retrieval) or say when NOT to use this 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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a read that returns the original Elsevier JSON in a single request, and it requires an access entitlement on the API key.

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

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

Three sentences, each earning its place: purpose, input convention, and prerequisite/return note. The core purpose is front-loaded and there is no filler.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. The description adds the entitlement prerequisite and identifier rule, leaving only minor gaps (pagination/sorting behavior) that the schema itself fully documents.

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 14 parameters (including sort, citation, date, count, start) are already documented in the schema. The description only restates the one-identifier-type constraint and comma-separated convention that the schema already carries, adding no new 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?

Specific verb (retrieve) plus specific resource (yearly citation counts and summaries for Scopus documents). It is clearly distinguishable from the metric-adjacent sibling plumx_metrics and the search/retrieval siblings, which operate on authors, affiliations, and search results rather than citation counts.

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 input convention (one native identifier type, comma-separated for multiples) and a real prerequisite (Citation Overview access must be enabled for the API key). However, it never says when to prefer this over plumx_metrics or any sibling, and offers no exclusions or failure-mode 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 readOnly/idempotent/openWorld, so the description is not required to restate safety. It adds genuinely useful behavior beyond them: the Scopus entitlement requirement and the ambiguous HTTP 404 semantics (no metrics vs unknown identifier), which the agent cannot infer from structured 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?

Front-loaded with the action and resource, then entitlement and error semantics, in four tight sentences with no filler. The sentence enumerating returned JSON fields is mildly redundant given an output schema exists, but the rest all earn their 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?

With an output schema present, return values need no prose; parameters are fully documented in the schema; and the description supplies the two things the schema cannot — the Scopus entitlement requirement and the meaning of a 404. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and every parameter (reqId, idType, idValue) is documented in the schema, including the namespace enum values and the no-URL-encoding rule. The description adds only the vague phrase 'by identifier', 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?

Names a specific verb (retrieve) and a distinctive resource (native PlumX metrics) scoped to a single publication or artifact located by identifier. The unique resource name separates it implicitly from siblings like citation_overview, but no sibling is named explicitly, so it stops short of full 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 states the lookup pattern (by identifier) and a hard prerequisite (active Scopus access), which implies when the tool is usable. However it never states when to prefer this over citation_overview or other metric-bearing siblings, and gives 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds meaningfully beyond them: credentials come from the server environment (no auth handling by the caller), responses are one page of raw Elsevier JSON with pagination, and view/cursor availability is gated by entitlements. This is useful operational context, though it does not quantify entitlement tiers 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?

Five sentences, each carrying distinct information (purpose, return shape, example, credentials, entitlements), front-loaded with the purpose. Slightly dense, but no sentence is purely filler; the return-shape sentence is only partly redundant with the 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?

For a 15-parameter tool with an output schema and rich annotations, the description covers purpose, return model, auth source, and entitlement gating. The offset-pagination 5000 limit and view/count ceilings live in the schema, so little is missing, though the relationship to sibling search/retrieval tools could be spelled out.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-cutting semantics not obvious from individual params: the response is a single page, includes pagination metadata, and cursor/view behavior is entitlement-dependent. It does not enumerate the parameters themselves, which is fine given 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 clear verb and resource ('Search Scopus publications') with the query syntax being native Scopus. The publication focus implicitly separates it from sibling tools like author_search, affiliation_search and citation_overview, but no sibling is named explicitly, so differentiation is left to inference.

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

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

The example query and the note that view/cursor access depends on Scopus entitlements imply when this tool applies, but there is no explicit when-to-use guidance or routing against siblings such as author_search or citation_overview. Usage is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so safety is covered. The description adds genuinely useful context beyond that: it returns raw Elsevier JSON and that the endpoint is public and needs no API key, which affects how the agent should call it.

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 purpose, then return format, usage, and auth note; no filler. The return-content sentence slightly overlaps the output schema, but it still conveys the raw JSON format, so only minor 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?

With an output schema present and rich annotations, the description only needs to establish purpose, filtering behavior, and auth expectations, all of which it does. Nothing an agent needs for correct invocation is missing for this simple, zero-required-parameter lookup.

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 of the five optional filter parameters is already documented with examples and matching semantics. The description adds no parameter-level detail (syntax, matching rules) beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Retrieve or filter Scopus subject classifications') and the resource is unique among the siblings, which are search/retrieval tools for other entity types. An agent can immediately tell this is the taxonomy lookup endpoint.

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 'Omit filters to list all classifications,' which tells the agent how to get the full list versus a filtered subset. There are no overlapping siblings to route against and no exclusion cases are needed, so context is clear even without naming alternatives.

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