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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write and repeatability profile is covered. The description adds nothing beyond that: it doesn't state whether duplicate documents are skipped or re-added, whether the operation is cancellable/undoable, or what happens when the query matches more than 'rows' results.

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

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

A single front-loaded sentence with no filler, which is appropriate for a terse tool. It is arguably too terse given the mutation semantics, but it wastes no 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?

For a non-idempotent mutation with no output schema and no annotations explaining side effects, the description should say what the call returns (count added?) and how duplicates are handled. Those gaps leave the agent unable to predict the outcome of a 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?

Schema description coverage is 75%, so most parameters (query, library_id, rows) are self-documented in the schema. The description itself adds no syntax, format, or default information beyond what the schema provides, so it sits at the baseline.

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 (documents to a library) plus the source (SciX search query), which is more informative than a bare name. It does not, however, differentiate itself from siblings like manage_documents or search_docs, so an agent must infer the boundary.

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, no mention of prerequisites (e.g. that the library must exist or that permission is required), and no routing to alternatives such as manage_documents for other document-editing modes. The agent is left to infer the context entirely.

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, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description contributes only the fact that documents may be attached at creation time; it says nothing about permission requirements, name uniqueness behavior, or whether duplicate calls create duplicate libraries.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity is partly under-specification rather than deliberate tightness.

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 non-idempotent mutation tool with five parameters and no output schema, the description omits what is returned (e.g., the new library's identifier) and any error or permission conditions. An agent can call it, but cannot anticipate the result or failure modes.

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 80%, so the schema already documents name, public, bibcodes, and description. The description echoes 'name' and the initial-documents concept without adding format, limits, or interaction details, 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?

The description states a specific verb and resource ('Create a new library') and adds scope ('with optional initial documents'), which is clear enough to separate it from get_library, delete_library, and edit_library. It stops short of naming any sibling or the boundary between create_library and add_documents_by_query for seeding documents.

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, no prerequisites (authentication, ownership), and no mention of alternatives such as edit_library for modifying an existing library. The agent must infer that this is the creation path purely from the verb.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered by structured data. The description adds nothing beyond restating the deletion: no indication that the removal is permanent, whether it requires write permission, or whether deleting the note affects the annotation object itself.

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

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

A single front-loaded sentence with zero filler. It is arguably too terse for a destructive mutation tool, but nothing in it is wasted.

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 destructive, non-idempotent mutation with no output schema and an ambiguous sibling (manage_annotation), the description is too thin: it omits reversibility, permission requirements, and any routing guidance to the correct sibling.

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

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

Schema coverage is 67%: bibcode and library_id are described in the schema, while response_format has only an enum and default with no description. The description mentions the document/library context but adds no parameter-level meaning, so it neither compensates nor regresses.

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 (delete) and resource (annotation/note) scoped to a document in a library, so the core action is unambiguous. However, siblings get_annotation and especially manage_annotation exist, and the description does nothing to distinguish this targeted delete from whatever manage_annotation covers.

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 when-to-use guidance, no prerequisites, and no named alternative despite manage_annotation sitting in the sibling list. The agent must infer that this is the single-annotation delete path rather than the bulk/management path.

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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so 'permanently' largely restates structured data. The description adds nothing about cascade effects (e.g. what happens to documents in the deleted library), permission requirements, or confirmation behavior that the annotations do not already convey.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though the brevity reflects under-specification rather than disciplined editing.

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 destructive, non-idempotent, open-world operation with no output schema and partial parameter documentation, the description is too thin. It omits side effects, required permissions, and any indication of what the caller gets back.

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

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

Schema description coverage is only 50%: library_id has a description, but response_format carries no description in the schema and the tool description says nothing about either parameter. With the description adding zero parameter meaning, it fails to 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 resource ('Delete a library') plus the irreversible scope ('permanently'), which cleanly separates it from edit_library and delete_annotation. It does not, however, name any sibling or contrast itself with alternatives like delete_annotation.

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 when-to-use guidance, no prerequisites, no mention of alternatives such as edit_library for non-destructive changes or transfer_library for ownership changes. The agent must infer all of this from the name alone.

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 destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: it specifies that existing values are overwritten (so partial-vs-full semantics matter) and warns that flipping public status can expose a private library. That risk disclosure is not derivable from the annotation set.

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 purpose and followed by the two behavioral caveats. No filler, no repetition of schema fields beyond what the risk warning requires.

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?

Covers purpose, mutation semantics, and the privacy hazard, which is most of what an agent needs; no output schema exists so return values need not be explained. It does leave one gap: whether omitting a field leaves it untouched or clears it, which matters given the 'overwrites' wording.

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 80%, so the schema already documents the parameters, and 3 of 5 (name, description, public) are echoed in prose. library_id and response_format receive no added meaning, and no format/syntax detail is offered, so this lands at the baseline.

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 (Edit) and resource (library metadata) and enumerates the mutable fields (name, description, public status), which cleanly separates it from get_library, create_library, and delete_library. It does not explicitly name those siblings, 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?

No when-to-use guidance, prerequisites, or named alternatives are provided. An agent must infer from the name and the sibling list that this is the update path versus create_library/delete_library, which is exactly the 'no guidance' case.

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=true, destructiveHint=false, openWorld=true and idempotentHint=false, covering the safety profile. The description adds that custom templates are supported, which is useful context, but omits practical traits like the 2000-bibcode cap and behavior of the 'custom' format path.

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

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

A single front-loaded sentence that names the action, the resource, and the breadth of formats without filler. Efficient, though it could have traded a few format examples for usage 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?

With 8 parameters, 100% schema coverage, and no output schema, the description covers the core capability but says nothing about what is returned (raw text vs structured) or the custom_format requirement, leaving some gaps for an agent to infer.

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 every parameter is already documented in structured form. The description reinforces the format dimension and custom-template concept but adds no syntax or semantics beyond what the schema/enum provides, 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 (Export) and resource (citations) plus the breadth of output formats. An agent can see this is the citation-formatting tool, distinct from data-retrieval siblings like get_citations or get_references, though the description never explicitly contrasts with them.

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 word 'export' and the format enumeration; there is no explicit guidance on when to choose this over retrieving citations directly, nor any noted preconditions such as obtaining bibcodes first.

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, giving the safety profile. The description adds no further behavioral context such as return format, missing annotation behavior, or permissions, and does not contradict the annotations.

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

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

A single front-loaded sentence with zero wasted words. It is appropriately sized for the tool's simple retrieval 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?

The description states the core retrieval action and scope, which is minimally adequate for a simple read tool with annotations. However, it omits response_format semantics and any guidance about missing annotations or alternatives, leaving 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 coverage is 67%, with descriptions for bibcode and library_id but none for response_format. The description only restates 'document in a library' and adds no meaning beyond the schema, failing to compensate for the undocumented response_format parameter.

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 gives a specific verb (Get), resource (annotation/note), and scope (for a document in a library), so an agent can tell it apart from delete_annotation and manage_annotation by verb. It does not explicitly name sibling tools, but the purpose is clear.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The implied usage is retrievable from the verb, but no explicit when/when-not context is provided.

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 safety is covered. The description adds nothing behavioral beyond that: no ordering, pagination, or result-count behavior, and no note on what happens with an unresolvable identifier. It does not contradict the annotations, but it contributes no behavioral context.

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 the accepted identifier forms are both front-loaded. Nothing in it wastes the agent's reading budget.

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, yet the description never characterizes the return (list of papers, ordering, fields), though it does cover the identifier input forms required to call it. For a simple read-only list tool this is nearly complete, with only return-shape details 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 67% and the schema already documents the identifier formats verbatim ('bibcode, DOI, arXiv ID, or SciX ID'), so the description's identifier sentence is largely a restatement. 'rows' and 'response_format' semantics come from the schema, not the description. 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?

States a specific verb (get) and resource (papers that cite a given paper) and disambiguates direction with '(forward citations)', which separates it from the references-style sibling. It does not, however, name the sibling tool (e.g. get_references) the way the highest-scoring definitions do.

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 '(forward citations)' qualifier implies when this tool applies versus a backward-citation tool, but there is no explicit when-to-use statement, no mention of get_references or get_paper as alternatives, and no preconditions. Usage is 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral value by explaining the return shape: each bucket carries a ready-to-use filter_query and hierarchical facets report a child_prefix for drilling deeper. It omits any mention of limits/rate behavior, keeping it from a 5.

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 before the facet enumeration and return-value note. The long facet list duplicates the schema enum, which is mildly wasteful, but overall the structure is 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?

With no output schema, the description carries the burden of explaining returns, and it does so for the key fields (filter_query, child_prefix). For a read-only facet tool whose annotations cover safety, this is nearly complete, missing only limit/defaults context.

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 86%, so the schema already documents nearly every parameter, and the enum of facets is duplicated verbatim in prose. The description does add the drill-down semantics of `prefix`/`child_prefix`, but this is largely reinforced by the schema's own prefix description, so a 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 opens with a specific verb and resource ('Count how SciX search results break down across facets') and states the goal ('to narrow a search'). It clearly distinguishes itself from the sibling `search` tool by describing an aggregation/breakdown role rather than 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?

It gives a clear usage context ('to narrow a search') and explicitly routes the agent back to the `search` sibling by noting buckets carry a filter_query to pass back, plus child_prefix for drill-down. It stops short of stating when NOT to use this tool or explicit preconditions, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only the 'authenticated user' scoping, and says nothing about pagination, result size, or ordering for a potentially large list.

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 no filler. The second sentence is somewhat redundant with the schema enum, but the overall size is appropriate.

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 two-parameter read-only list tool with no output schema, the description covers the action and filter but omits anything about return shape, ordering, or limits. Adequate but with visible 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 coverage is 50%: the 'type' parameter is already documented in the schema, and the description merely repeats its enum values rather than adding meaning. The 'response_format' parameter has no description anywhere, and the description does not compensate for that 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 resource ('Get all libraries') plus scope ('for the authenticated user'), which implicitly separates it from the singular get_library sibling. It does not explicitly name or rule out any sibling, so it falls 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: the tool enumerates the user's libraries, and the type filter hints at a use case (owned vs shared). There is no statement of when to prefer this over get_library or search, and no prerequisites or exclusions are 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the return content (metadata and document list), which matters because there is no output schema, but says nothing about pagination, truncation, or access restrictions on private libraries.

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

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

A single front-loaded sentence with no filler. It is efficient, though it uses its brevity to omit any routing or scoping detail that would have earned 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 simple two-parameter read tool with full annotation coverage, the description covers what the tool returns, which is useful given no output schema. It leaves unclear whether the document list is paginated or complete, and what response_format changes about the result.

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 50%: library_id is documented in the schema while response_format is an enum with a default, largely self-explanatory. The description adds no parameter meaning 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?

Clear verb+resource: retrieves details for a single library and names the payload (metadata plus document list). It does not explicitly distinguish itself from the sibling get_libraries (plural listing) or from search_docs, so it is clear but not sibling-differentiating.

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 'specific' implies a single-identifier lookup rather than a listing, which weakly routes an agent away from get_libraries. However, no explicit when-to-use, prerequisites, or named alternatives are provided.

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/behavior profile is covered and the description need not restate it. The description adds the batch framing ('for a list of bibcodes') but omits practical traits such as the 2000-bibcode ceiling and any rate/latency behavior for large lists.

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

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

A single efficient sentence that front-loads the verb and the returned fields with no filler. It is appropriately sized for a two-parameter tool, though it could have spent one clause on the response_format choice.

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 names the returned metric types, which is the main thing an agent needs. However, it is silent on the response_format parameter's markdown/json behavior and the 2000-item input limit, so it is adequate but not complete for a batch 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 description coverage is 50%: 'bibcodes' is documented inline, but 'response_format' (enum markdown/json with default markdown) has no description anywhere. The description reinforces the bibcode-list input but adds nothing about output format selection, so it neither compensates for the gap nor regresses below the baseline.

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+resource ('Get citation metrics') and enumerates the return payload (h-index, citation counts, paper statistics), so the agent knows what it gets. It does not explicitly differentiate itself from citation-oriented siblings like get_citations or get_references, which is the only gap.

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 when-to-use guidance, no prerequisites, and no named alternative among the 22 sibling tools. The reader must infer that this is the batch-metrics tool versus get_citations/get_references, and nothing states whether bibcodes must already exist or how many calls are appropriate.

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 safety behavior is fully covered. The description adds no behavioral context beyond restating the identifier types already in the schema; it says nothing about error behavior, lookup breadth, or what 'detailed information' includes.

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

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

A single front-loaded sentence with no wasted words. It leads with the action and resource immediately, then specifies accepted identifier formats.

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 two-parameter read tool with rich annotations and no output schema, the description is minimally adequate. However, it omits any mention of response_format or the shape of the returned 'detailed information,' leaving an agent to discover those through the schema alone.

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 50%, and the description only repeats the bibcode parameter's accepted identifier types exactly as written in the schema. The second parameter, response_format, is an enum with no description in the schema and is not mentioned at all, so the description 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 ('Get') and resource ('detailed information about a specific paper') and enumerates accepted identifier types. It does not explicitly differentiate itself from the sibling 'search' tool, but the purpose is clear 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: call this when you have a specific paper identifier and need details. However, it never states when to use this instead of 'search' or what to do if the identifier type is unknown, leaving alternatives 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, covering the safety profile. The description adds nothing beyond that: no note on permissions required to view permissions, no indication of whether results are cached or scoped to the caller's role.

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

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

A single short sentence with the resource front-loaded and zero filler. It is appropriately sized for its content, though the content itself is thin rather than the structure being wasteful.

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

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

For a simple, read-only, idempotent lookup with annotations covering safety, the description is minimally sufficient. However, with no output schema, an agent gets no sense of what 'permission information' contains (roles, users, groups) or how response_format changes the result.

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 only 50%: library_id is documented in the schema while response_format (an enum with a markdown default) has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented response_format and its effect on output.

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) and resource (permission information) scoped to a library, which implicitly separates it from the sibling update_permissions. It does not explicitly name or contrast with any sibling, so an agent must infer the read-vs-write distinction from the verb 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_permissions or library_operation. The description gives only what the tool returns, leaving the agent to guess the triggering context.

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 no behavioral detail beyond that (no pagination, result limits, or auth notes), so it neither adds value nor contradicts the annotations.

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

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

Two tightly written sentences with the core action front-loaded and the accepted identifier formats placed after. No filler or redundancy.

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

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

For a simple read-only lookup the description is adequate, but with no output schema it omits what a result contains and ignores the rows (default 20, max 100) and response_format parameters entirely. An agent gets the gist but not the full call contract.

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

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

Schema coverage is 67% and the listed identifier types ('bibcode, DOI, arXiv ID, or SciX ID') duplicate what the bibcode property description already says. The rows and response_format parameters get no mention in the description, so it adds no 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?

States a specific verb+resource ('Get papers referenced by a given paper') and adds the parenthetical '(backward citations)' which meaningfully clarifies direction. It implicitly separates itself from the sibling get_citations, though it never names that sibling explicitly.

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 'backward citations' phrasing implies when this applies versus forward citations, but no when-to-use/when-not guidance or named alternative (get_citations) is given. Usage is left to inference from the parenthetical.

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 genuine context by listing the exact diagnostic fields returned and confirming no required arguments. It does not mention that the auth probe may make a network call or how failures are surfaced, but openWorldHint plus the enumerated fields largely fill that gap.

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

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

Two sentences, each earning its place: the first enumerates the diagnostic output, the second routes the agent's decision. Nothing is padded or repeated from the 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 no output schema, the description correctly takes on the burden of describing return contents via its field enumeration, which is adequate. The only minor gap is the unmentioned response_format option, which would have completed the picture.

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?

There is one optional parameter (response_format) with an enum and default, and schema coverage is 0% — the description never mentions it. The parameter is self-documenting via its enum+default, so an agent can still use it, but the description adds nothing here and 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 ("Diagnose") and resource ("SciX MCP server setup"), then enumerates exactly what the report contains (server name/version, base URL, token presence, auth probe, registered tool names). This is unmistakable against the sibling set, all of which are data-access tools like search, get_paper, and export.

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 frames the use case: "Use this to distinguish setup problems (missing/invalid token, unreachable API) from ordinary API errors," which is a clear trigger condition. It does not name exclusion alternatives, but none of the siblings overlap in purpose, so the guidance is sufficient in practice.

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 give a blanket destructiveHint=true, but the description adds granular value by specifying that empty, difference, and intersection replace or discard target library contents, while union and copy do not. This per-operation destructive detail goes beyond the annotations, though it omits permission requirements and reversibility.

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 no filler; the purpose is front-loaded and the destructive caveat follows immediately. It could have been slightly more efficient by tying the destructive note directly to the operation names, but it is well-structured.

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 6-parameter, multi-mode, destructive, open-world tool with no output schema, the description covers purpose and destructiveness but omits which parameters each operation requires (e.g., source_library_ids for union) and what the call returns. Adequate but with clear 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 83%, so the schema already documents name/description (copy-only) and source_library_ids (union/intersection/difference). The description adds no parameter-level detail beyond mapping operations to destructiveness, so the 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 states a specific verb+resource (set operations on libraries) and enumerates the five supported operations, which is more than a restatement of the tool name. It does not explicitly differentiate itself from siblings such as create_library, edit_library, or delete_library, so it falls 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?

There is no explicit guidance on when to choose this tool over the sibling library tools (get_library, create_library, edit_library, delete_library, transfer_library), nor any stated prerequisites. The operation list implies usage, but no alternatives or conditions are named.

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, destructiveHint=true and idempotentHint=true. The description adds real behavioral context by disclosing that an update replaces the prior note content, which is exactly the destructive semantic an agent needs to see before overwriting. It still omits whether the target document must already be in the library and 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 short sentences, with the core action stated first and the destructive overwrite caveat immediately after. No filler and nothing redundant with the title or 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 annotations covering write/destructive/idempotent signals and no output schema to explain, the main open questions are permissions on the library and what the call returns. The description addresses the update semantics but leaves those gaps, making it adequate rather than 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 75% with three self-explanatory required fields (library_id, bibcode, content), so the schema carries most of the semantic load. The description adds the replace-vs-append behavior of content but says nothing about response_format, which has an enum and no schema description.

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 gives a specific verb pair and resource: add or update an annotation/note for a document in a library. The write orientation implicitly separates it from the read/delete siblings get_annotation and delete_annotation, but it never names them, so 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?

Usage is implied by 'Add or update' plus the note that updating replaces existing content, so an agent can tell this is the create/overwrite path. There is no explicit guidance on when to prefer it over get_annotation, delete_annotation, or manage_documents, and no stated prerequisites such as required library permissions.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds genuinely non-redundant context: removal 'discards the record of those documents in that library,' clarifying that the deletion is library-scoped rather than a global document delete. It stops short of noting permission requirements or the behavior of duplicate adds.

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, no waste, with the add/remove capability front-loaded and the destructive caveat immediately after. Every clause earns its place.

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

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

For a 4-parameter destructive mutation with no output schema, the definition covers the core operation and the consequence of removal, but omits prerequisite permissions, partial-failure behavior when some bibcodes fail, and why removal is marked idempotent. Adequate but with clear 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 75% and the description itself adds nothing about parameters — it never mentions bibcodes, library_id, action, or response_format. With the schema already documenting three of four parameters, 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 pair (add/remove) and resource (documents in a library), so the agent immediately knows this is a bulk membership operation keyed on bibcodes. It does not, however, distinguish itself from the sibling add_documents_by_query, which is the closest overlapping tool.

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 and no mention of alternatives such as add_documents_by_query (query-driven addition) or library_operation. The agent must infer from the parameter names that this is the explicit-bibcode path rather than the query path.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds useful context about query syntax support and the facet-filtering workflow, but says nothing about pagination behavior, result counts, or rate limits beyond what annotations and schema 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?

Three sentences, front-loaded with purpose then query capability then sibling workflow. Every sentence carries information an agent needs; nothing is redundant with 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?

No output schema exists, but the description focuses on the one thing the agent most needs to get right: constructing valid queries and filters. Return format, pagination, and sort behavior are delegated to the schema, which documents them adequately, so the definition is nearly 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 baseline is 3. The description goes beyond the schema by showing concrete Solr syntax examples (author:"Last, F.", year:2020-2023, Boolean operators) and by tying filter_query to get_facets output, adding real meaning not present in the terse schema 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?

States a specific verb and resource ('Search SciX for astronomical literature') and immediately identifies the query dialect, which distinguishes it from sibling tools like search_docs or get_paper. An agent can tell what this tool retrieves 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?

Explicitly routes the agent to get_facets for obtaining facet values and tells it to pass them via filter_query, which is a genuine usage instruction. It lacks explicit when-not guidance or alternatives (e.g., when to prefer search_docs), so it stops short of a 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds no behavioral context beyond that — no note on result freshness, ranking, or whether an empty result is possible.

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

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

A single front-loaded sentence with zero filler; the resource and supported topics are stated immediately and 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 simple two-parameter read-only search with no output schema, the description is nearly sufficient. It could have named the sibling `search` tool to prevent confusion, but no critical invocation detail 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%, with both `query` and `limit` documented in the schema, so the baseline is 3. The description adds nothing about query phrasing or result count behavior beyond what the schema 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?

The description names a specific verb (Search) and resource (SciX help documentation) and enumerates the content covered (search syntax, features, API usage, best practices). It is clear this targets docs rather than the sibling `search` tool, but it never explicitly states that distinction.

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 can infer it should call this when it needs documentation help, but there is no explicit when-to-use statement, no prerequisites, and no mention of the sibling `search` tool as an alternative for actual paper retrieval.

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 destructiveHint=true, so the bar is lower, yet the description still adds real value by naming the specific consequence: the current owner loses ownership. It also states the server cannot undo the change, which sharpens the destructiveness beyond the boolean hint. Missing: whether the target user must already exist and any permission requirements.

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, zero filler, with the action front-loaded and the irreversible consequence immediately after. Every clause earns its place.

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

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

For a destructive mutation with no output schema, the description covers the key behavioral risk (ownership loss, no undo) and annotations cover the rest of the safety profile. It falls short only on prerequisites such as target-user existence and required permissions.

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

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

Schema coverage is 67%: email and library_id carry descriptions while response_format is undocumented in both places. The description's 'to another user' loosely maps to the email parameter but adds no format or validation detail beyond the schema's email pattern, so it lands at the baseline.

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 (transfer) and resource (ownership of a library) plus the recipient, so the operation is unambiguous. It does not, however, distinguish itself from potentially confusable siblings like update_permissions or edit_library, so an agent must infer the boundary.

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 by the irreversible framing ('the current owner loses ownership'), which tells the agent this is a deliberate hand-off rather than a routine edit. No explicit when-not or alternative tool (e.g., update_permissions for access changes) is named, leaving routing 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds that existing collaborator access can be revoked, which sharpens the destructive implication, but it omits guardrails like permission requirements or effects on the last owner.

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 the revocation note placed second. Every clause carries information and 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?

For a destructive permissions mutation with no output schema, the description covers what changes and that existing access can be removed, but says nothing about authorization requirements, precedence when downgrading, or failure behavior. Adequate but with clear 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?

With 75% schema coverage, the schema already documents email, library_id and permission; the description only frames permission as grantable/modifiable without explaining the owner/admin/write/read hierarchy. response_format is undocumented in both places. This is the baseline 3 – no real value added beyond the structured fields.

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 ('Grant or modify permissions for a user on a library') and extends scope with the revocation capability. It does not explicitly differentiate itself from siblings such as get_permissions or transfer_library, so it falls 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?

It characterizes the operation but never says when to reach for this tool versus get_permissions or transfer_library, nor what prerequisites (e.g., caller must be owner/admin) apply. Usage is only inferable from the verb.

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