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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds genuine value on top by disclosing deduplication behavior ('Papers already in the library are not duplicated'), which is the practical consequence of idempotency, though it says nothing about permissions or partial-failure 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 action and scope, then the required inputs, then the dedupe caveat. No filler; 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?

For a 2-parameter, non-destructive mutation with full schema coverage and no output schema, the description covers purpose, inputs, and the dedupe side effect. It stops short of noting auth requirements or what happens with invalid library IDs, which are minor omissions rather than blocking gaps.

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 schema already documents both parameters, including that library_id comes from list_libraries. The description merely restates those parameters ('Provide library ID and list of bibcodes') without adding format, limits, or semantics 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 ('Add') and resource ('papers to an existing library in the user's ADS account'), and the word 'existing' implicitly separates it from the sibling create_library. An agent can identify the operation 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?

The description tells the agent what to provide (library ID and bibcodes) and that the library must already exist, which implies you need list_libraries first. However, it never explicitly states when to use this versus alternatives such as create_library or get_library_papers, so 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 readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the mutation/non-idempotent safety profile is covered. The description adds only account scoping ('in the user's ADS account') and nothing about permission needs, duplicate-name handling, or side effects, which is acceptable but thin given annotations carry most of the burden.

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 with no filler, and the core action is front-loaded before the use-case elaboration. Efficient, though the second sentence is more marketing than specification.

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 could usefully state what a successful creation returns (e.g., a library identifier needed to chain into add_to_library), and it omits any visibility/permission caveats around the 'public' flag. It is adequate for a simple 3-param create but leaves a real chaining gap.

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

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

Schema description coverage is 100%, so all three parameters (name, public, description) are already documented with defaults and examples. The description adds no parameter-level meaning beyond the schema, which is the baseline-3 case.

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+resource ('Create a new paper library/collection') and scopes it to 'the user's ADS account', which is clearer than the bare title. It implicitly separates from siblings like add_to_library and list_libraries, but never names or contrasts them explicitly, so it stops short of a 5.

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

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

The second sentence ('Useful for organizing papers by topic, project, or reading status') gives an implied usage context, but offers no when-to-use vs alternatives guidance and no prerequisites. It does not clarify the relationship to add_to_library (adding existing papers) versus creating a new container, which is the main ambiguity an agent would face.

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 genuine value beyond them by disclosing the output fidelity (ADS-style journal macros, volume, pages, DOI, eprint) — meaningful since there is no output schema. It stops short of covering size limits or error behavior for invalid bibcodes.

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

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

Two tight sentences with zero filler; the core action and its format guarantee lead, and the use case follows. Nothing is repeated from the schema or annotations.

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-only export with no output schema, the description supplies both the format of the returned citations and a use case, which is nearly everything an agent needs. Only error/limit behavior for large or invalid bibcode lists is missing.

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

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

Schema coverage is 100% and the single parameter is fully described there. The description's 'one or more papers' reinforces the array/multi-value semantics but adds no format, syntax, or validity detail 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 (export) and resource (BibTeX citations for one or more papers), plus a distinguishing quality claim: 'exactly as ADS formats them (journal macros, volume, pages, DOI, eprint)'. No sibling is named or contrasted, but the operation is naturally unique among the search/get/library siblings, so the intent is unmistakable.

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 sentence 'Useful for adding references to LaTeX/Quarto documents' gives a downstream use context but no explicit when-to-use trigger, no prerequisites, and no alternatives (e.g., that bibcodes typically come from search_papers). Usage 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, openWorld and non-destructive, so the safety profile is covered. The description then adds a genuinely useful behavioral caveat absent from structured data: name matching sweeps in every paper with that name, so common names may pull in other people's work. It does not describe return shape or how the years filter interacts with the aggregate.

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 sentences with the core purpose and returned fields front-loaded, followed by usage context and the important caveat. Little waste, though the CV sentence is mild 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?

No output schema exists, but the description compensates by naming the metric fields returned, and the annotations cover the safety profile. The ambiguity caveat addresses the main risk. Only minor gaps remain around how years filtering affects totals.

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

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

Schema description coverage is 100%, with both author and years documented in the schema, so the baseline is 3. The description adds no syntax, format, or default guidance beyond what the schema already states.

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 (get), resource (author metrics) and enumerates the returned fields (h-index, total citations, paper count, citation statistics). It is clearly distinct from paper-oriented siblings like get_author_papers and search_papers, though it never explicitly contrasts itself with get_paper_metrics.

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

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

Provides implied context ('useful for CV preparation and tracking research impact') but gives no explicit when-to-use condition, prerequisites, or routing to alternatives such as get_author_papers when the user wants the paper list rather than aggregate metrics.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds the useful detail that results include citations and publication details, but says nothing about pagination, result truncation at max_results, or sorting behavior beyond what the schema states.

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 with the core action front-loaded and zero filler. Nothing is wasted or buried.

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 helpfully identifies what comes back (papers with citations and publication details), and annotations cover safety. It could still note the meaning of max_results truncation or whether an empty author returns an error, but for a simple three-param read tool this is close to complete.

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

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

Schema description coverage is 100%, so all three parameters (author, sort, max_results) are already documented with defaults, limits and an enum. The description's mention of 'citations' loosely echoes the citation_count sort but adds no format or syntax meaning 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 ('Find all papers by a specific author') and sketches the return payload. It is clear on its own, but it never names the obvious siblings (search_papers, get_paper_details) that an agent could confuse it with.

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

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

There is no when-to-use guidance: nothing tells the agent to prefer this over search_papers for author-scoped queries, nor any prerequisite on author name format (the schema shows examples but not the description). Usage is only implied by the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds nothing beyond that: it does not say whether results are paginated, how large a library listing can be, or what the returned 'paper details' include.

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 with the core action front-loaded, but the second sentence largely restates the first ('returns paper details' vs 'get all papers'). Efficient but not fully earned.

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 single-parameter read tool with full annotation coverage and no output schema, the description is minimally adequate. It leaves the library-vs-collection wording ambiguous and gives no sense of result volume or ordering.

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 schema already tells the agent the library_id comes from list_libraries. The description adds no syntax, format, or example beyond that, 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 (get papers from a library) and clarifies it returns paper details, which distinguishes it from list_libraries and add_to_library. Minor wobble between 'library' and 'collection' in the second sentence slightly muddies the target resource.

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?

No guidance on when to use this versus siblings like search_papers, get_paper_details, or get_author_papers. The only routing hint is inherited from the schema's mention of list_libraries, not 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that a rich metadata payload (abstract, authors, citations, keywords) is returned, but says nothing about failed lookups or rate limits, so it adds modest value 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?

Two tight sentences with zero filler, front-loaded on the action and identifier, then the return payload.

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

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

With no output schema, the description correctly enumerates the returned fields ('abstract, authors, citations, keywords, and more'), which is the key missing piece. Minor gap: no statement on behavior when the bibcode is invalid or not found.

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 single bibcode parameter is documented with a concrete example, so the schema carries the load. The description only reinforces that the bibcode is the lookup key without adding format or validation 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?

States a specific verb ('Get detailed information') and resource ('a specific paper'), keyed on the bibcode identifier. It is clearly distinguishable from search_papers and the author/metrics siblings, though it does not explicitly name those alternatives.

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 'using its bibcode' phrasing implies the tool is for single-paper lookups once an identifier is known, but there is no explicit when-to-use/when-not guidance or pointer to search_papers for discovery scenarios.

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, and destructiveHint=false, so the safety and idempotency profile is covered. The description adds the metric categories a caller receives, but says nothing about rate limits, partial-failure behavior for invalid bibcodes, or cost of the open-world call.

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

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

Two sentences, front-loaded with the purpose and followed by the metric contents; no filler or repetition. It is slightly short on routing information rather than verbose.

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

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

With no output schema, the description does list the returned metric categories, which partially compensates. But it omits key details for a batch metrics call — behavior on unknown bibcodes, response shape per paper, and how to choose this over get_paper_details — leaving a small but real gap.

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

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

Schema coverage is 100% and the single bibcodes parameter already carries a format example and minItems=1. The description's 'specific papers' only loosely restates the bibcode-list input without adding batching or format constraints beyond the schema, 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 ('Get detailed metrics for specific papers') and enumerates what is returned: citation count, reads, impact indicators. However, it never distinguishes itself from the close sibling get_paper_details or get_author_metrics, so an agent must infer the boundary from the name alone.

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?

'Useful for tracking paper impact over time' implies a use case but names no alternative tools and gives no condition for choosing metrics over details. Usage is only implied, not directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return-content context (names, descriptions, paper counts) that the annotations cannot convey, though it omits pagination or auth details.

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 verb and resource, followed by the return contents. 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?

With no output schema, the description usefully enumerates what is returned (names, descriptions, paper counts). Only minor gaps remain, such as whether results are paginated or require authentication.

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

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

Zero parameters, so there is nothing to document; baseline 4 applies. The description correctly does not invent parameter guidance where none is needed.

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 ('List') and resource ('personal paper libraries/collections in ADS'), and the phrase 'your personal' scopes it distinctly from siblings like get_library_papers or create_library. An agent can identify the tool's purpose 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?

Usage is implied — this is the natural discovery step before get_library_papers or add_to_library — but the description never says when to use it versus alternatives or states any preconditions. Adequate but with a clear gap.

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, openWorld, non-destructive), so the bar is lower. The description adds genuine value the annotations don't: the shape of the returned records. It omits any note on rate limits, result-window behavior, or empty-result handling, which for an open-world search API would be useful.

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

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

Three sentences, front-loaded with the verb and resource, followed by return shape and then query syntax. Every sentence earns its place with no filler or restatement of the name.

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

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

With no output schema, the description correctly compensates by listing returned fields. Combined with a fully documented 3-parameter schema and complete annotations, an agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by showing field-search syntax ('author:Coelho', 'year:2020-2024'), which the schema's plain example does not teach. It adds nothing about sort or max_results, but those are fully documented in the schema.

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

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

States a specific verb (Search) and resource (NASA ADS papers), names the domain, and enumerates what comes back (bibcodes, titles, authors, years, citation counts). This lets an agent distinguish it from get_paper_details, get_author_papers, and export_bibtex 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?

Tells the agent how to formulate input ('natural language queries or specific field searches') and gives three concrete query examples, which is real usage guidance. It does not, however, say when to prefer a sibling (e.g., get_paper_details once you have a bibcode) or when-not to use it.

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