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?

The description adds meaningful behavior beyond the annotations: without `confirm: true` it returns a dry-run preview and makes NO network call, while with `confirm: true` it applies the change. It also discloses the OAuth requirement and that the operation targets the user's own collections. This exceeds the basic readOnly/idempotent hints already present.

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 reasonably concise and front-loaded: the purpose is stated first, followed by auth, collection ID source, and the critical `confirm` behavior. The final attribution sentence is not strictly functional, but the overall length is justified by the tool's complexity.

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 five parameters, no output schema, and a mutation tool, the description covers auth, target collection identification, entity types, and the confirm gating/dry-run behavior. It could be more explicit about what the dry-run preview contains or what success/failure responses look like, but enough is present for correct invocation.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description adds value by explaining the `confirm` dry-run/apply behavior and by telling users how to get the `collection` MBID from the URL. It does not add detail for `action`, `entityType`, or `mbids`, but the schema descriptions are sufficient.

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

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

The description opens with a specific verb and resource: 'Add or remove entities ... in one of YOUR MusicBrainz collections.' It enumerates the entity types and clarifies that only the user's own collections are affected, which distinguishes it from lookup, search, and 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?

It clearly states when to use the tool: for modifying a user's own MusicBrainz collection, and it specifies the OAuth requirement and `collection` scope. It also explains how to obtain the collection MBID from its URL. It does not explicitly contrast with alternative sibling tools, but the context is clear enough.

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?

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds valuable behavioral context: OAuth requirements, rating semantics (0 removes, 20-point steps), and critical dry-run behavior without confirm. This goes well beyond the structured hints.

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

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

Two compact sentences pack all essential information: auth requirement, rating scale, remove behavior, and confirm semantics. It is front-loaded with the core action and includes no filler or repetition.

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

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

For a simple submit tool without an output schema, the description covers auth, input semantics, and side-effect control. It doesn't describe return values, but the dry-run preview is mentioned and output detail is not necessary for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description elevates this by explaining the rating scale mapping (0–100 vs 1–5 stars), the special meaning of 0, and the confirm parameter's dry-run vs submit behavior—none of which are in the schema descriptions.

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

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

The description uses the specific verb 'Set' with a concrete resource ('YOUR rating for a MusicBrainz entity'), making the tool's function immediately clear. It also distinguishes itself from siblings like musicbrainz_submit_tags by focusing on 'rating' rather than tags.

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

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

The description implies when to use it (set/remove a user rating) and provides clear prerequisites (OAuth scope, confirm flag), but it does not explicitly compare against alternative tools or state when not to use it. The usage is inferred from the resource type rather than explicitly differentiated.

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

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

The description discloses important behavior beyond the annotations: OAuth and scope requirements, the effect of each vote value, the dry-run preview returning exact XML, and that confirm:true actually submits. It also notes no network call is made without confirmation. This is substantial and does not contradict 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?

Thre sentences, each earning its place: core action and scope, vote semantics, and confirm/network behavior. It is front-loaded with the most important information and contains no filler.

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 authentication, vote semantics, dry-run behavior, and the confirmation gate, which is enough to prevent accidental writes. It does not explicitly describe the return value for the confirm:true path, but the overall definition is still complete for practical use.

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

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

With 100% schema coverage, the baseline is 3, but the description adds real meaning for 'vote' and 'confirm' by explaining vote direction effects and dry-run vs submission behavior. The schema already covers mbid, tags, and entity sufficiently.

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

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

The description uses a specific verb ('Apply user tags') with a clear resource ('a MusicBrainz entity on YOUR account'), making the tool's purpose immediately identifiable. It also distinguishes this from sibling tools like musicbrainz_submit_rating and musicbrainz_lookup by emphasizing account-scoped user tags.

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: it requires OAuth with the tag scope, is scoped to 'YOUR account', and explains when to use the dry-run vs confirm behavior. It does not explicitly name sibling alternatives or exclusions, but the account and tag scope 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.