Server Quality Checklist

Tool Scores

• ads_resolve_linksB
  3.4/5.0
  Behavior3/5

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

  Annotations indicate this is a read-only, non-destructive operation, which the description does not contradict. The description adds value by specifying the types of links resolved (e.g., 'full text, data, citations'), but does not disclose additional behavioral traits like rate limits, authentication needs, or response format details beyond what annotations provide.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that directly states the tool's purpose with relevant examples. It is front-loaded and wastes no words, making it easy to understand quickly without unnecessary elaboration.

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

  Completeness4/5

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

  Given the tool's moderate complexity, rich annotations (read-only, non-destructive), and the presence of an output schema, the description is reasonably complete. It covers the core functionality and link types, though it could benefit from more usage context or behavioral details to fully compensate for the lack of explicit guidelines.

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

  Parameters3/5

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

  With 100% schema description coverage, the input schema fully documents both parameters ('bibcode' and 'link_type'), including their purposes and default behavior. The description adds minimal semantic context by listing examples of link types ('full text, data, citations, etc.'), but does not provide significant additional meaning beyond the schema, aligning with the baseline score for high coverage.

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

  Purpose4/5

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

  The description clearly states the verb ('Resolve') and resource ('available links for a paper') with specific examples of link types ('full text, data, citations, etc.'). However, it does not explicitly differentiate this tool from sibling tools like 'ads_resolve_reference', which might handle similar resolution tasks, leaving some ambiguity about when to use one over the other.

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

  Usage Guidelines2/5

  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 alternatives, such as sibling tools like 'ads_resolve_reference' or 'ads_search'. It lacks explicit context, prerequisites, or exclusions, offering only a basic functional statement without usage scenarios.

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

• ads_networkA
  3.6/5.0
  Behavior3/5

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

  Annotations indicate readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds behavioral context by explaining what each network type does (e.g., 'Groups authors who frequently co-author together'), which goes beyond annotations. However, it doesn't disclose details like rate limits, output format, or computational requirements.

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

  Conciseness5/5

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

  The description is front-loaded with a clear purpose statement, followed by bullet points that efficiently explain the two network types. Every sentence earns its place with no wasted words, making it easy to scan and understand quickly.

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

  Completeness4/5

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

  Given the tool's moderate complexity, rich annotations (read-only, non-destructive), and the presence of an output schema, the description is reasonably complete. It covers the core functionality and parameter semantics well. However, it could benefit from mentioning sibling tools or use-case examples to enhance contextual understanding.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for 'bibcodes' and 'type' parameters. The description adds value by explaining the semantics of the 'type' parameter options: 'author' groups co-authors, and 'paper' clusters by shared references. This enhances understanding beyond the schema's enum list, but doesn't provide additional details for 'bibcodes'.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Generate a collaboration or citation network from a set of papers.' It specifies the verb 'generate' and resource 'network,' and distinguishes between two network types. However, it doesn't explicitly differentiate from sibling tools like ads_search or ads_metrics, which might also involve paper analysis.

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

  Usage Guidelines3/5

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

  The description implies usage by listing two network types: 'author' for collaboration groups and 'paper' for citation clusters. This provides some context on when to choose each type, but it doesn't explicitly state when to use this tool versus alternatives like ads_search for finding papers or ads_metrics for analysis. No exclusions or prerequisites are mentioned.

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

• ads_bigqueryA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context beyond annotations: it specifies a limit ('Provide up to 2000 bibcodes at once'), which is a rate limit or constraint not covered by annotations. It also implies the tool returns metadata (e.g., for 'retrieving metadata'), though this is partially covered by the output schema. No contradictions with annotations are present.

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

  Conciseness5/5

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

  The description is highly concise and well-structured: three sentences that are front-loaded with the core purpose, followed by usage context and a key constraint. Every sentence adds value—no wasted words or redundancy. It efficiently communicates essential information without unnecessary detail.

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

  Completeness4/5

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

  Given the tool's complexity (5 parameters, one required), rich annotations (readOnlyHint, destructiveHint), and the presence of an output schema, the description is mostly complete. It covers the purpose, usage context, and a key constraint (2000 bibcode limit). However, it could be more complete by explicitly differentiating from sibling tools or detailing error cases, but the annotations and output schema reduce the burden on the description. The description adequately supplements the structured data for effective tool selection.

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

  Parameters3/5

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

  Schema description coverage is 100%, meaning the input schema fully documents all parameters (bibcodes, query, fields, sort, rows). The description adds minimal parameter semantics beyond the schema: it mentions 'bibcodes' in the context but doesn't explain their format or source, and it implies the tool handles 'filtering, sorting, or retrieving metadata,' which aligns with the query, sort, and fields parameters. Given the high schema coverage, a baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Search within a specific set of bibcodes (big-query)' and 'Useful for filtering, sorting, or retrieving metadata for a known set of papers.' This specifies the verb (search), resource (bibcodes/papers), and scope (within a known set). However, it doesn't explicitly differentiate from sibling tools like 'ads_search' or 'ads_object_search' beyond mentioning 'big-query' and 'known set of papers.'

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

  Usage Guidelines3/5

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

  The description provides some implied usage context: 'Useful for filtering, sorting, or retrieving metadata for a known set of papers.' This suggests it's for when you already have bibcodes. However, it doesn't explicitly state when to use this tool versus alternatives like 'ads_search' (which might search the full database) or other siblings, nor does it mention any exclusions or prerequisites beyond the bibcodes requirement.

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

• ads_metricsA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds useful context about the return values (specific metrics and histograms) and the bibcode limit (~2000), which helps set expectations beyond the annotations. However, it does not detail rate limits, auth needs, or error handling.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by return details and scope. Both sentences are essential: the first defines the action and output, the second adds critical constraints. There is no wasted text, making it highly efficient.

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

  Completeness4/5

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

  Given the complexity (2 parameters, 100% schema coverage, output schema exists, annotations provided), the description is mostly complete. It explains what the tool does, what it returns, and operational limits. However, it could benefit from more explicit usage guidelines relative to siblings, but the output schema reduces the need to detail return values.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for both parameters (bibcodes and types). The description adds minimal value beyond the schema, as it does not explain parameter interactions or provide additional semantics. With high schema coverage, the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the verb 'compute' and resource 'citation metrics for a set of papers', specifying what metrics are returned (h-index, g-index, etc.) and the scope (1 to ~2000 bibcodes). It distinguishes from siblings like ads_search or ads_bigquery by focusing specifically on metric computation rather than searching, querying, or exporting.

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

  Usage Guidelines3/5

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

  The description implies usage for computing citation metrics given bibcodes, but does not explicitly state when to use this tool versus alternatives like ads_citation_helper or ads_search. It provides a scope (1-2000 bibcodes) but lacks explicit guidance on prerequisites or exclusions.

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

• ads_library_documentsA
  3.9/5.0
  Behavior4/5

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

  Annotations indicate this is not read-only and not destructive, but the description adds valuable behavioral context beyond this. It clarifies that 'empty' action clears a library and that note operations work on individual papers. However, it doesn't mention rate limits, authentication requirements, or what happens with conflicting operations.

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

  Conciseness4/5

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

  The description is well-structured with clear categorization (document actions vs note actions) and bullet points for readability. It's appropriately sized for a multi-function tool, though the bullet format could be more concise. Every sentence earns its place by clarifying the tool's scope.

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

  Completeness4/5

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

  Given the tool's complexity (11 actions across two domains), the description provides good coverage of what the tool does. With annotations covering safety aspects and an output schema presumably handling return values, the description focuses appropriately on functional scope. It could benefit from more guidance about action selection and prerequisites.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema already documents all 6 parameters thoroughly. The description adds minimal value beyond the schema by grouping actions into document vs note categories, but doesn't provide additional semantic context about parameter usage, dependencies, or edge cases.

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

  Purpose5/5

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

  The description clearly states the tool's purpose as managing documents and notes within an ADS library, with specific actions listed for both document handling (add/remove bibcodes, set operations) and note management (get, add, edit, delete). It distinguishes itself from sibling tools like ads_library by focusing on document/note operations rather than general library management.

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

  Usage Guidelines3/5

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

  The description provides implied usage guidance by categorizing actions into document actions and note actions, but doesn't explicitly state when to use this tool versus alternatives like ads_library or ads_search. It lists available operations but doesn't provide context about when each action is appropriate or what prerequisites might exist.

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

• ads_citation_helperA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds behavioral context by specifying that it returns 'papers that are frequently co-cited' and excludes those 'not yet included,' which clarifies the recommendation logic. However, it lacks details on rate limits, response format, or potential errors, leaving some behavioral aspects uncovered.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence and follows with a clarifying second sentence. Every sentence earns its place by defining the input, output, and logic without redundancy. It is appropriately sized, avoiding unnecessary details while being fully informative for the tool's scope.

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

  Completeness4/5

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

  Given the tool's moderate complexity (citation recommendation based on co-citation), annotations cover safety, schema covers the single parameter, and an output schema exists (though not detailed here). The description adequately explains the tool's function and logic. However, it could be more complete by hinting at output structure or usage constraints, but the presence of an output schema reduces the need for such details, making it nearly sufficient.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the parameter 'bibcodes' fully documented in the schema as 'List of bibcodes already in the bibliography.' The description reinforces this by mentioning 'a set of bibcodes (e.g. from a paper's bibliography),' adding minimal semantic value beyond the schema. Since coverage is high, the baseline score of 3 is appropriate, as the description does not significantly enhance parameter understanding.

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

  Purpose5/5

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

  The description clearly states the specific verb ('suggest papers that should be cited') and resource ('papers'), and distinguishes it from siblings by focusing on citation recommendations rather than search, export, or metrics. It explicitly defines the input as 'a set of bibcodes (e.g. from a paper's bibliography)' and the output as 'papers that are frequently co-cited with the input set but are not yet included,' making the purpose distinct and well-specified.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool: 'Given a set of bibcodes (e.g. from a paper's bibliography),' implying it's for enhancing bibliographies. However, it does not explicitly state when not to use it or name alternatives among sibling tools (e.g., ads_search for general paper discovery), which limits guidance on tool selection in broader workflows.

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

• ads_exportA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, establishing safety. The description adds valuable behavioral context by specifying the return type ('formatted citation text') and listing 18+ supported formats, which helps agents understand output expectations beyond 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.

  Conciseness5/5

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

  Two sentences with zero waste: first states purpose and scope, second lists formats and return type. Well-structured and appropriately sized for the tool's complexity.

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

  Completeness5/5

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

  Given the presence of annotations (readOnly, non-destructive), 100% schema coverage, and an output schema (implied by context signals), the description provides complete contextual information. It covers purpose, formats, and return type without needing to duplicate structured data.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents all parameters. The description doesn't add parameter-specific semantics beyond what's in the schema, so it meets the baseline of 3 without compensating for gaps.

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

  Purpose5/5

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

  The description clearly states the verb ('Export') and resource ('paper records') with specific scope ('in various citation formats'). It distinguishes from siblings by focusing on citation export rather than search, metrics, or other functions mentioned in the sibling list.

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

  Usage Guidelines3/5

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

  The description implies usage context by listing supported formats, but doesn't explicitly state when to use this tool versus alternatives like ads_citation_helper or ads_search. No guidance on prerequisites or exclusions is provided.

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

• ads_resolve_referenceA
  4.1/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful context about the tool's matching behavior ('attempts to match') and its utility for partial citations, but does not provide additional behavioral details like rate limits or error handling.

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

  Conciseness5/5

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

  The description is appropriately sized and front-loaded, with two concise sentences that efficiently convey the tool's purpose and usage without any wasted words or redundancy.

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

  Completeness5/5

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

  Given the tool's moderate complexity, high schema coverage, presence of annotations, and existence of an output schema, the description is complete enough. It effectively explains what the tool does and when to use it, without needing to detail return values or parameters.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents the 'references' parameter. The description adds marginal value by clarifying the parameter's purpose ('free-text reference strings') and providing an example, but does not go beyond what the schema provides in terms of semantics.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('Resolve') and resource ('free-text reference strings to ADS bibcodes'), and distinguishes it from siblings by specifying it's for matching human-readable reference strings to records, unlike general search or citation tools.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use this tool ('Accepts human-readable reference strings and attempts to match them to records in ADS'), but does not explicitly state when not to use it or name specific alternatives among the sibling tools.

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

• ads_object_searchA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds valuable context beyond this by specifying the translation mechanism ('via SIMBAD/NED') and the output format ('an ADS query'), which helps the agent understand the tool's behavior and expected results.

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

  Conciseness5/5

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

  The description is efficiently structured in two sentences: the first states the core purpose, and the second provides usage instructions with examples. Every sentence adds essential information without redundancy, making it easy to parse and understand quickly.

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

  Completeness5/5

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

  Given the tool's low complexity (1 parameter, 100% schema coverage), the presence of annotations covering safety, and an output schema (implied by 'Has output schema: true'), the description is complete. It adequately explains the tool's purpose, usage, and context without needing to detail parameters or return values, which are handled elsewhere.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the schema fully documenting the 'identifiers' parameter as a list of astronomical object identifiers. The description adds minimal semantic value beyond the schema, only implying that identifiers like 'M31' or 'Crab Nebula' are valid, which aligns with the schema's examples.

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

  Purpose5/5

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

  The description clearly states the specific action ('Translate astronomical object names to ADS search queries via SIMBAD/NED') and the resource ('astronomical object names'). It distinguishes this tool from sibling tools like 'ads_search' by specifying it's for object name translation rather than general searching.

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

  Usage Guidelines4/5

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

  The description provides clear context about when to use this tool ('Provide object identifiers... and get back an ADS query that matches papers about those objects'). However, it doesn't explicitly state when not to use it or name specific alternatives among the sibling tools, such as when to use 'ads_search' instead.

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

• ads_searchA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, establishing this as a safe read operation. The description adds valuable behavioral context beyond annotations by explaining the query syntax capabilities, providing concrete query patterns, and detailing functional operators like citations(), references(), trending(), etc. This helps the agent understand how to construct effective queries.

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

  Conciseness5/5

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

  The description is efficiently structured with clear sections: purpose statement, syntax explanation, common patterns, specialized functions, and additional operators. Every sentence earns its place by providing specific, actionable information without redundancy. It's appropriately sized for a complex search tool.

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

  Completeness5/5

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

  Given the tool's complexity (search with multiple parameters and rich query syntax), the description provides excellent context about capabilities and usage patterns. With annotations covering safety, 100% schema coverage documenting parameters, and an output schema existing (though not shown), the description focuses appropriately on explaining the search functionality and query construction.

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

  Parameters3/5

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

  With 100% schema description coverage, the input schema already fully documents all 5 parameters. The description doesn't add any parameter-specific information beyond what's in the schema. However, it provides context about query construction that indirectly relates to the 'query' parameter. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Search the NASA ADS database' with specific verb ('Search') and resource ('NASA ADS database'). It distinguishes from siblings by focusing on general search functionality rather than specialized operations like citation analysis (ads_citation_helper), metrics (ads_metrics), or object search (ads_object_search).

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

  Usage Guidelines4/5

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

  The description provides clear context about when to use this tool by explaining it 'Supports the full ADS query syntax' and giving specific examples for different search patterns. However, it doesn't explicitly state when NOT to use it or directly compare it to sibling tools like ads_object_search or ads_citation_helper for specialized tasks.

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

• ads_libraryA
  4.7/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond the annotations. While annotations indicate this isn't read-only or destructive overall, the description clarifies that the 'delete' action is 'permanently delete' and specifies which actions require which parameters. It also mentions that 'get' returns both details and bibcodes, providing useful implementation context that annotations don't cover.

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

  Conciseness5/5

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

  The description is perfectly structured and concise. It starts with a clear purpose statement, then uses a bulleted list format to efficiently present each action with its requirements. Every sentence earns its place, with zero wasted words or redundant information.

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

  Completeness5/5

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

  Given the tool's complexity (8 parameters, 5 actions), the description provides complete guidance. With annotations covering safety aspects, an output schema presumably handling return values, and the description clearly explaining action selection and parameter requirements, there are no significant gaps. The description appropriately focuses on what the agent needs to know to select and invoke the tool correctly.

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

  Parameters4/5

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

  With 100% schema description coverage, the baseline would be 3, but the description adds meaningful context by grouping parameters with actions. It clarifies that library_id is required for get/edit/delete, name is required for create, and description/public are optional for create/edit. This action-parameter mapping provides semantic value beyond the individual parameter descriptions in the schema.

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

  Purpose5/5

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

  The description clearly states the tool's purpose as managing ADS libraries (saved paper collections) and lists five specific actions with their required parameters. It distinguishes this tool from siblings like ads_search or ads_export by focusing specifically on library management rather than searching, exporting, or other functions.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use each action (list all libraries, get details with library_id, create with name, edit with library_id, delete with library_id) and includes parameter requirements. It clearly differentiates between actions that require library_id versus those that don't, giving the agent clear decision criteria.

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