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

With no annotations, the description carries full burden and meets it: it exposes the CLI mechanism, duplicate detection, the possibility of a user accept prompt, the fact that the .bib file is not modified by the server, and that success means dispatch only, not persistence. This discloses side-effect and reliability semantics that annotations would otherwise hide.

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 front-loaded with the one-line purpose, then uses labelled sections (Args, Returns, Workflow) and bullets for behavioral caveats. Although long, the length is justified because the tool has asynchronous, user-interactive behavior that cannot be safely summarized in one line.

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 mutation-like tool with no annotations and an important asynchronous caveat, the description covers prerequisites, invocation semantics, return meaning, post-call workflow, verification strategy, and even restart behavior. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 0%, so the schema alone gives no meaning. The description compensates by defining bibtex as 'a complete BibTeX entry' with a concrete example, and by explaining timeout as 'optional override of the import timeout in seconds'. Both parameters are semantically fully specified.

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 + resource: 'Add a new entry to the JabRef library', and adds 'the ONLY supported way of adding entries', which differentiates it from all sibling tools that either read or search entries. There is 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?

It states a hard prerequisite ('JabRef must be running with Listen to remote operation on port enabled'), and notes that this is the only supported add path, so there is no alternative tool to choose. The post-dispatch workflow also tells the agent when to verify via search and when to ask the user to save, which is precise usage guidance.

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns complete BibTeX and resolved attached files, and explicitly mentions error behavior for missing keys. This goes beyond a bare 'get' statement, though it doesn't detail error types or side effects (unlikely for a read 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?

Two sentences, front-loaded with the action and output, followed by the error condition. Every word adds value; no fluff 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?

For a simple one-parameter read tool with an output schema, the description covers the essential behaviors: what it returns, why it's needed, and failure mode. It doesn't mention prerequisites like prior list_entries usage, but that is not implied by the tool signature and can be inferred from the citation key 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 0%, so the description must explain the single parameter. It explains that citation_key identifies a single citation and that the tool errors if that key does not exist, adding meaning beyond the bare string type. A format example or source hint would be extra, but with one parameter this is sufficient.

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 'Get the full record for one citation key' with specific output content ('complete BibTeX plus the resolved attached files'), which distinguishes it from siblings like list_entries or get_pdf. It also provides a specific use case ('needed for summarization'), making the tool's role immediately 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?

It gives a clear context for when to use this tool ('needed for summarization') and states the error condition ('Raises an error if the key does not exist'). However, it does not explicitly name alternatives or say when NOT to use it, so it falls 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 provided, the description carries the full burden of behavioral disclosure. It explicitly states that only existing files are returned and that a key with no PDF raises an error. It does not mention side effects (none expected) or auth, but the read-only nature is implied. This adds meaningful context beyond the schema.

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

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

Two sentences with zero wasted words. The core purpose and key behavioral constraints (only existing files, error on missing PDF) are front-loaded, making it easy for the agent to scan and understand.

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 (one parameter, no nested objects) and the output schema exists (though not shown). The description covers the return type and error behavior. It does not mention edge cases like invalid citation_key or what happens if the entry itself doesn't exist, but these are minor given the straightforward nature. The description is sufficient for correct invocation.

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 one parameter (citation_key) with 0% description coverage, so the description must compensate. However, it only refers to 'an entry' without explaining what citation_key is or its expected format. The description does not clarify that citation_key is the identifier used to locate the entry, leaving ambiguity for the agent.

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 ('Return'), the resource ('absolute file paths of the PDFs attached to an entry'), and the intended purpose ('so the assistant can read and summarize them'). It is specific and distinct from sibling tools like get_entry or search, which focus on metadata or text.

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 usage when PDFs need to be accessed for reading/summarizing, but it does not explicitly mention when not to use this tool or compare it to alternatives. There is no mention of other tools like get_entry for retrieving entry metadata or search for finding entries.

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. It discloses the fields returned, which is useful behavioral information. However, it does not mention the effect of the limit parameter, pagination, ordering, or any other behavioral aspects such as whether it returns all entries by default or only a subset. The description is a minimal disclosure of the tool's behavior.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, then lists the relevant fields and a usage note. Every word earns its place with no redundancy or fluff.

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 (one optional parameter) and has an output schema, so the description need not explain return values in depth. However, it omits any mention of the limit parameter's behavior or whether the list is truncated, which is a key operational detail. The usage context is helpful but incomplete without describing how the limit affects results.

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

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

Schema description coverage is 0% for the single parameter 'limit', and the description does not mention it at all. The description provides no additional meaning about what 'limit' controls (e.g., maximum number of entries). With no compensation from the description, the agent receives no guidance on this parameter beyond its name and default value.

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 verb ('List') and resource ('entries in the JabRef library') and enumerates the returned fields (citation key, authors, year, title, venue, DOI). It differentiates from siblings: list_libraries lists libraries, get_entry fetches a single entry, search is for querying, get_pdf and add_entry are unrelated. The added 'most useful for getting an overview or picking citation keys' further clarifies intent.

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 clear usage context: 'most useful for getting an overview or picking citation keys.' This implies when to use it (for overview or selection) but does not explicitly state when not to use it or mention alternatives like search or get_entry. It gives clear context without exclusions, fitting a score of 4.

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 accurately conveys a read-only listing operation and mentions the output cardinality (count of entries per library). It does not disclose any side effects, but 'list' implies no mutation. It could explicitly say it is non-destructive, but the nature of a list operation makes that self-evident, and no permissions or rate limits are relevant for a simple read. The transparency is adequate.

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 states exactly what the tool does and what it returns. No filler or repetition—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?

The tool is simple: no parameters, a clear purpose, and an output schema (provided as structured data). The description fully covers the operation and necessary context. There is nothing an agent needs to know that isn't already explained.

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 schema is empty. Per rubric, 0 params gives a baseline of 4. The description adds no parameter details because none exist; it is fully consistent with the schema.

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

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

The description states a specific action ('List') and a precise resource ('configured JabRef libraries') plus the output detail (number of parsed entries). It clearly distinguishes itself from siblings like list_entries (lists entries), get_entry (fetches one), search (queries), get_pdf (retrieves files), and add_entry (mutates). No ambiguity.

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 explains what the tool does but does not explicitly state when to use it over alternatives or when not to use it. Although the sibling tool names make the differentiation obvious, there is no direct guidance such as 'Use this to see all libraries; for entries within a library use list_entries.' A clear context but no exclusions or explicit routing.

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 explains search semantics: AND logic, case-insensitivity, field restriction, substring matching for author/tag, inclusive year ranges, and the limit behavior. However, it does not mention result ordering, pagination, or potential side effects (though search is inherently read-only). The disclosed details are substantive and go beyond a simple 'searches library'.

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 well-structured: a one-line summary with the return format, followed by a concise Args list. Each parameter gets a clear explanation without wasted words. The information is front-loaded, and the structure makes 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 description covers the purpose, return format, and all parameter semantics, which is sufficient for a search tool. It lacks explicit notes on ordering, pagination, or error behavior, but these are not critical for basic usage. The presence of an output schema reduces the need to describe return structure, though the description already provides it. Overall, the description is complete for the tool's complexity.

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 has 0% description coverage, so the description must compensate. It does so comprehensively, explaining each parameter's purpose and behavior: query terms (space-separated, AND), field restriction, author substring, exact year, year range, tag substring, and limit (0 = no limit). This adds significant meaning beyond the raw schema types and defaults.

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 it searches the JabRef library and returns matching entries with a specific output format. The verb 'Search' and the resource 'JabRef library' are explicit, and the mention of returning matching entries distinguishes it from listing or fetching a single entry.

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 no guidance on when to use this tool versus the sibling tools like list_entries or get_entry. It does not mention alternatives or conditions that would favor one over another, leaving the agent to infer usage from the parameters alone.

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