Server Quality Checklist

Tool Scores

• adn_update_collectionC
  2.3/5.0
  Behavior2/5

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

  Annotations already indicate this is a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds no additional behavioral context, such as whether it performs a partial update, what happens to omitted fields, or any side effects. The word 'existing' hints that a missing collection would cause an error, but this is minimal.

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

  Conciseness2/5

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

  The description is a single short sentence, but this is under-specification rather than conciseness. While there is no fluff, the lack of necessary detail means it does not earn its place as a helpful description. It is barely more informative than a tautology.

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

  Completeness1/5

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

  For a tool with seven parameters, a nested object, and no output schema, this description is woefully incomplete. It does not explain return values, error handling, the semantics of partial updates, or how the metadata field is merged. The agent would be left guessing about crucial behavior, making the description inadequate for correct invocation.

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

  Parameters1/5

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

  The schema lists seven parameters, but the description mentions none of them. With 0% schema description coverage, the description provides no semantic insight into the meaning or usage of parameters like `metadata`, `player_color`, or `organization_index`. The field names alone are insufficient for an agent to understand their purpose or how to set them correctly.

  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 'Update an existing collection' clearly specifies the verb (update) and resource (collection), distinguishing it from sibling tools like adn_create_collection and adn_get_collection. However, it lacks any detail about which fields can be updated or any scoping, so it is not as rich as the highest-caliber examples.

  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 gives no guidance on when to use this tool versus alternatives, such as adn_create_collection or adn_list_collections. It does not mention preconditions, when not to use it, or reference any sibling tools. The only implied usage is 'when you already have a collection to modify,' which is trivial and insufficient.

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

• adn_get_play_sessionB
  3.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the word 'existing,' implying it retrieves an already-created session, but offers no additional context about error behavior or return format, adding minimal value 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?

  The description is a single, front-loaded sentence with no filler. It earns a high score for conciseness even though it lacks depth in other dimensions.

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

  Completeness3/5

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

  Given the simple read-only operation with one parameter and strong annotations, the description is minimally adequate but not complete. It doesn't mention what 'details' includes, behavior for invalid IDs, or any prerequisites. However, for a straightforward getter, the missing output schema would normally be the main concern, but without any usage guidance, completeness suffers.

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

  Parameters2/5

  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 semantics. It does not mention play_session_id or how to specify which session, leaving the sole parameter's meaning entirely to the schema. This is a significant gap, though the single parameter name is somewhat self-explanatory.

  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 'Get' and resource 'play session', making its primary function evident. While it doesn't explicitly distinguish from sibling get tools like adn_get_upload_session, the resource name itself provides adequate differentiation.

  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?

  No guidance is provided on when to use this tool versus alternatives. The description only states what the tool does, not the context or situations where it should be preferred over other get tools, so it falls at the 'no guidance' level.

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

• adn_create_collectionB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description adds the conceptual definition but no additional behavioral details such as uniqueness constraints, required permissions, or what happens on success or failure.

  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 a single, focused sentence that front-loads the purpose and avoids waste. It is concise, but the lack of any additional detail means it may be too terse for full usefulness.

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

  Completeness2/5

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

  While it explains what a collection is, it omits parameter guidance, return value expectations, and operational context beyond the basic creation action. With six parameters and no output schema, this description is insufficient for reliable invocation.

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

  Parameters1/5

  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 mention any of the six parameters. The schema provides only names and types, leaving field meanings like metadata, creator_id, player_color, and organization_index completely unexplained.

  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 'Create a new collection' and defines a collection as 'a logical container for tracks, like an album, podcast feed, or course module', which distinguishes it from sibling create tools like create_creator or create_track_in_upload_session. The verb and resource are specific and unambiguous.

  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 as the tool for creating track containers, but it does not explicitly state when to use it versus alternatives or any exclusions. The definition provides context, but no direct guidance on selection among sibling tools.

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

• adn_update_creatorB
  3.3/5.0
  Behavior2/5

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

  Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, but the description adds no behavioral context beyond that. It does not explain whether updates are partial or full, what fields are affected, or what responses look like. With no contradiction but no added value, the score is low.

  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, front-loaded sentence with no wasted words. It is appropriately concise, though under-specified in other dimensions.

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

  Completeness2/5

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

  With three parameters, a nested object, no output schema, and no parameter descriptions, the description is far too sparse. An agent needs to know how to construct a valid update request, what fields can be updated, and what the tool returns. The current description provides almost none of that.

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

  Parameters2/5

  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 by explaining the parameters. It does not mention metadata, creator_id, or organization_index at all. The schema provides names and types, but no semantics, leaving the agent to guess what 'metadata' or 'organization_index' mean for an update.

  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 'Update an existing creator' clearly states the action (update) and resource (creator), and implicitly distinguishes from sibling tools like adn_create_creator, adn_list_creators, and adn_get_creator. The word 'existing' also clarifies that the target must already be present.

  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 verb 'update' implies it should be used when a creator already exists and needs modification, but there is no explicit guidance on when to choose this over alternatives, nor any prerequisites or exclusions. This is implied usage, not explicit guidance.

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

• adn_list_tracksA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to cover safety. The description adds only the scoping phrase 'in a collection,' which overlaps with the schema's collection_id parameter. No additional behavioral context such as pagination, ordering, or return format is disclosed, but annotations mitigate the need.

  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, concise, front-loaded sentence that directly states the action and object. It contains no redundant or extraneous text, achieving high efficiency.

  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?

  For a simple list operation, the description combined with the schema and annotations is largely complete. The verb 'list' implies a return of tracks, and the schema defines the relevant limit/offset pagination parameters. The absence of an output schema is offset by the straightforward nature of the operation, though a brief mention of whether it returns full track objects or summaries would enhance completeness.

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

  Parameters2/5

  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 the lack of parameter documentation. It partially clarifies collection_id via 'in a collection' but gives no information about limit or offset, which are present in the schema but unexplained. This leaves a significant gap in parameter 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 'List tracks in a collection' clearly states a specific action (list) on a specific resource (tracks) with a scope (in a collection). This distinguishes it from sibling tools like adn_list_creators and adn_list_collections, and from the singular adn_get_track.

  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 when the agent needs to list tracks within a specific collection, but it offers no explicit guidance on when to use this tool versus alternatives like adn_get_track for a single track or adn_list_collections for collections. No exclusions or alternative tool references are provided.

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

• adn_get_collectionA
  3.8/5.0
  Behavior2/5

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

  Annotations already disclose that the operation is read-only, idempotent, and non-destructive. The description adds no further behavioral context, such as response format, error handling, or rate limits. It simply restates 'Get details' without enriching beyond the structured fields.

  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, front-loaded sentence with no filler. It conveys the action and target efficiently, earning its place without redundancy.

  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?

  For a simple get-by-ID tool with rich annotations and one clear parameter, the description adequately covers the core purpose. It does not explicitly state what 'details' includes, and there is no output schema, but the essential context is present. Edge cases like 404 behavior are omitted, but not critical for this simplicity level.

  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?

  The only parameter, collection_id, is implicitly referenced by 'by ID', but no additional meaning is provided beyond its name and the schema's uuid format. With 0% schema description coverage, the description minimally compensates by linking the parameter to the resource, but it lacks depth.

  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 a specific verb ('Get') and resource ('collection'), and specifies that it targets a particular collection by ID. This distinguishes it from sibling tools like adn_list_collections (which lists collections) and adn_create_collection/adn_update_collection (which modify).

  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 implies usage for retrieving a single collection when its ID is known, contrasting with collection listing. It does not explicitly mention when not to use it or name alternatives, but the context is clear for a simple get-by-ID operation.

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

• adn_list_collectionsA
  3.9/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. Description adds scope 'on the authenticated AudioDN organization', reinforcing that it's scoped. However, it doesn't mention pagination behavior or return format, so some behavioral traits remain undisclosed. With annotations covering safety, baseline 3.

  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 concise sentences, each earning its place. The first states the core operation, the second provides usage guidance. No redundant words.

  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?

  The tool has no output schema, so the description must convey what it returns. It says 'List collections' which implies a list, but it doesn't explain pagination parameters or result structure. However, the schema defines limit/offset, and the simple nature of the operation means this is a minor gap.

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

  Parameters2/5

  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 mention limit/offset at all. The schema provides min/max but no semantic meaning. The description carries no information about pagination parameters, so it fails to compensate for the schema gap.

  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?

  Uses specific verb 'List' + resource 'collections on the authenticated AudioDN organization', and explicitly distinguishes from create_collection by saying 'before creating a new one.' This clearly differentiates it from sibling 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?

  Provides explicit context: 'Use this to discover existing collections before creating a new one.' This indicates when to use it relative to creation. Doesn't mention alternatives like get_collection, so no full exclusions, but the context is clear.

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

• adn_list_creatorsA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only, idempotent nature is established. The description adds value by specifying the authentication scope ('authenticated AudioDN organization') and clarifying the domain concept, but it does not discuss pagination behavior or rate limits.

  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 only two sentences, with the primary action 'List creators' front-loaded. The second sentence adds a concise definition of 'creator' that is helpful context without introducing verbosity.

  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?

  For a simple list operation with strong annotations, the description sufficiently conveys the core purpose and authentication requirement. It does not explicitly cover pagination behavior or return shape, but the schema already exposes limit/offset parameters, making the description reasonably complete given the tool's simplicity.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description provides no explanation of the 'limit' and 'offset' parameters. The tool description says only 'List creators' and does not compensate for the absence of schema descriptions, leaving the agent without guidance on pagination 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 uses the specific verb 'List' with the resource 'creators' and scopes it to 'the authenticated AudioDN organization', making the operation unambiguous. It also defines 'creator' as a sub-account, clearly distinguishing this list tool from sibling tools like adn_get_creator, adn_create_creator, and adn_update_creator.

  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 conveys that this tool enumerates creators on the authenticated organization, which clearly implies its role among sibling creator tools. However, it does not explicitly mention alternatives or when not to use it, so it stops short of the highest bar.

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

• adn_create_upload_sessionA
  4/5.0
  Behavior4/5

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

  Annotations already indicate this is a mutating, non-destructive operation. The description adds key behavioral context beyond annotations: it does NOT return an upload URL by itself and requires a follow-up call. This is valuable information for the agent to set expectations and plan subsequent actions.

  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 two sentences with no filler. It front-loads the main purpose, then adds the critical caveat and next-step instruction. Every word earns its place.

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

  Completeness3/5

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

  The tool has no output schema and 4 parameters with 0% schema coverage. The description provides essential purpose, return value, and next step, but lacks parameter context and any caveats about session lifecycle. It is adequate for a simple flow but leaves gaps for complex usage.

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

  Parameters2/5

  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 by explaining parameter meanings. It only vaguely references collection_id ('for a collection') and leaves metadata, creator_id, and organization_index completely unexplained. This is a significant gap for a tool with nested objects and optional parameters.

  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 function: 'Create an upload session for a collection' and specifies the return value (upload_session_id). It also distinguishes itself from the sibling tool adn_create_track_in_upload_session by explicitly noting that it does not return an upload URL and pointing to the next step.

  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 contextual guidance by indicating this is the first step in a two-step process and explicitly names the next tool to call (adn_create_track_in_upload_session). It does not explicitly state when not to use the tool, but the context is sufficient for most use cases.

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

• adn_get_guideA
  4/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context: the guide is 'concise' and 'canonical', and limited to 'core' concepts. It does not describe return format or any edge cases, but annotations cover the safety profile, so a 3 is appropriate.

  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 two sentences, with the first stating the action and the second simply listing topics. There is no redundant explanation of the schema or annotations. Every word earns its place, 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 tool's simplicity (one parameter, no output schema), the description is largely complete. It describes the purpose, lists valid topics, and the annotations provide safety and idempotency. The only gap is the lack of explicit return format (e.g., whether the guide is text, markdown), but since it is labeled a 'guide', this is implied and not critical. A 4 reflects the minor missing detail.

  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?

  The schema has one parameter 'topic' with an enum listing the exact topics. The description repeats this list but doesn't explain what each topic means or what a guide entails. The main clause ('Get a concise, canonical guide for a core AudioDN concept') clarifies that topic selects the concept, so some semantics are provided. However, schema coverage is 0%, and the description fails to elaborate on the enum values, making this a marginal compensation.

  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 uses a specific verb 'Get' with a clear resource 'guide' and scope 'for a core AudioDN concept'. It lists the exact topics covered, which distinguishes it from general documentation tools like adn_search_docs. This is a precise and unambiguous statement of purpose.

  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 clearly implies when to use this tool: when you need a guide for one of the listed topics. It does not explicitly mention alternatives or exclusions, but the topic list and the phrase 'core AudioDN concept' provide clear usage context. Since there is no 'when-not' guidance, 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.

• adn_get_upload_sessionA
  4/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, so safety is covered. The description adds useful context with 'authorized by the session ID itself,' implying the ID acts as an authorization token, which is beyond the annotation baseline.

  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?

  A single sentence that is front-loaded with the action and resource, with no filler or redundancy. Every word contributes.

  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?

  For a simple get-by-ID tool with one parameter and read-only annotations, the description is sufficient. It does not explain return values, but the absence of an output schema and the tool's simplicity make this acceptable. The authorization nuance is a valuable addition.

  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?

  The schema describes the parameter as a uuid but lacks semantic detail. The description adds that the ID itself authorizes the request, giving meaning beyond the schema. With only one parameter and 0% coverage, this partial compensation is adequate.

  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 a specific verb ('Get details') and resource ('existing upload session by ID'), distinguishing it from sibling tools that create or update sessions. The authorization note adds a precise scope.

  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?

  Usage is implied: use this when you have an upload session ID and need its details. However, it does not explicitly state when not to use it or reference sibling alternatives like adn_create_upload_session.

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

• adn_create_creatorA
  4.1/5.0
  Behavior4/5

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

  Beyond annotations (readOnlyHint=false), the description adds meaningful context by stating it 'Provisions a dedicated storage folder linked via folder_id', which is a side effect not visible from annotations. It also clarifies organization_index's role.

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

  Conciseness5/5

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

  The three-sentence description is front-loaded with the primary action, defines the core concept, and adds a unique side-effect detail. Every sentence earns its place without unnecessary filler.

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

  Completeness3/5

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

  The description covers the main purpose, a key parameter, and a side effect, but it omits details about the metadata parameter and the exact response structure (no output schema is provided), leaving notable gaps for a creation operation.

  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 coverage is 0%, and the description explains 'organization_index' as an external identifier but leaves the 'metadata' object parameter entirely unaddressed, creating ambiguity about expected keys.

  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 creates a creator and defines creators as 'a sub-account used to classify collections and tracks and track per-creator usage', which distinguishes it from sibling creation tools like create_collection and create_track.

  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 implies when to use the tool by explaining the purpose behind creators, but it does not explicitly name alternatives or when not to use it (e.g., updating an existing creator).

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

• adn_create_track_in_upload_sessionA
  4.1/5.0
  Behavior4/5

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

  Beyond the annotations (readOnly=false, destructive=false), the description reveals important behaviors: the returned upload URL is short-lived and must not be cached, the method is PUT, and a separate cover image target is provided. This adds valuable operational context.

  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?

  Three succinct sentences front-load the primary purpose, then detail return values, required follow-up actions, and a critical caching caveat. No redundancy or filler.

  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 absence of an output schema, the description adequately covers return values (track_id, upload URL, cover image), the upload method, and the short-lived nature of the URL. It misses explanations for optional parameters but covers the core workflow sufficiently for the tool's moderate complexity.

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

  Parameters2/5

  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, but it only indirectly references file_name ('call once per file') and upload_session_id ('existing upload session'). metadata and organization_index are completely unexplained, leaving the agent without guidance for half the parameters.

  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: registering a new track inside an existing upload session, distinguishing it from sibling tools like adn_create_upload_session. It also outlines the result and subsequent upload step, making the tool's role unambiguous.

  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 usage context: it references an existing upload session (implying prerequisite), instructs 'Call once per file,' and explains the follow-up audio upload. It does not explicitly name alternatives or exclusions, but the context is sufficient.

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

• adn_search_docsA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the exact data sources searched (llms-full.txt, OpenAPI operation summaries, guides) and stating that it returns ranked snippets, which goes beyond the annotation baseline.

  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 concise sentences carry the core information without redundancy. The first sentence states the function and sources, the second explains output and recommended usage, all front-loaded.

  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?

  For a moderate-complexity search tool with no output schema, the description covers purpose, usage context, and return format. Minor gaps remain around limit semantics and handling of empty results, but overall it is sufficiently complete.

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

  Parameters2/5

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

  Schema descriptions are absent (0% coverage), so the description must compensate. It clarifies that 'query' is a keyword or phrase, but says nothing about 'limit' beyond the schema's integer constraint, leaving its purpose and effect unstated.

  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 searches the bundled AudioDN documentation for a keyword or phrase, with a specific verb and resource. It distinguishes itself from sibling CRUD tools and other doc lookup tools by being a cross-document search rather than a specific entity operation.

  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 explicitly advises using this tool 'before writing integration code to ground answers in canonical docs,' giving a clear context. It does not mention when not to use it or alternative doc tools like adn_get_guide, so it falls just short of full guidance.

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

• adn_create_play_sessionA
  4.2/5.0
  Behavior4/5

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

  The description adds meaningful behavioral context beyond the basic annotations: it reveals that the tool returns signed, time-gated URLs, implying expiration and authentication. It also discloses the mutual-exclusion requirement and unsupported playlist scope. These details go beyond the readOnly/destructive hints provided in 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?

  The description is two sentences long, with the core purpose and output in the first sentence and critical constraints in the second. Every word serves a purpose, and the structure is front-loaded with essential information.

  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?

  The description covers the essential aspects for use: purpose, output format, ID constraints, and scope limitations. Since there is no output schema, the description adequately describes the return value (signed, time-gated URLs). The primary gap is the unexplained variants parameter, which prevents a perfect score.

  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 0% schema description coverage, the description partially compensates by explaining the mutual-exclusion relationship between scope and collection_id/track_id, which is not enforced by the schema's required fields. However, the variants parameter is entirely unmentioned, leaving a significant gap in 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 uses the specific verb 'mint' with the resource 'play session' and clearly states the output ('signed, time-gated playback URLs'), making the tool's purpose unmistakable. It also distinguishes itself from sibling tools like adn_get_play_session and adn_create_upload_session by focusing on play session creation.

  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 usage context by specifying valid scopes ('collection' or 'track') and the constraint that exactly one of collection_id/track_id must be provided. It explicitly excludes playlist scope as unsupported, giving a clear when-not. It doesn't explicitly name alternative tools, but the context is sufficient for correct selection.

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

• adn_get_creatorA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a clear safety profile. The description adds no additional behavioral context (e.g., auth requirements, rate limits, or side effects), but there is no contradiction.

  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, concise sentence that front-loads the purpose. Every word is necessary, and there is no 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 low complexity (one parameter, no output schema, no nested objects) and strong annotation coverage, the description fully covers what the agent needs to select and invoke the tool correctly. No missing behavioral or usage context is apparent.

  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?

  The schema provides one required parameter, creator_id (uuid), with 0% description coverage. The description mentions 'by ID', which indicates the parameter's role as the identifier, but does not elaborate further. Since there is only one self-explanatory parameter, this minimal guidance is sufficient.

  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 'Get details about a specific creator by ID' clearly states a specific verb (Get), resource (creator), and scope (by ID). It distinguishes from sibling tools like adn_list_creators and adn_update_creator.

  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 clearly implies when to use this tool: when you have a specific creator ID and need its details. It does not explicitly mention alternatives or exclusions, but the usage context is unambiguous for a get-by-ID operation.

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

• adn_list_variantsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by explaining what variants are (org-configured delivery index values) and their role in play sessions/signed URLs, going beyond the annotations without contradicting them.

  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 two sentences with no fluff. It front-loads the core purpose, then provides a clarifying distinction and a pointer to a sibling tool. Every word earns its place.

  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?

  For a simple list tool, the description is nearly complete: it explains the domain concept, scoping, and relationship to variants. It doesn't describe the return format or pagination behavior, but given the lack of output schema and the simplicity, this is a minor gap.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description was expected to compensate. It does not mention the 'limit' and 'offset' pagination parameters at all. While these are conventional, the description adds no meaning beyond the bare schema names and ranges.

  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 lists 'variant configurations' on the authenticated organization, using a specific verb and resource. It also distinguishes these from 'the underlying variant type' and points to adn_list_variant_types, making the purpose unambiguous and differentiated from siblings.

  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 explicitly tells users that these are delivery index values used in play sessions and signed URLs, and directs them to 'adn_list_variant_types for the type catalog' as an alternative. This provides clear when-to-use guidance and names the alternative, satisfying the highest bar.

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

• adn_aboutA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this by framing the action as 'Report.' The description adds value by explaining the docs-source distinction (bundled snapshot vs live) and the purpose of checking freshness, which annotations do not convey.

  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 two sentences, front-loaded with the action and content, and the second sentence provides a clear use case. Every word earns its place with no redundancy or filler.

  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?

  The tool is simple (no params, no output schema), and the description fully covers its purpose, return content, and intended use. Annotations cover the safety profile, and the description's freshness-check guidance completes the picture.

  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?

  The tool has zero parameters, and the schema is empty, so parameter documentation is unnecessary. The description focuses on output semantics instead, which is appropriate for a parameterless tool.

  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 specifies a concrete verb ('Report') and enumerates the exact resources returned (MCP server version, OpenAPI version, docs source, API base URL). This is clearly differentiated from sibling tools, which focus on creators, collections, tracks, and other domain objects.

  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 explicitly states when to use the tool: 'Use this to confirm how fresh the grounded documentation is.' It does not name alternatives or exclusions, but for an 'about' tool in a server with many data-operation siblings, this context is sufficient.

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

• adn_get_trackA
  4.5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds valuable behavioral context by explaining terminal vs transitional statuses and the condition for playability. This goes beyond structured fields and prevents misuse, fully earning credit.

  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?

  Three sentences, front-loaded with purpose, then compact usage guidance. Every sentence adds unique value—no fluff, clear structure, and easily scannable.

  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?

  The tool is simple (one param, no output schema) and richly annotated. The description covers the core use case (polling readiness), explains relevant statuses and their implications, and warns against premature playback. This is complete for an AI agent selecting the tool.

  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 coverage is 0%, so the description must compensate. It confirms the parameter is a track ID and implies its use for lookup, but does not add detail beyond the schema's track_id name and uuid format. Given the single simple parameter, this is acceptable but not enriching.

  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 fetches details for a specific track by ID, using a specific verb ('Get details') and resource. It distinguishes itself from sibling tools like adn_list_tracks by focusing on a single track and adding the unique polling/status readiness use case.

  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 explicitly says 'Use this to poll processing readiness,' giving a clear when-to-use context. It also provides a behavioral guardrail with 'Do not build playback until a track is ready.' However, it does not explicitly name alternatives or exclusions (e.g., when to use list_tracks instead), so it stops short of a full 5.

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

• adn_list_operationsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds behavioral context by noting the data comes from the bundled OpenAPI spec, implying a deterministic, locale, side-effect-free listing, and specifies exactly what fields will be returned.

  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 compact sentences: the first states the action, source, and output fields; the second gives a clear usage rationale. Every word earns its place, with no redundancy or filler.

  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?

  For a simple, zero-parameter tool with no output schema, the description is very complete: it names the source, the full content type, and the intended use case. No additional behavioral or return-value details are needed.

  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?

  The tool has zero parameters, so the schema is trivially complete. The description correctly implies no inputs are needed. The baseline score for 0 params is 4, and nothing in the description detracts from this.

  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 opens with 'List every AudioDN REST API operation' - a specific verb and resource - and elaborates that it pulls from the bundled OpenAPI spec, enumerating the exact fields (operationId, method, path, summary). This clearly distinguishes it from sibling tools that list concrete entities like creators or collections.

  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 phrase 'Use this to discover the exact, canonical endpoints instead of guessing' provides a clear when-to-use context and a rationale. It does not explicitly name alternative tools or exclusions, but the usage intent is unambiguous.

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

• adn_get_operationA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by detailing exactly what the returned definition contains (method, path, parameters, request body, responses), which goes beyond simple read-only scoping and tells the agent what to expect in the response.

  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, front-loaded with the main purpose and followed by a useful pointer to a sibling tool. No filler or repetition of annotations; every word adds value.

  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?

  For a single-parameter read-only metadata retrieval tool, the description is complete: it states the input, explains how to obtain it, and enumerates the response contents. No output schema exists, but the description covers what is returned. Annotations cover safety, so all key aspects are addressed.

  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?

  Schema coverage is 0% but the description compensates by clearly stating the operationId is the identifier of the operation to retrieve, and even tells how to find valid operationIds via adn_list_operations. With only one parameter, this provides sufficient semantic meaning beyond the schema's name and type.

  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 gets the full OpenAPI definition for a single operation by operationId, listing contents (method, path, parameters, request body, responses). This specific verb+resource distinguishes it from siblings like adn_list_operations and adn_get_guide.

  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 explicitly says to use adn_list_operations to find operationIds, giving a clear when-to-use instruction and naming the sibling tool for discovery. This is more than implied usage; it directs the agent to the correct prerequisite step.

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

• adn_list_variant_typesA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safe read-only nature is covered. The description adds valuable behavioral context by specifying that it includes descriptions and 'whether each can be created via the REST API', and clarifies the distinction from index values, which is beyond what the annotations alone 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 two sentences, front-loaded with the action and resource ('List the AudioDN variant types'), then gives the specific payload and usage guidance. Every word earns its place—no filler, no repetition of the title or name.

  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?

  For a parameterless, informational listing tool with strong annotations and no output schema, the description is complete: it states what is listed, provides the list of types, mentions the creation-capability detail, and gives usage context with a pointer to the sibling. There are no open questions about invocation or expected behavior.

  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?

  The tool has zero parameters, and the schema shows an empty object. The baseline for 0 params is 4, and the description does not need to explain parameters. It also implies no input is required, so no additional semantic burden is placed on the description.

  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 'List the AudioDN variant types' and enumerates them: 'transcode, preview, levels, waveform_video, waveform_image, original, cover'. It also distinguishes from the sibling tool adn_list_variants by mentioning 'org delivery "index" values', making its purpose specific and non-overlapping.

  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?

  Explicit guidance is given: 'Use this to distinguish variant types from org delivery "index" values' and directly references the alternative tool 'see adn_list_variants'. This tells the agent exactly when to choose this tool and when to use the sibling.

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