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

No annotations are provided, so the description must carry the behavioral disclosure burden. It states the core create action but does not disclose duplicate handling, required permissions, side effects, or what is returned on success or failure. This is a significant gap for a mutation tool.

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

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

The description is a single, front-loaded sentence with no filler. It states the action and key parameters efficiently, making it easy for an agent to parse.

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

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

Despite having an output schema, the tool has no annotations and 0% schema description coverage. The one-sentence description does not cover required title, doc_type default, object formats for authors/identifiers, or behavioral consequences. It is a useful summary but not fully actionable guidance.

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 0%, and the description compensates by listing most parameters (title, authors, year, source, abstract, identifiers) and framing them as bibliographic metadata. However, it omits doc_type and does not explain the expected structure of authors or identifiers objects, leaving some ambiguity.

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

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

The description uses the specific verb 'Create' and identifies the resource as 'a new library entry', with examples of the bibliographic metadata involved. This clearly distinguishes it from sibling operations like mendeley_add_document_to_folder, mendeley_update_document, and mendeley_delete_document.

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

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

The description provides clear context: use this tool when creating a new library entry from metadata. It does not explicitly state when not to use it or name alternatives, but the use case is unambiguous given the sibling set.

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

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

No annotations are provided, so the description carries the full behavioral burden. It states the basic mutation ('Add') but does not disclose important behavioral traits such as idempotency, duplicate handling, whether an error occurs if the document is already in the folder, or any side effects beyond the relationship.

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 sentence that is tight, front-loaded, and contains no filler. The key qualifiers 'existing library document' and 'existing folder' add meaningful scope without unnecessary elaboration.

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 mutation with an output schema, the description is adequate but minimal. It does not need to explain return values, but it also omits any guidance on error conditions, duplicate additions, or whether the folder_id/document_id must come from specific sibling tools. An agent could invoke it correctly but with incomplete expectations about behavior.

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

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

The schema has 0% description coverage, so the description must compensate. It partially does by clarifying that the operation involves an 'existing library document' and an 'existing folder', which maps to document_id and folder_id. However, it does not explain the ID format, where to obtain valid IDs, or any restrictions on which document types can be added.

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 clear verb ('Add') with a specific resource ('existing library document') and target ('existing folder'). It distinguishes itself from siblings like mendeley_add_document (which adds a document to the library) and mendeley_remove_document_from_folder (which removes it), so an agent can select the correct 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?

The phrase 'existing library document' and 'existing folder' implies this tool is for linking already-created entities, but the description does not explicitly state when to use it versus the alternatives, nor does it mention prerequisites such as fetching IDs from list_documents or list_folders. It provides only implied usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the placement behavior (nesting, group context), which is genuinely useful, but it does not disclose that this is a state-mutating write, how duplicate folder names are handled, permission requirements, or failure modes. For a mutation tool with zero annotation coverage, this is a meaningful 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?

A single 22-word sentence with zero wasted words. The action verb and resource are front-loaded, followed by the three placement contexts. Every phrase earns its place.

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

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

The tool is simple (3 params, 1 required) and an output schema exists, so return-value explanation is unnecessary. The description adequately covers the three creation modes. However, it omits guidance on sourcing parent_id/group_id and, because no annotations exist, leaves the behavioral safety profile undisclosed — gaps that matter for a state-changing 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?

With 0% schema description coverage, the description must compensate, and it partially does: 'name' maps to the folder name, 'parent_id' to the nesting behavior, and 'group_id' to the group context. However, it does not clarify which parameters are required, where to obtain valid parent_id or group_id values (e.g., via mendeley_list_folders), or the relationship between group context and personal library.

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 ('Create') and resource ('a new folder'), and enumerates three distinct scopes: personal library, nested under a parent, or in a group context. This clearly differentiates it from sibling tools like mendeley_rename_folder, mendeley_delete_folder, and mendeley_list_folders, though it does not name them 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 description implies when to use the tool — whenever a new folder is needed — and sketches the three usage contexts via 'nested under a parent folder, or in a group context.' However, it provides no explicit when-not-to-use guidance or routing to alternative tools, and it doesn't explain when each placement mode (root vs. parent_id vs. group_id) is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that deletion is permanent, cannot be undone through the API, and requires user confirmation — all critical behavioral traits for a destructive tool.

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

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

Two sentences with no filler. The operation is stated first, followed immediately by the destructive warning and the required user-confirmation behavior. 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 simple one-parameter destructive operation, the description is complete: it names the resource, explains the consequence, and gives the required safety protocol. Since an output schema exists, return-value documentation is not needed.

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

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

The single required parameter, document_id, is never described in the prose, and schema description coverage is 0%. The description says 'a document' but does not explicitly connect it to the document_id parameter or explain what identifier is expected. The parameter name provides some clue, but the description does not compensate for the lack of schema guidance.

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

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

The description uses a specific verb and resource: 'Permanently delete a document from the library.' It clearly distinguishes this from sibling operations like deleting a folder or updating a document.

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

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

It clearly instructs the agent to confirm with the user before calling because the operation is destructive and irreversible. It does not explicitly enumerate alternative tools or when not to use it, but the deletion purpose and confirmation gate are strong 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does state that the operation deletes an existing folder and returns confirmation, which establishes the destructive nature. However, it does not disclose side effects such as whether child folders or contained documents are deleted, nor does it cover error behavior or 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?

The description is a single, clean sentence that front-loads the action and outcome. It contains no filler or redundant restatement of the tool 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?

For a single-parameter destructive operation with an output schema, the description is minimally viable. It names the action, target, and return behavior. Yet with no annotations and many folder-related siblings, the lack of side-effect and routing guidance leaves a notable completeness 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 0%, so the description needs to compensate, but it never explicitly explains folder_id beyond implying it identifies the folder to delete. The word 'existing' adds a small constraint, but there is no guidance on format, how to obtain the ID, or why an ID might be invalid.

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

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

The description uses a specific verb ('Delete'), names the resource ('folder'), qualifies it as existing, and states the return expectation ('deletion confirmation'). It clearly distinguishes this from siblings like mendeley_delete_document and mendeley_remove_document_from_folder.

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 mendeley_remove_document_from_folder, mendeley_rename_folder, or mendeley_delete_document. It also does not mention prerequisites such as whether the folder must be empty or what happens if the folder does not exist.

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

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

The description discloses that the tool returns raw BibTeX text ready to paste into a .bib file and that the output is generated by Mendeley. However, it does not explain how the limit parameter affects folder exports, and the claim of exporting 'all documents in a folder' sits uneasily with the default limit of 50.

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

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

The description is compact and front-loaded: the action and the critical one-of rule appear immediately. Every sentence adds useful information, with no filler or repetition.

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

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

The output schema covers return structure, but the description omits the behavior of the limit parameter and appears to contradict it by saying 'all documents' when the default limit is 50. An agent could under-export a large folder without realizing it, and the one-of constraint is not enforced by the schema, so the description must fully explain the boundary conditions but does not.

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

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

The description adds meaningful exclusive-or semantics for document_id and folder_id, which the schema lacks since no parameters are required. However, schema description coverage is 0%, and the limit parameter is not explained at all, leaving one of three parameters semantically opaque.

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

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

The description clearly identifies the action (export), the resource (BibTeX), and the scope (one document or all documents in a folder). It also states the output format, which distinguishes it from the sibling tools that search, fetch, or manage Mendeley records.

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 gives an explicit, actionable usage rule: 'Provide exactly one of document_id or folder_id.' It does not explicitly discuss when to prefer this tool over siblings, but the tool's unique export purpose makes that context reasonably clear.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It does disclose that only the user's own annotations are returned and that note text and page numbers are included. However, it does not mention pagination, limit behavior, authentication requirements, or error cases, leaving some behavioral gaps for a read tool.

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

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

The description is two sentences with no filler. It front-loads the core function and adds a practical use case in the second sentence, making it efficient and easy to parse.

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 presence of an output schema covers return-value structure, and the description explains the core purpose well. However, it omits guidance on the limit parameter and does not suggest when to choose this tool over sibling content-retrieval tools, so the overall context is adequate but not thorough.

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 0%, and the description only implicitly explains document_id via 'on a library document'. The limit parameter is entirely unexplained, despite having a default of 50. The description provides some meaning for one parameter but fails to compensate for the total lack of 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?

The description clearly identifies the verb (Get), the resource (annotations on a library document), and the scope (user's own annotations, PDF highlights and sticky notes). It also names specific output elements (note text, pages), and this scope makes it distinct from sibling tools like mendeley_get_document_text or mendeley_get_file_content.

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

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

The description provides a general use case ('surfacing what the user marked as important in a paper') but does not explicitly compare with alternatives or state when not to use this tool. It is clear enough for a simple read operation, but lacks explicit routing relative to the many sibling tools.

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

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

With no annotations, the description carries the behavioral transparency burden. It discloses the core read-like behavior and the 'best matching' caveat, but it does not describe failure behavior, whether the operation is strictly read-only, or what happens when no match is found. This is adequate but leaves notable gaps.

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

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

The description is a single, focused sentence with no filler. The primary action and the key output element (catalog_id) are front-loaded, making it easy for an agent to parse quickly.

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

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

The tool is simple with one parameter and has an output schema, so the description does not need to explain return values. It covers the core behavior and the important catalog_id linkage. Missing sibling differentiation is the main gap, but the low complexity makes this largely 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?

The input schema provides no description for the single 'doi' parameter (0% coverage), so the description's mention of 'Resolve a DOI' adds minimal semantic context. It correctly suggests how the parameter is used, but it does not provide format requirements, examples, or edge-case handling.

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 action ('Resolve a DOI') against a specific resource ('the Mendeley catalog') and names the returned artifact ('best matching paper metadata, including catalog_id'). This clearly distinguishes the tool from siblings like mendeley_get_document and mendeley_search_catalog, since the DOI-based lookup is explicit.

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 intended use is implied by the description: use it when you have a DOI and need Mendeley catalog metadata or a catalog_id for downstream actions. However, it does not explicitly state when not to use it or compare it to alternatives such as mendeley_search_catalog or mendeley_get_document.

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?

No annotations are present, so the description carries the full burden. It discloses what data is returned and calls out the attached-file indicator. However, it does not address failure modes, permissions, or how this differs behaviorally from related getters beyond the scope of metadata.

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 well-structured sentence that front-loads the core action ('Fetch full metadata') and then lists the meaningful fields. There is no wasted text or unnecessary repetition of the tool 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?

For a simple get-by-ID operation with one required parameter and an output schema present, the description provides sufficient context by enumerating the metadata categories returned. It lacks explicit alternative routing and error behavior, but these are minor given the tool's simplicity.

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 0%, but there is only one parameter, document_id, whose role is easily inferred from 'one library document'. The description doesn't explain the ID format or provide lookup guidance, but for a single obvious parameter the name plus context is mostly adequate.

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

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

Description uses a specific verb and resource: 'Fetch full metadata for one library document' and lists concrete fields (identifiers, abstract, keywords, tags, timestamps, file attachment). This clearly distinguishes it from siblings like mendeley_get_document_text, mendeley_get_file_content, and mendeley_list_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?

The singular 'one library document' clearly indicates the intended use case: retrieve complete metadata for a specific document by its ID. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to avoid confusion with search/list/content siblings.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that the tool returns full text, works only on born-digital PDFs, and returns an empty result for scanned/image-only PDFs. It could also mention what happens when no PDF is attached, but the key behaviors are disclosed.

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

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

The description is three short sentences with no filler. The core function is front-loaded, the use case is stated, and the important limitation is included. 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 single-parameter tool with no output schema, the description covers the main behavior, the intended use, and a key edge case. The main missing context is how to source document_id and what happens if the document has no attached PDF, but overall the description is sufficiently complete for typical use.

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

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

Schema description coverage is 0%, and the description does not explain the document_id parameter or indicate how to obtain it (e.g., via mendeley_search_library or mendeley_list_documents). The only indirect hint is 'library document,' which is insufficient compensation for the missing parameter documentation.

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

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

The description clearly states a specific action—extracting and returning the full text of the PDF attached to a library document—and explains its purpose for reading or analyzing papers. It does not explicitly distinguish itself from the sibling mendeley_get_file_content, but the 'full text of the PDF' and 'model can read the paper's contents' framing provides enough functional differentiation.

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

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

The description gives clear usage guidance: 'Use this when asked to read, summarize, or answer questions about a paper.' It also provides a capability boundary for scanned/image-only PDFs, though it does not name alternative tools or state explicit when-not-to-use conditions.

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?

With no annotations provided, the description carries the full burden and does disclose important behavioral traits: it 'tries' to download, it only handles the first file, and the PDF is only returned 'when Mendeley exposes one'. It does not cover error handling or side effects, but for a read/download operation the key uncertainties are surfaced.

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

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

The description is two short, front-loaded sentences with no filler. The action, target, return value, and main caveat are all covered efficiently, and every clause contributes meaningful information.

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

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

For a one-parameter tool with no output schema and no annotations, the description gives enough to invoke it correctly and to set expectations about the returned metadata and embedded PDF. Exact return structure and failure behavior are not documented, but the caveats 'try' and 'when Mendeley exposes one' partially cover those 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 0%, and the description only indirectly defines document_id by referring to 'a library document or catalog entry'. This gives some context, but it does not specify the ID format, its origin, or how it relates to IDs used by sibling tools, so the compensation for the missing schema descriptions is only partial.

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 action ('try to download') and a specific resource ('first file attached to a library document or catalog entry'), which clearly distinguishes it from siblings like mendeley_get_document or mendeley_get_document_text. It also adds the conditional caveat about whether Mendeley exposes a PDF, making the tool's purpose unambiguous.

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

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

The description clearly indicates when to use this tool: when an agent needs the file content of a document's or catalog entry's first attachment. It does not explicitly name alternatives or provide exclusion criteria, but the context is clear enough to guide tool selection without opening other definitions.

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?

With no annotations, the description carries the behavioral burden. It correctly communicates that this is a non-mutating listing operation, supports folder filtering, and names three sort dimensions. However, it does not disclose pagination or limit behavior, nor does it explicitly state that the tool returns document metadata/summaries rather than full content, though the output schema partially compensates.

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 states the action, scope, optional filter, and sort choices with no filler. Every phrase earns its place, and the most important information ('List documents') appears immediately.

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 list operation with three optional, defaulted parameters and an output schema, the description covers the main selection and invocation traits. It is slightly incomplete only in not flagging when to prefer mendeley_search_library over this tool and not specifying pagination behavior, but these are minor given the low complexity and existing schema.

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

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

Schema description coverage is 0%, so the description must add parameter meaning. It adds semantic value by explaining that sort_by corresponds to last modification, creation date, or title, and that folder_id filters by folder; limit is left implicit despite having a default. The human-readable sort labels are not quoted as exact API values, which could lead an agent to pass invalid sort strings.

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 the specific verb 'List' and a concrete resource ('documents from the library'), clearly distinguishing it from sibling operations like mendeley_search_library, mendeley_get_document, and folder-management tools. It also states the optional folder filter and sort options, leaving no ambiguity about the tool's core function.

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

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

The description implies a clear use case—obtain a listing of library documents, optionally scoped to a folder—but it never names sibling alternatives such as mendeley_search_library, which should be used for text/content search, or mendeley_get_document for a single document. There is no explicit when-to-use/when-not-to-use guidance, so the agent must infer selection from the verb 'list' 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It indicates a read-oriented listing and adds useful context about hierarchy and authentication, but it does not explicitly state read-only status, pagination behavior, or whether results are flat or nested.

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

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

The description is a single focused sentence with no filler. The key scope information ('authenticated library' and 'parent-child relationships') is front-loaded and every part of the sentence adds value.

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 zero-parameter listing tool with an output schema available, this description is largely complete. It covers the resource, scope, and structural detail, though an explicit note distinguishing it from mendeley_list_documents or stating that it is read-only would make it fully 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?

The tool has zero parameters, so the baseline is 4 and there is no parameter documentation gap. The description reinforces that the listing scope is the entire authenticated library, which is the only relevant semantic needed here.

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

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

The description uses a specific verb ('Return') and a specific resource ('folder and collection structure of the authenticated Mendeley library'). It also adds the key detail of 'parent-child relationships', which clearly differentiates this from document-listing siblings like mendeley_list_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?

The purpose statement implies this is the tool to use when an agent needs folder/collection hierarchy information. However, it does not explicitly name alternatives or state when not to use this tool, leaving sibling differentiation mostly 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?

No annotations exist, so the description carries the full burden of behavioral disclosure. It does disclose the most important behavioral trait — the operation mutates folder membership but is non-destructive to the document itself. However, it does not disclose error behavior (e.g., what happens when the document is not a member of the folder), idempotency, or any permission requirements. The key safety-relevant behavior is covered; other behavioral context is absent.

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 main action comes first ('Remove a document from a folder') and the scope-limiting clarification ('without deleting the document from the library') immediately follows. Every word earns its place; nothing could be trimmed without losing meaning.

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

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

The tool is a simple two-parameter mutation with an output schema, so return-value documentation is not needed. However, with zero annotations, the description omits error conditions (e.g., removing a document that isn't in the folder) and any note about whether the operation is idempotent. These are modest gaps for a tool of this simplicity, but a more complete description would address them.

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 0%, meaning the schema provides only parameter names and titles ('Folder Id', 'Document Id') with no descriptions. The tool description does not compensate: it mentions 'folder' and 'document' generically but never explicitly maps them to folder_id and document_id, nor does it explain the expected format or semantics beyond what the parameter names imply. With such low coverage, the description should carry more explanatory weight.

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 ('remove') + resource ('document from folder') and adds the critical scope distinction 'without deleting the document from the library.' This clearly differentiates it from the sibling mendeley_delete_document, which actually destroys the library record. An agent can tell this tool apart from nearby siblings without inspecting schemas.

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

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

The clarifying clause 'without deleting the document from the library' implies this tool is for folder-organization operations rather than document destruction, but it does not explicitly name alternatives or state when-not-to-use conditions. Usage context is implied rather than stated. No direct comparison to mendeley_delete_document or mendeley_add_document_to_folder 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It does disclose a useful behavioral trait ('return its updated state'), which goes beyond the bare action. However, it does not mention side effects on associated documents, whether the operation is reversible, or any permissions required. For a simple rename, this is adequate but not comprehensive.

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

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

The description is one short, efficient sentence with no filler. The core action is front-loaded, and the behavioral note about returning the updated state is appended cleanly. Every word 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 simple two-parameter rename tool, the description covers the basic operation and return value. However, without annotations or parameter descriptions, it leaves gaps around validation, failure modes, and side effects. An output schema exists, but its contents are not visible to the agent, so this minimal description only partially satisfies what a caller needs to know.

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 0%, so the description should compensate by explaining the parameters. It does not explicitly describe what 'folder_id' and 'name' mean beyond what the schema titles provide. 'Rename an existing folder' weakly implies that folder_id identifies the folder and name is the new name, but no meaningful detail is added for either 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 uses a specific verb ('Rename') and resource ('existing folder'), and clearly distinguishes this tool from its siblings (create, delete, list folders). The added 'return its updated state' clarifies the result. No ambiguity about what the tool does.

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

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

The description implies the use case: when an existing folder needs to be renamed. However, it offers no explicit guidance on when not to use this tool or how it contrasts with sibling tools like create_folder or delete_folder. The uniqueness of the rename operation makes the usage context reasonably clear, but no direct guidance 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?

No annotations are provided, so the description carries the full behavioral burden. It states that the search targets the global catalog rather than the library and explicitly discloses the return payload: catalog identifiers plus summary metadata. It does not discuss auth or rate limits, but those are less critical for a read-only search operation.

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

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

The description is a single, front-loaded sentence with zero filler. It packs in the action, scope, and output shape efficiently.

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

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

With an output schema present and only two simple parameters, the description covers the key semantic context: global catalog scope, not user-library scope, and the kind of result returned. The only notable gap is the lack of an explicit routing distinction against mendeley_search_library.

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 0%, and the description does not compensate by explaining query syntax or limit behavior. The verb 'Search...' loosely implies the query parameter is a text search, but the limit parameter is left entirely to inference from its name and default.

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

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

The description uses a specific verb and resource: 'Search Mendeley's global catalog' and clearly scopes the tool to papers that may not yet exist in the user's library. This also differentiates it from the sibling mendeley_search_library without needing to open any schemas.

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

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

The phrase 'papers that may not yet exist in the user's library' gives clear context for when to use this tool: when searching beyond the user's library. It does not explicitly name mendeley_search_library as the alternative or list exclusion conditions, 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?

With no annotations, the description carries the full burden; it does disclose the searchable fields and the return payload, which is sufficient for a safe read-only search operation. It does not mention pagination behavior, error handling, or whether the search is full-text vs exact-field, but for a non-destructive search tool these are moderate gaps.

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?

One sentence packs the action, scope, search fields, and return value with no filler. The most important information is front-loaded.

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 search tool with an output schema, the description is nearly complete. It could add a sentence about pagination semantics or explicitly point to search_catalog, but nothing essential is missing for the agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does define what can be searched (title, authors, abstract, notes), adding meaning to the query parameter, but it does not explain the limit parameter or its effect. The limit parameter is largely self-explanatory and has a default, so a mid-range score 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 names a specific action ('Search'), a clear scope ('authenticated Mendeley library'), and the relevant fields (title, authors, abstract, notes). It also states what is returned (concise document metadata, citation text, PDF availability), and this scope separates it from sibling search_catalog, which targets the broader catalog.

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 phrase 'authenticated Mendeley library' clearly situates this as the user's library search, as opposed to the catalog-level search. It does not explicitly name search_catalog or enumerate when not to use the tool, but the context is clear enough for an agent to make the basic routing decision.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It usefully states that 'Only supplied fields change', which clarifies the partial-update semantics. However, it does not disclose whether passing null values clears fields, how missing documents are handled, or whether validation rules apply to particular fields—important behavior for a mutation tool.

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

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

The description is two short sentences with no filler. It front-loads the action and resource, then adds the key partial-update behavior. Every clause contributes useful information.

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

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

For a tool with 8 parameters and no annotations or schema descriptions, this description is too thin. It does not address null semantics, nested object formats, missing-document errors, or tie the tool into the overall Mendeley workflow relative to siblings. While an output schema exists, the input-side ambiguity remains unresolved.

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 0%, so the description must compensate for parameter meaning. It lists several field names (title, authors, year, etc.), but it does not explain the expected format for nested structures like 'authors' (array of objects) or 'identifiers' (object of strings), nor does it mention default/null behavior. This leaves significant gaps for an agent trying to construct correct arguments.

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

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

The description clearly states the action ('Update'), the resource ('an existing library document'), and lists the specific fields affected: title, authors, year, source, abstract, or identifiers. This makes it easy to distinguish from sibling tools like mendeley_add_document or mendeley_delete_document without needing to inspect 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 phrase 'on an existing library document' implies the tool is for modifying already-created documents, which is a reasonable usage hint. However, it does not explicitly state when to prefer this over alternatives like mendeley_add_document, nor does it mention any exclusions or preconditions (e.g., whether partial updates are supported when only some fields are supplied).

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