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 (readOnlyHint=false, openWorldHint=true), the description discloses critical behaviors: it requires OAuth, and without confirm:true it returns a dry-run preview and makes NO network call. This significantly informs the agent about side effects and safety, exceeding what annotations convey.

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 and front-loaded with the action and entity types, then quickly covers OAuth, MBID sourcing, and the dry-run/confirm mechanism. Every sentence earns its place with no 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 essential operational details for a modification tool: authentication, dry-run behavior, and how to identify the collection. It does not mention the response format or error handling, but given the absence of an output schema and the straightforward nature of the operation, it is sufficiently complete for an agent to invoke 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 coverage is 100% with descriptions for every parameter, but the tool description adds valuable semantics: it explains that confirm gates the actual change, tells how to get the collection MBID from a URL, and notes entityType is plural. This enriches the schema baseline.

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 the precise action (add or remove) and the resource (entities in a MusicBrainz collection), and enumerates the supported entity types. It clearly distinguishes this modification tool from siblings like search, browse, and lookup, which have different purposes.

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: it operates on the user's own collections, requires OAuth with collection scope, and explains how to obtain the collection MBID from its URL. It does not explicitly mention alternatives or when not to use it, but the purpose is unambiguous and the sibling tools are clearly different actions.

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 flag readOnlyHint=false and destructiveHint=false, but the description adds the critical dry-run/confirm behavior and the rating scale (0 removes). This goes beyond the structured hints by explaining the two-phase submission mechanism and the exact effect of rating values, which is essential for safe invocation.

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 sentences, front-loading the purpose, then auth, then the confirm behavior. No wasted words, and every sentence earns its place by providing actionable 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?

Given the tool has no output schema, the description explains the dry-run preview and submission, but does not specify the exact return format or error handling. However, for a submission tool with this scope, the essential behavior is covered, and annotations plus schema handle most edge cases.

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%, but the description adds meaning by explaining the rating scale (0–100 with 20-step stars) and the confirm parameter's dry-run vs submit behavior, which the schema does not fully convey. It reinforces the semantics without duplicating everything.

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 ('Set'), resource ('YOUR rating for a MusicBrainz entity'), and clarifies it is a user rating, distinguishing it from other MusicBrainz operations like tags or searches. It also names the required OAuth scope, making the purpose unmistakable.

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 explicit conditions for use: the OAuth requirement and the confirm parameter's role (dry-run preview vs actual submission). It does not explicitly exclude alternatives, but the tool's scope is clear enough that an agent can infer when to use it over siblings like musicbrainz_submit_tags.

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 the OAuth requirement and scope, explains each vote direction's effect, and clarifies that without confirm:true no network call is made and only an XML preview is returned. These behavioral details go well beyond the annotations (readOnlyHint false, destructiveHint false) and materially improve safe invocation.

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 and front-loaded with the purpose and OAuth requirement before parameter behavior. The final attribution sentence about MusicBrainz being an open encyclopedia is marginal for tool invocation, but the overall structure is efficient.

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

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

For a mutation tool with five parameters and no output schema, it covers auth, vote semantics, and the confirm dry-run safety valve. It stops short of describing what a confirmed submission returns or possible error conditions, which keeps it from a 5.

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, but the description adds meaning: it defines the default vote as upvote, explains what downvote/withdraw do, and ties confirm to preview-vs-submit behavior. This is valuable information not present in the schema property 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 opens with a specific verb-resource pair ('Apply user tags to a MusicBrainz entity') and scopes it to the user's own account, making it easy to distinguish from the sibling rating, collection, and search tools. It also names the vote modes, which clarifies the tool's full purpose.

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 clear context for when to invoke the tool (tagging an entity) and explains the conditional confirm flag: preview without a network call vs. actual submission. It does not explicitly contrast with sibling tools such as musicbrainz_submit_rating, so it earns a 4 rather than a 5.

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