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

Annotations already establish read-only, idempotent, open-world behavior, so the description only needs to add context. It adds that browse returns the complete paged set rather than a ranked subset, highlights paging limits, and notes the data source. It doesn't cover rate limits or error behavior, but the key behavioral trait—deterministic complete relationships—is disclosed.

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

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

The description is a compact two-sentence definition with no fluff. The core action and examples are front-loaded, followed by the search distinction, paging usage, and data provenance. Every sentence contributes to selection or invocation.

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

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

For a 7-parameter read-only tool with full schema coverage and no output schema, the description provides enough context for an agent to select and call it: purpose, examples, paging, read-only nature, and data source. It doesn't describe response shape in detail, but the absence of an output schema makes that less critical for invocation.

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

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

Schema covers 100% of parameters, so baseline is 3. The description goes beyond the schema by providing a concrete parameter mapping example (entity: 'release', linkedBy: 'artist', mbid: <artist>) and explaining that inc adds detail and limit/offset page. This clarifies how the three required parameters interrelate.

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

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

The description opens with specific verb and resource: 'List all entities of one type directly linked to a given entity', including concrete examples like 'every release by an artist' and 'recordings on a release'. It clearly distinguishes this from musicbrainz_search, which 'ranks fuzzy matches', making the tool's unique role unambiguous.

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

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

It explicitly says this is the 'complete, paged set for a relationship' and contrasts with 'search, which ranks fuzzy matches', telling the agent when to prefer browse over search. It also gives direct operational guidance: 'Use inc for extra detail and limit/offset to page (max 100/page).'

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds meaningful behavior beyond those: it returns URLs, does not embed image bytes, and errors clearly when no art exists. This gives the agent expectations about side effects, return content, and failure mode without contradicting any annotation.

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

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

Three tight sentences put the core purpose first, then the return behavior, error condition, and read-only nature. The source attribution at the end is brief and unobtrusive. Nothing is redundant or padded.

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

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

With only two parameters, rich annotations, and no output schema, the description covers what the agent needs: what the tool fetches, what it returns, what it does not return, error behavior, and data provenance. This is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents mbid and entity with types, enums, patterns, and descriptions. The description reinforces that the entity can be release or release-group and that the MBID keys the cover art, but it does not add significant meaning beyond what the input schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Fetch Cover Art Archive image metadata for a release or release-group MBID.' It enumerates the concrete outputs (front/back URLs, thumbnails, image types), which clearly differentiates it from the lookup/search/browse siblings.

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

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

The description makes the intended use clear: you need a release or release-group MBID and you will get cover art metadata. It also warns that an error occurs when no art exists, which is a useful boundary condition. It does not explicitly name alternative tools or state when not to use it, but the resource is distinct enough that this is a minor gap.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds behavioral detail beyond this: it performs a lookup on a stable entity, verifies User-Agent acceptance, and reports on the OAuth write path. It also explicitly includes 'Read-only', reinforcing 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.

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

The description is two sentences with no wasted words. The primary purpose is front-loaded, and the return shape and read-only nature are stated efficiently. Every clause adds meaningful information.

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

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

For a zero-parameter, no-output-schema health check, the description is complete. It explains what the tool verifies, what it returns, and its safety profile. An agent can invoke it without any inputs and interpret the result correctly from the described fields and hint.

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

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

The tool has zero parameters, and the input schema is empty, so there is no parameter semantics burden. The description usefully explains what the tool reports (ok, reachable, oauth_configured) and that a plain-English hint is included, which is sufficient for a no-argument health check.

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

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

The description clearly states the tool's function: confirm MusicBrainz API reachability and User-Agent acceptance, and report whether the OAuth write path is configured. This is a specific verb+resource combination that distinguishes it from sibling tools that perform lookups, searches, or submissions.

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

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

The description gives clear context for when to use it: to verify connectivity and OAuth configuration before or alongside other MusicBrainz operations. It does not explicitly name alternatives or exclusions, but the health-check purpose is self-evident and distinct from all listed siblings, so no further disambiguation is needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond that, such as how `inc` affects the response and that data originates from MusicBrainz. It does not contradict the annotations and provides enough added detail for a safe read-only operation.

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

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

The description is compact: two sentences, one focused purpose statement and one guidance sentence on `inc`. It front-loads the primary action. The MusicBrainz source URL is useful attribution and does not add clutter.

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

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

For a read-only lookup with a rich schema covering all parameters, the description is mostly complete. It explains the core behavior, supported entity types, and `inc` usage. It does not describe the response shape in detail, but the absence of an output schema and the simplicity of a single-entity lookup make this a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by giving concrete `inc` examples tied to entity types, such as ['releases','release-groups'] on an artist and ['recordings','labels'] on a release. This helps an agent construct meaningful requests beyond the schema's bare parameter names.

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

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

The description opens with a specific verb and resource: 'Fetch a single MusicBrainz entity ... by its MBID.' It enumerates the full set of entity types, making the scope unmistakable. It also distinguishes this tool from siblings like musicbrainz_search and musicbrainz_browse by emphasizing lookup by MBID.

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

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

The description clearly conveys the usage context: use this when you already have an MBID and need one entity. It also gives practical guidance on when to add `inc` to pull linked sub-entities. It does not explicitly mention when not to use it or point to a specific alternative, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses crucial behavioral traits: a side-effect-free pre-confirmation phase, a preview + confirmToken fallback for clients without elicitation, that 'nothing is changed before confirmation', and the OAuth scope needed. This gives an agent a clear model of the mutation's safety and sequencing, well above what readOnlyHint/destructiveHint 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.

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

The description is three dense sentences, with the core purpose front-loaded and supporting details (OAuth, confirmation, data source) following. Each sentence carries useful information, though the closing 'Data from MusicBrainz' attribution is not strictly needed for tool invocation, keeping it just short of a perfect 5.

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

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

Given the tool's complexity (mutating action, OAuth, confirmation flow, multiple entity types) and the absence of an output schema, the description covers prerequisites, MBID sourcing, and the confirmation protocol thoroughly. It does not describe what a successful commit returns, but the confirmation flow and annotation hints (idempotent, non-destructive) make the behavior predictable enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds minimal parameter-specific meaning beyond what the schema already provides; the mention of deriving the collection MBID from a URL is helpful context, but the schema's per-parameter descriptions already explain action, entityType, mbids, collection, and confirmToken adequately. The description doesn't need to compensate for any coverage gap.

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

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

The first clause 'Add or remove entities ... in one of YOUR MusicBrainz collections' pairs a specific verb (add/remove) with a precise resource (collection membership). It lists the entity types explicitly, and the resource is clearly distinct from the sibling tools (search, lookup, browse, submit_tags, submit_rating), so an agent can tell what it does without opening the schema.

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

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

The description gives clear operational context: OAuth requirements (`MUSICBRAINZ_OAUTH_*` with `collection` scope), how to obtain the collection MBID from its URL, and the two-step confirmation flow. It does not explicitly name alternatives or state when not to use this tool, but the prerequisites and owned-collection framing make the intended usage obvious.

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

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

Annotations already convey readOnlyHint, idempotentHint, and openWorldHint; the description adds the extraction-and-lookup mechanism and notes that inc includes linked sub-entities. It does not disclose response shape, error behavior, or rate-limit implications, but with safety annotations present this is acceptable.

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

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

Three sentences, no wasted words: the main action is front-loaded, the use case follows, and the inc hint plus read-only note round it out. The source attribution is brief and not distracting.

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

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

For a read-only URL resolver, the description covers the input format, the lookup behavior, and the inc option. With no output schema, a little more detail about exactly what the returned entity contains would help, but the view parameter's schema description already explains response shape, so the definition is largely complete.

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

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

Schema coverage is 100% and the schema already documents url, inc, and view well. The description adds value by clarifying inc as linked sub-entities and giving concrete URL path examples, while leaving the lengthy view semantics to the schema where they already live.

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

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

The description states a specific verb and resource: it turns a MusicBrainz URL into its underlying entity by extracting the type and MBID. It gives concrete URL examples and clarifies how this differs from a plain MBID lookup, so an agent can distinguish it from musicbrainz_lookup and musicbrainz_search.

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

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

It gives a clear usage context: "Handy when a user pastes a MusicBrainz link." However, it does not explicitly say when not to use it or name alternatives such as musicbrainz_lookup for direct MBID queries, so the guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description reinforces 'Read-only.' Beyond the annotations, it adds useful behavioral context: results are 'ranked matches with their MBIDs,' plain text matches entity names, and fielded Lucene queries are supported with concrete examples. It does not discuss rate limits or response shape details, but the safety profile is already covered by annotations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place: purpose, query semantics with concrete examples, and chaining to lookup. The read-only and data-source notes are brief and non-redundant enough to not feel wasteful.

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

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

For a read-only search tool with 100% parameter schema coverage and strong annotations, the description is complete. It explains what results contain (ranked matches with MBIDs), how to execute both plain-text and Lucene queries, and where to send the resulting MBID next. The absence of an output schema is mitigated by the explicit mention of MBIDs and the routing to lookup for full detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value above the schema by showing query syntax examples such as `artist:"Miles Davis" AND country:US`, `release:"Kind of Blue" AND format:Vinyl`, and `recording:"So What" AND dur:[540000 TO 560000]`, plus noting that plain text matches the entity name. This helps an agent construct valid queries more confidently.

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

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

The description opens with a specific verb and resource: 'Search a MusicBrainz entity type with a Lucene query and get back ranked matches with their MBIDs.' It clearly distinguishes this from lookup by saying 'Feed a returned MBID into musicbrainz_lookup for full detail.' The scope is precise and leaves no doubt about what the tool does.

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

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

The description clearly frames when to use this tool: when you need to find entities by Lucene text or fielded queries. It also provides chaining guidance to musicbrainz_lookup, but it does not explicitly name exclusions for browse or resolve, so it stops short of fully enumerating alternatives.

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

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

Beyond the annotations (idempotentHint, readOnlyHint=false), the description reveals critical behavior: OAuth requirement, the 0–100 scale mapping to 1–5 stars, the two confirmation modes (native prompt vs confirmToken fallback), and the guarantee that 'Nothing is sent before confirmation.' This adds substantial value over the annotations.

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

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

The description is compact yet information-dense. It front-loads the core purpose, then moves to auth, scale, confirmation mechanics, and data source. Every sentence contributes; there is no filler or redundancy.

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

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

The description covers the essentials for correct invocation: auth scope, rating semantics, confirmation behavior, and the two-step fallback. It does not specify the success response format or error cases, but given no output schema and the tool's moderate complexity, the provided information is sufficient for reliable selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful semantics beyond the schema: it explains the star/point mapping, that 0 removes the rating, and the full behavior of confirmToken (never on first call, never invented, never reused). This enriches the schema's parameter meanings.

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

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

The description opens with a specific verb+resource: 'Set YOUR rating for a MusicBrainz entity.' It clearly states the action (set rating), the target (MusicBrainz entity), and the scope (your own rating). This distinguishes it from sibling tools like musicbrainz_submit_tags and musicbrainz_modify_collection without ambiguity.

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

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

Clear context is provided: the tool is for setting a user rating, requires OAuth with the 'rating' scope, and involves a confirmation flow. It does not explicitly name alternative tools or state when not to use it, but the purpose is distinct enough among siblings that an agent can infer correct usage.

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

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

Beyond the annotations, the description richly discloses behavior: the OAuth requirement and scope, vote semantics, the confirmation prompt vs. two-step fallback with confirmToken, the exact-XML preview, and the guarantee that nothing is sent before confirmation. This substantially exceeds the annotation data and gives an agent a precise behavioral model.

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

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

The description is longer than average but front-loaded with the core purpose before moving to auth, vote semantics, and confirmation behavior. Each section serves a real need, though the attribution sentence and some confirmToken redundancy could be trimmed without loss.

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

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

Given the tool's high complexity — OAuth, vote behavior, confirmation modes, and repeat-call fallback — the description covers everything needed to invoke it correctly. It explains the fallback flow, what the preview contains, and what must never be done with confirmToken, so an agent has enough context even without an output schema.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains what each vote value does, and it gives a detailed protocol for confirmToken (phase-1 response, repeat call, never first/invented/reused). This is useful meaning not encoded in the schema alone.

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

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

The description opens with a specific action ('Apply user tags to a MusicBrainz entity') and clearly scopes it to the user's own account, which distinguishes it from read-only lookup/browse/search siblings. It also names the three vote modes and their effects, making the tool's purpose unambiguous.

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

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

The description provides clear context for when tagging is appropriate — authenticated, account-specific action with OAuth and the 'tag' scope — but it never explicitly tells the agent when not to use this tool or how to choose between it and musicbrainz_submit_rating or modify_collection. Usage is implied rather than explicitly routed.

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