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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds genuinely new behavior: the call defaults to a non-mutating preview and requires an explicit second call with dry_run=false to commit. It also flags that 0 is not a valid folder id. It stops short of disclosing idempotency or what happens if the release is already in the folder, so not a 5.

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 short sentences with the core action and the critical dry-run caveat front-loaded; no filler. Minor angularity from the embedded parenthetical and stray indentation, but nothing 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 three-parameter mutation tool with annotations covering the safety profile and no output schema, the description supplies what structured fields omit: the two-phase dry-run contract and the invalid default sentinel. It would be fully complete with a note on repeat-add behavior.

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 0%, so the description must carry the param burden, and it does for two of three: it documents dry_run's default/effect and folder_id's default of 1 = Uncategorized with 0 disallowed. release_id is left to its obvious name, which is a minor 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?

States a specific verb and resource (add a release to a collection folder), which implicitly separates it from siblings like add_to_wantlist, remove_from_collection, and move_collection_item. It does not explicitly name or contrast a sibling, so it falls short of a 5.

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 explains the operational workflow (dry-run first, then call again with dry_run=false), which is useful implied usage guidance. However, it gives no guidance on when to choose this tool over siblings such as move_collection_item or add_to_wantlist, and no prerequisites or exclusions.

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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but say nothing about the preview/apply workflow. The description adds the critical fact that the default is a non-mutating preview and that a second call with dry_run=false is required to apply — genuine behavioral context beyond structured data. It stops short of noting auth requirements or what the preview returns.

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 tightly scoped sentences, front-loaded with the core action and immediately followed by the critical dry-run behavior. 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?

For a small mutation tool with no output schema, the description covers the operation and its preview/apply mechanics adequately. The main shortfall is parameter detail (rating bounds, notes semantics) that neither the description nor the 0%-coverage schema supplies.

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 0%, so the description must compensate, and it partially does: it clarifies that notes and rating are the updatable fields and that dry_run gates application. It does not describe release_id, the valid rating range, or the notes format, leaving gaps the schema does not fill.

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?

States a specific verb+resource ('Add a release to the wantlist') and adds the non-obvious upsert scope ('or update notes/rating if it's already there'). An agent can distinguish it from siblings like add_to_collection and rate_collection_item without opening any 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?

Clearly explains the dry-run-then-apply call protocol, which is the essential usage context for this tool. It does not, however, name alternatives (e.g., remove_from_wantlist or add_to_collection) or state when not to use it, so it falls short of the explicit when/when-not/alternatives bar.

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=true and openWorldHint=false, covering the safety profile. The description adds valuable behavioral context by stating the data comes 'from the cache' and that a last sync time is returned, which tells the agent the result may be stale. It stops short of detailing cache refresh semantics or permissions.

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 single, front-loaded sentence that efficiently enumerates the returned aggregates. Every item earns its place by clarifying the tool's scope and output content.

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?

There is no output schema, so the description appropriately enumerates the returned counts and metadata. However, for a tool with one parameter, omitting any explanation of the 'top' parameter leaves a notable invocation gap. The definition is adequate but incomplete for correct parameter 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?

The input schema has one parameter, 'top', with 0% description coverage and a default of 15. The description never mentions this parameter or what it controls, so the agent cannot know how to invoke it meaningfully beyond accepting the default.

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-resource pair ('Collection overview') and enumerates the exact aggregates it returns: counts by genre, style, label, artist, decade, format, country, duplicate masters, and last sync time. This makes it clearly distinguishable from siblings like query_collection, get_collection_value, and export_collection.

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 a summary use case by listing aggregate outputs, but it never says when to choose this tool over alternatives such as query_collection or get_collection_value, nor does it mention exclusions or prerequisites. No explicit usage guidance is provided.

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=false, destructiveHint=false, openWorldHint=true, so the safety profile is largely covered. The description adds genuinely useful behavior — the dry-run default — though it doesn't say what the dry run returns, whether names must be unique, or what auth scope is needed.

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 short sentences, front-loaded with the operation and then the modifier; nothing is wasted. It is close to under-specified rather than merely concise, but the structure itself is clean.

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?

A mutation tool with no output schema, 0% schema coverage, and no documented return value or dry-run semantics. The description doesn't say what a dry run produces or how to actually commit the creation, which an agent needs in order to complete the workflow.

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 0% and only the title 'Name' exists, yet the description says nothing about what the folder name must be (uniqueness, length, forbidden characters). The dry-run statement merely restates the schema's default:true rather than adding semantic value.

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?

Specific verb ('Create') + resource ('collection folder'), so an agent immediately knows the operation. It does not differentiate from siblings such as add_to_collection or rename_folder, and 'collection folder' scoping (which service/account) is left implicit.

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?

'Dry-run by default' is an implicit usage hint — the agent should preview before committing — but there is no explicit when-to-use, no prerequisites (e.g. list_collection_folders to check for duplicates), and no named alternatives among the many folder siblings.

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 destructiveHint=true, but the description adds the non-obvious behavioral requirement that both dry_run=false and confirm=true must be set together, plus the upstream API refusal on non-empty folders. That is exactly the context an agent needs to avoid a failed or unwanted destructive call.

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 short sentences, front-loaded with purpose and constraint, then the destructive precondition, then the API limitation. No filler and nothing buried.

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 destructive, no-output-schema tool, it covers purpose, safety preconditions, parameter interplay, and the API-side failure mode. Nothing an agent needs in order to call it correctly is missing.

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 0%, so the description must carry the load; it explains the semantics and required combination of both confirm and dry_run, which is the highest-risk ambiguity in the schema. folder_id is only hinted at ("not 0 or 1") and its format is never stated, leaving a small 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?

States a specific verb and resource ("Delete an empty collection folder") and immediately scopes it away from the default folders via "not 0 or 1", which distinguishes it from create_folder and rename_folder among the 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?

Gives the preconditions that gate use: the folder must be empty, and the call only succeeds with dry_run=false AND confirm=true. It also gives the when-not condition (Discogs refuses folders containing items). It does not name an alternative tool, but no other sibling deletes folders, so none 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=false, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond the annotations by disclosing that it operates on the cached collection (implying a sync prerequisite) and the default path pattern. It does not disclose overwrite behavior if the target file already exists, which is a real gap for a write-to-disk tool.

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?

A single front-loaded sentence with zero waste. The action, format options, and default location are all packed in without padding.

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?

No output schema exists, and the description covers what the tool writes and the default destination, which is most of what an agent needs for a simple 2-param tool. Gaps remain around whether an existing file is overwritten and the sync prerequisite implied by 'cached', so it is adequate but not fully 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 description coverage is 0%, so the description carries the burden. It partially compensates by enumerating the format values (CSV or JSON) for the 'format' parameter and by explaining the default location pattern (~/.discogs-mcp/collection.<fmt>) tied to 'path'. However, it never explains that 'path' is a caller-supplied override or its expected form, leaving that parameter under-specified.

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 gives a specific verb+resource ('Write the cached collection') plus the output formats (CSV or JSON), so an agent can distinguish it from the read-oriented collection siblings (get_collection, query_collection, collection_summary). It does not explicitly name those siblings, so it falls short of the 5 tier, but the 'write to a file' framing is 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?

There is no when-to-use guidance and no named alternative. The agent is not told when exporting is preferable to get_collection or query_collection, nor that the collection should be synced first for the cache to be current. Usage is left entirely to inference.

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=true and openWorldHint=true, so safety is covered externally. The description adds genuine value by disclosing the returned fields (folder, rating, fields) and the empty-list edge case when the release is not owned. It stops short of any auth, rate-limit, or pagination context.

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 short sentences that are front-loaded with the core return content, with no filler. The stray line break is cosmetic. It is appropriately sized, though it wastes no words only because it omits parameters.

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 tool with no output schema and no annotations about returns, the description usefully sketches the return shape and the empty case. But it leaves the username parameter unexplained and says nothing about ordering or pagination for what could be multiple copies. Adequate but with clear gaps.

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 0%, so the description must compensate and largely does not. It implies the release_id scope via 'of a release' but never names the parameter, and the username parameter is entirely undocumented in both schema and description. An agent cannot tell what username does or whether it defaults to the authenticated user.

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 resource and scope: every copy/instance of a release in the collection, including folder, rating and fields. This lets an agent infer it is a per-release lookup returning owned copies. However, it never distinguishes itself from close siblings like get_collection or query_collection, so the agent must guess which list tool applies.

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?

There is no when-to-use guidance and no comparison to alternatives such as get_collection or query_collection. The only conditional sentence, 'Returns an empty list if it is not owned,' describes outcome rather than selection criteria. The agent gets no explicit signal about which collection tool to pick.

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=true and openWorldHint=true, so safety is covered, but the description adds nothing beyond the field list: no note on what happens when the artist_id is unknown, whether the lookup hits an external service, or how groups/members are represented. With annotations already covering the safety profile, the description's only added behavioral value is the hint that groups/members are included.

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?

A single compact phrase with no filler, and the return-shape information is front-loaded. It is terse to the point of being underspecified rather than 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?

There is no output schema, so the field list is a useful substitute for describing return values, but it omits the include_images parameter and any indication of failure modes. For a two-parameter read tool with no output schema, this is partial coverage.

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 0%, so both parameters (artist_id, include_images) are undocumented in the schema. The description never mentions either parameter, so it fails to compensate for the coverage gap — notably the optional include_images flag is entirely unexplained.

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 lists what the tool returns (profile, real name, aliases, groups/members), which implies it retrieves an artist, but there is no verb and no explicit statement of the action. It does not distinguish itself from the sibling get_artist_releases, which an agent must infer covers a different resource.

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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as get_artist_releases or search. The agent must infer that this is the lookup-by-id entry point for artist metadata.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful scope information by disclosing that appearances with roles are included, which an agent could not guess from the name. It does not, however, mention pagination behavior, response size, or how results are ordered by default.

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?

A single compact sentence with the resource front-loaded and zero filler. It is appropriately sized for the amount of information it chooses to convey, though that brevity comes at the cost of completeness.

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 paginated list tool with an entirely undocumented parameter schema and no output schema, the description omits any mention of paging, default sort, or result shape. An agent could call it, but not confidently or efficiently.

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 0% for five parameters, so the description carries full burden, yet it says nothing about page, per_page, sort, or sort_order. Only the artist_id and result-content semantics are weakly implied. This leaves four pagination/sorting parameters undocumented anywhere.

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 names a specific resource — an artist's discography — and clarifies the contents (masters, releases, and appearances with roles). It distinguishes itself from get_artist (artist metadata) and get_master_versions by scope, though it is phrased as a noun rather than a verb.

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?

There is no guidance on when to use this versus alternatives such as get_artist, get_label_releases, or get_master_versions. The agent must infer usage purely from the resource name.

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=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: results come 'straight from Discogs' (live API, subject to paging and rate considerations) and are paginated one page at a time, with the cache tools noted as the paging-avoidance alternative. It does not state auth requirements or rate limits explicitly.

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 short sentences, front-loaded with the core behavior before the alternative-tool routing. No filler or restatement of the tool name.

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?

Annotation coverage and no output schema mean return values needn't be explained, but with 6 undocumented parameters the description is thin on how to drive paging (per_page defaults, page/sort interaction) and auth (username). Adequate for orientation, incomplete 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 description coverage is 0% across 6 parameters, so the description must carry the burden. It explains only folder_id=0 = all; page, per_page, sort, sort_order, and username are left entirely undocumented, and the sort/sort_order defaults are only visible in the schema. Partial compensation for a significant 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?

States a specific verb and resource (fetch one page of the Discogs collection) and immediately clarifies the folder_id=0 semantics ('folder 0 = all'). It explicitly names sibling tools (query_collection, collection_summary) and positions itself apart from them as the raw API path.

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?

Gives an explicit routing rule: for whole-collection questions, prefer the cache tools because they avoid API paging. This names concrete alternatives and the condition that selects them, which is exactly what an agent needs to choose between get_collection and the cache tools.

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=true, so the safe-read nature is covered. The description adds that the response includes allowed options, not just field names, which is useful. It says nothing about authentication, scoping by username, or caching/refresh behavior, so the added value beyond annotations is modest.

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 short sentences with no filler; the resource definition is front-loaded ahead of the usage note. The parenthetical example list is efficient and grounds the abstract term "custom fields."

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 no output schema, the description usefully states what comes back (fields plus allowed options), which is the most important unknown. However, the optional username parameter is undocumented everywhere, leaving a genuine gap for an agent deciding how to call it.

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 0%, so the description must carry the parameter burden, and it does not mention the username argument at all — an agent cannot tell whether omitting it yields defaults, the caller's own fields, or a global list. The only parameter-related content is the vague pointer to using returned ids with set_collection_field.

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 names a specific resource — custom collection fields and their allowed options — and gives concrete examples (Media Condition, Sleeve Condition, Notes). The retrieval verb is only implied by the noun phrase, but an agent can immediately tell this is the read-side counterpart to set_collection_field.

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?

"Use the ids with set_collection_field" establishes the workflow: fetch these field ids and feed them into the sibling mutation tool. It gives clear context for when the tool is needed, though it states no exclusions or prerequisites (e.g. whether the username argument is required for resolving user-specific fields).

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=true and openWorldHint=true, so the safety profile is covered. The description adds useful methodology context ('based on sales history') and the shape of the estimate, but says nothing about whether the estimate depends on the optional username or what happens if it is omitted.

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?

A single front-loaded sentence with zero waste; the return shape and methodology are stated up front. It is well sized for what it covers, though it is arguably too terse given the undocumented parameter.

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 tool with no output schema, naming the returned values (min/median/max) is helpful. However, the missing username semantics leave a real gap, and no guidance on estimate freshness or scope is provided.

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 single parameter (username, optional, default null) is not described in either the schema (0% coverage) or the description. The description never explains what omitting username does, so the agent cannot tell whether it defaults to the authenticated user's collection. With low coverage, the description should compensate but does not.

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?

States a specific verb+resource ('collection value') and enumerates the output (minimum, median, maximum) plus the methodology (based on sales history). It is clearly distinguishable from sibling mutation tools, though it does not differentiate itself from the nearby collection_summary.

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?

There is no when-to-use guidance, no mention of alternatives (e.g., collection_summary, get_price_suggestions), and no prerequisites. The agent must infer the purpose entirely from the one-line description.

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=true and openWorldHint=true, so the safety profile is covered. The description usefully discloses that results include parent label and sublabel context, but says nothing about what happens with a missing/invalid label id or about rate/remote-lookup behavior implied by openWorldHint.

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?

A single front-loaded sentence with no filler; the problem is under-specification rather than verbosity. Nothing in the sentence is wasted, but there is very little of it.

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?

No output schema exists to explain return values, so the description must carry that burden and it only names two content elements. With two undocumented parameters and no error/miss behavior, an agent has clear gaps before calling 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 0% and neither parameter is mentioned in the description. The required 'label_id' and the optional 'include_images' flag (which likely changes payload size) are left entirely undocumented, so the description does nothing to compensate for the schema 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?

Names the resource ('label profile') and qualifies its contents (parent label and sublabels), so an agent knows what kind of record comes back. It lacks an explicit verb and never names the neighbouring get_label_releases, but the 'profile' framing does implicitly separate it from a release listing.

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?

There is no statement of when to call this versus get_label_releases or the artist/release getters that sit alongside it in the sibling list. The agent must infer the distinction from the noun 'profile' alone.

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=true and openWorldHint=true, so the safety profile is covered. The description adds only that catalog numbers appear in results, and says nothing about pagination defaults despite page/per_page parameters existing. Modest added value against an already-covered safety profile.

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?

It is a single compact phrase with no wasted words, but its brevity comes from omission rather than efficiency; the tool's parameter and pagination behavior is simply absent.

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 tool with a required label_id, pagination parameters, and no output schema documenting the return payload, the description omits parameter meanings, pagination behavior, and result structure. It is too thin to call the definition self-sufficient.

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 0% and the description mentions no parameter at all — not label_id, not page, not per_page. With three undocumented parameters, the description does nothing to compensate for the 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 description names a specific resource ('releases on a label') and adds a return-content detail ('with catalog numbers'), which is enough to distinguish it from the sibling get_label, which fetches the label itself. It is clear but does not explicitly name or exclude any sibling, so it falls short of a 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_label for label metadata or get_release for a single release. The agent must infer context entirely from the tool name.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-data profile is covered. The description adds useful content detail that each item's comment is included, but it does not mention pagination, authentication needs, or response shape.

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 single front-loaded phrase with no wasted text. It is appropriately brief for a simple one-parameter retrieval tool, though the sentence fragment omits an explicit verb.

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 tool with an undocumented required parameter and no output schema, the description leaves key gaps: it does not explain list_id, return format, pagination, or how this differs from get_user_lists. An agent could infer basic intent but would still need to inspect the schema and experiment to invoke it confidently.

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 0%, and the only parameter list_id is not explained in the description. The phrase 'in a Discogs list' implies a list identifier exists, but it adds no format, constraints, or meaning beyond the bare schema field.

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 identifies the resource as items in a Discogs list and notes that each item includes its comment. It is clear enough to distinguish from get_user_lists, which returns lists rather than list items, though it does not explicitly name or compare against sibling tools.

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?

There is no guidance on when to use get_list versus alternatives such as get_user_lists. The description does not state prerequisites, when-not conditions, or the relationship between fetching lists and fetching items within a list.

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=true and openWorldHint=true, so the safety profile is covered. The description adds only a conceptual definition of the resource and says nothing operational beyond that – no auth expectations, no note on what data (image flag, formats) is affected by the parameters.

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?

It is a single short sentence with no wasted words, but it is under-specified rather than tight: it leads with a noun definition instead of the action. Concise but not front-loaded with what the tool does.

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 two-parameter read tool with no output schema the bar is modest, yet the definition omits the action, the meaning of include_images, and any sense of the returned payload. An agent cannot call this confidently without guessing at the parameters.

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 0%, so the description should compensate for the two undocumented parameters. It explains nothing about master_id or include_images, leaving both entirely to field names. Only indirect value is the loose link between 'master' and master_id.

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 defines what a 'master release' is ('the umbrella over every version/pressing of an album') but never states the action the tool performs. It gives a resource definition rather than a verb+resource, so the agent must infer that this retrieves a single master. It offers partial differentiation from get_master_versions by framing the master as the umbrella over versions, but not explicitly.

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?

There is no when-to-use guidance and no reference to alternatives such as get_release or get_master_versions. The agent is left to infer the correct tool purely from the name.

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 and openWorldHint, so the safety profile is covered. The description adds the returned field set, which is useful context, but says nothing about pagination behavior despite page/per_page params, nor rate limits or result ordering. With annotations doing the heavy lifting, this is a modest addition.

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 front-loaded sentences with no filler: purpose and returned fields first, filters and workflow second. Every clause earns its place.

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?

No output schema exists and 9 params have zero schema coverage, so the description carries the burden. It covers purpose, filters, and the downstream workflow well, but leaves pagination/sorting semantics unexplained for a list tool.

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 0%, so the description must compensate and it only partially does: it explains the format, country, year (mapped to `released`) and label filters. It omits the semantics of page, per_page, sort, sort_order, and master_id, leaving roughly half the parameters undocumented anywhere.

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?

States a specific verb ('List') and resource ('every version (pressing) of a master') and even names the returned fields (label, catno, country, year). This clearly separates it from siblings like get_master (the master itself) and get_release (a single release).

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?

Provides a concrete trigger ('which pressing is this?') and routes the agent to the follow-up tool (get_release) for confirmation, plus lists the usable filters. It stops short of stating when NOT to use it or when get_master/get_release alone would suffice.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses the 403 failure mode when seller settings are missing and that the tool explains the error, which helps an agent interpret a failure.

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 sentences, front-loaded with the core function and followed by the failure condition. Efficient overall, though the odd leading indentation and the trailing 'this tool explains that' phrasing are slightly awkward.

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 single-parameter read with no output schema, the description covers both what is returned (price per condition grade) and the key gotcha (the 403 for accounts without seller settings). The main gap is that it never addresses the release_id input.

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 0% and the description never mentions the release_id parameter, its expected format, or what value to supply. With a required input entirely undocumented in both the schema and the description, semantics rest only on the self-explanatory parameter name.

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?

States a specific verb+resource: it returns suggested sale prices per condition grade sourced from Discogs sales history. The purpose is clear and unambiguous, though it does not differentiate itself from any sibling (no competing pricing tool exists in the list, so differentiation is less critical).

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?

Usage is implied rather than stated: an agent can infer it should call this when it wants pricing for a specific release. There is no explicit 'when to use' vs. 'when not to use' guidance and no named alternative, so the guidance remains implicit.

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=true and openWorldHint=true, so the safety profile is covered. The description adds useful context by enumerating the returned data (tracklist, credits, identifiers, community stats), but says nothing about error behavior or what include_images changes.

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?

A single front-loaded sentence that leads with the core purpose, then enumerates contents. Dense and waste-free, though the long parenthetical list makes it slightly list-heavy.

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 no output schema, the description usefully enumerates the returned fields, which compensates well on the return side. But for a 2-parameter tool at 0% schema coverage, the missing parameter documentation (especially include_images) leaves the definition incomplete.

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 0%, so the description carries the full burden, yet it never mentions release_id or the include_images option. Only the vague notion of 'one release' hints at an identifier; the images flag is entirely undocumented in both schema and description.

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?

States a specific verb and resource ('Full detail for one release') and adds the key disambiguation that it is 'a specific pressing', which implicitly separates it from get_master. However, it does not name the sibling it contrasts with, so the differentiation is left partly to inference.

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 phrase 'a specific pressing' hints at when this applies versus get_master, but there is no explicit when-to-use/when-not guidance and no mention of the alternative tools (get_master, get_master_versions) in the large sibling set.

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=true and openWorldHint=true, so the safety and external-data profile is covered. The description adds the useful detail that currency defaults to the account currency, but says nothing about rate limits, freshness of the marketplace data, or what happens when no listings exist.

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?

Front-loaded with the return payload in a single tight sentence, then the currency detail. Slightly marred by stray indentation and the dangling quoted second sentence, but nothing is wasted.

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 no output schema, the description carries the return-value burden and does so adequately (lowest price, number for sale). For a 2-parameter read-only tool this is nearly sufficient; only release_id semantics and empty-result behavior are missing.

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 0%, so the description must compensate. It does add meaning for `currency` (ISO code examples and the account-currency default), but `release_id` is left entirely unexplained beyond its name.

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?

States a specific resource (marketplace snapshot for a release) and the exact data returned (lowest listed price, number for sale). This implicitly separates it from sibling pricing tools like get_price_suggestions and get_collection_value, though it never names an alternative explicitly.

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?

There is no when-to-use guidance, no stated prerequisites, and no comparison against alternatives such as get_price_suggestions or get_release. The only conditional note concerns the currency default, not tool selection.

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=true and openWorldHint=true. The description adds that only public lists are returned and that username defaults to the caller, which is useful context, but it omits auth requirements, rate limits, and pagination behavior.

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 single front-loaded fragment with no filler, which is efficient. However, for a tool with three parameters and no schema descriptions, it is arguably too sparse to be appropriately sized.

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 list-retrieval tool with three parameters and no output schema, the description omits crucial context: what 'lists' are, how pagination works, and how this differs from sibling list/collection tools. Annotations cover safety but not domain specifics.

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 0%, so the description must compensate. It only clarifies the username default ('defaults to you'); page and per_page remain entirely undocumented in both schema and description.

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 names the resource ('A user's public lists') but provides no verb and largely restates the tool name with minor additions ('public', 'defaults to you'). It does not distinguish this tool from siblings like get_list or get_wantlist.

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 contains no when-to-use guidance, alternatives, or exclusions. 'Defaults to you' is a default parameter behavior, not usage guidance for selecting this tool over others.

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=true and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context: results are paginated ('one page'), which tells the agent not to expect the full list and implies a paging loop — information absent from 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?

Two sentences, zero filler, with the scoping statement front-loaded and the routing advice immediately after. Every clause earns its place.

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?

Routing is well covered, but with no output schema and three undocumented parameters, the definition leaves the agent guessing at the return shape and at page/per_page/username semantics. Adequate for a simple read tool, but with clear gaps.

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 0% across three parameters (page, per_page, username), yet the description only vaguely gestures at paging with 'one page' and says nothing about per_page defaults or what username does (another user's wantlist vs. the authenticated one). It fails to compensate for the 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?

States the resource (the wantlist) and its scope precisely: 'One page of the wantlist.' It also implicitly contrasts with the whole-wantlist path, so an agent can distinguish it from siblings like query_collection without opening any 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?

Explicitly names the alternative workflow ('sync_collection and then query the `wants` view with query_collection') and the condition that selects it ('For whole-wantlist questions'). This is a textbook when-to-use-this-vs-that statement.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful domain behavior beyond that: results carry item counts, and folder IDs 0/1 are reserved sentinels ("All", "Uncategorized") that an agent must recognize when passing IDs to other tools. It says nothing about ordering, auth, or whether the list is per-user.

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 short, front-loaded fragments with zero filler; the reserved folder-ID mapping is placed immediately. It is arguably over-terse rather than bloated, so the structure works even though the content is thin.

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 no output schema and 0% parameter coverage, the description carries the return-value burden and only partially meets it: it conveys that folders come with item counts and explains the two sentinel IDs, but not the shape of the result, ordering, or the role of username.

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 single parameter (username) has 0% schema description coverage, and the description never explains what it does or what happens when it is omitted (default null). Schema coverage is below the 50% threshold, so the description was required to compensate and does not.

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 names a specific resource (collection folders) and a distinguishing output trait (item counts), which lets an agent separate it from get_collection or collection_summary. It omits an explicit verb like "list", relying on the tool name to supply it, and does not contrast itself with siblings such as get_collection_fields.

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?

There is no statement of when to call this versus the other collection-listing siblings (get_collection, query_collection, collection_summary). The folder-ID hints imply this is the entry point for folder navigation, but that inference is left entirely to the agent.

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 this is a non-readonly, idempotent, non-destructive, open-world operation, so the safety profile is partly covered. The description adds a genuinely useful trait not in the annotations: the operation is a dry-run by default, so no mutation occurs unless explicitly requested. It still omits behavior on missing folders or permission requirements.

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 tight sentences with zero filler; the action is front-loaded and the dry-run caveat follows immediately. Every word earns its place.

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 4-parameter mutation tool with 0% schema coverage and no output schema, the description covers purpose and the dry-run default but leaves the three required ID parameters and error/permission behavior unexplained. It is minimally viable rather than 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 description coverage is 0%, so the description must carry the burden. It conceptually maps 'instance' to instance_id, 'folder' to to_folder_id, and clarifies dry_run's default, but adds no meaning for release_id (why it is required alongside instance_id) and no ID formats or constraints, so compensation is only partial.

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?

States a specific verb (move), resource (collection instance) and destination (another folder), which clearly differentiates it from siblings like add_to_collection, remove_from_collection, and rename_folder. It does not explicitly name a sibling to route against, so it lands just short of a 5.

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 only guidance is implicit: 'Dry-run by default' tells the agent it must flip dry_run=false to actually effect the move. There is no explicit when-to-use vs alternative, no prerequisites, and no contrast with add_to_collection/remove_from_collection, leaving usage largely inferred.

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=true and openWorldHint=false, so safety is covered. The description goes further by adding the 500-row cap, clarifying that queries hit a local cache (no API calls), and flagging data-freshness dependencies on sync_release_details — real behavioral context 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.

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

The core purpose and row limit are front-loaded, and the table/column listing is dense reference material that earns its space for a SQL-writing tool. It is long, but the structure (intro, bulleted tables, JSON usage note, freshness caveat) keeps it navigable rather than 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 no output schema, the description compensates by documenting the 500-row result limit and the columns each query can return, plus JSON-handling and freshness caveats. It stops short of describing the return shape (row objects) or error behavior on invalid SQL, which would round out completeness.

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 0% and the single `sql` parameter is a bare string, so the description must carry the burden — and it does, enumerating every available table/view, its columns, the SQLite dialect, JSON array/object access patterns via json_each and json_extract, and worked examples. This is substantially more meaning than the schema provides.

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?

States a specific verb and resource ('Run a read-only SQL SELECT against the local collection cache') plus a hard constraint (max 500 rows), which clearly separates it from sibling tools like find_in_collection, search, or get_collection. An agent knows exactly what capability this exposes 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?

Gives clear when-to-use context ('answer any question across the whole collection without API calls') and prerequisite conditions (country and tracks require sync_release_details). It does not explicitly contrast against siblings like find_in_collection or search, so the alternative-selection decision is left partly to inference.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond them: the 0–5 scale, that 0 clears the rating, and critically that the call dry-runs by default before committing.

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?

A single tight sentence that front-loads the core action, then adds the two most decision-relevant facts (reset semantics, dry-run default). No wasted words.

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?

There is no output schema and 0% schema coverage across 4 params, so the description carries the burden. It covers the primary rating and dry-run semantics but omits what release_id/instance_id identify and what the dry-run response returns, leaving gaps for an agent.

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 0%, so the description must compensate; it defines rating (0–5, 0 clears) and implies dry_run's default behavior. However, release_id and instance_id remain completely undocumented, leaving half the parameters unexplained.

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?

States a specific verb (Set a star rating) and resource (a collection instance), so the action is unambiguous. It doesn't differentiate itself from siblings like set_collection_field, but the verb+resource pairing is clear enough to identify the tool.

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?

Uses the quasi-guidance of '0 clears it' and 'Dry-run by default', which tells the agent how to reset a rating and that side effects are deferred. However, it names no alternative and gives no explicit when-to-use versus the many other collection-mutation siblings (add_to_collection, set_collection_field, move_collection_item).

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 destructiveHint=true and readOnlyHint=false, but the description goes further by disclosing the granularity of destruction (one instance, not all copies) and the exact two-flag gate (dry_run=false AND confirm=true) that is not derivable from the schema defaults. It stops short of covering reversibility or permission requirements.

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 short sentences, front-loaded with the destructive operation and its scope, followed immediately by the safety precondition and the discovery pointer. 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?

For a destructive mutation with no output schema and zero schema-level parameter documentation, the description carries the critical safety information an agent needs to avoid accidental deletion. Minor gaps remain around failure behavior when a release has multiple copies and what the call returns, but the essentials are present.

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 0% for 4 parameters. The description explains the roles of confirm and dry_run and points to find_in_collection for instance_id, but release_id's identity and relationship to the instance are left implicit, so compensation for the coverage gap is partial.

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?

States a precise verb (remove) plus resource (a release from the collection) and narrows the scope to 'one copy (instance)', which is exactly the distinction an agent needs against siblings like move_collection_item or add_to_collection. There is no ambiguity about what the call 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 gives the operative precondition (dry_run=false AND confirm=true) and routes the agent to find_in_collection to obtain instance ids, which is real when-to-use guidance. It does not explicitly contrast with siblings such as remove_from_wantlist or delete_folder, 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.

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

Annotations already flag destructiveHint=true, but the description goes further and discloses the concrete safety gate: the call is destructive and requires dry_run=false AND confirm=true. That tells the agent the defaults (dry_run defaults to true) would make the call a no-op, which is exactly the kind of behavior structured fields don't 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?

Two short sentences, front-loaded with the purpose and immediately followed by the destructive precondition. Every clause earns its place with 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?

For a destructive mutation with annotations and no output schema, the description covers the critical execution requirements. It could add what a dry_run=true call returns or what happens if the release isn't on the wantlist, but nothing essential to calling it correctly is missing.

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 0%, so the description must carry the parameter burden. It meaningfully explains the semantics of dry_run and confirm (both must be false/true respectively), which is the non-obvious part; only release_id (an integer identifier) is left undocumented, and its meaning is inferable from the tool name.

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?

States a precise verb (Remove) and resource (a release from the wantlist), which cleanly distinguishes it from the sibling add_to_wantlist. An agent knows exactly what the call changes 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 makes the use case clear (undoing a wantlist entry) and states the exact conditions required to actually execute the removal. It doesn't explicitly name an alternative tool or state when NOT to use it, but the counterpart add_to_wantlist is unambiguous from the name.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the mutating-but-safe profile is covered. The description adds the folder 0/1 exclusion and the dry-run default, but is silent on permissions, reversibility, and error behavior beyond 'Dry-run by default' (which also restates the schema default).

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 short, front-loaded sentences with no filler. The parenthetical '(not 0 or 1)' is telegraphic and context-dependent, but overall the size is well matched to the tool.

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?

No output schema exists, so the description needn't explain return values, but for a 3-param mutation with 0% schema coverage it leaves gaps: what dry-run reports, required auth, and what happens if folder 0/1 is targeted. Adequate but not 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 0% for three parameters, so the description must compensate. It partially does: it constrains folder_id (not 0 or 1) and explains dry_run's default behavior, but leaves 'name' (the new folder name) entirely uninterpreted.

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?

States a specific verb+resource ('Rename a collection folder') that an agent can immediately distinguish from create_folder and delete_folder. The '(not 0 or 1)' note clarifies the target scope, though it never names the sibling alternatives.

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?

Usage is implied rather than stated: the '(not 0 or 1)' restriction and 'Dry-run by default' hint at when/how to call it, but there is no explicit when-to-use, when-not, or alternative routing among the folder siblings.

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=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that the return is a compact list and that detail requires a second call, but says nothing about pagination behavior despite page/per_page, nor about rate limits or result caps.

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?

Front-loads the purpose in one sentence, then adds two short sentences of practical detail with no filler. Slightly awkward wrapping/indentation but every sentence contributes 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 15-parameter tool with zero schema coverage and no output schema, the description documents only about four parameters and omits pagination, result limits, and the meaning of the `type` selector. An agent could invoke it, but not confidently or completely.

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 0% across 15 parameters, so the description carries the burden and only partially meets it. It clarifies query semantics, the `year` range format ("1990-1995"), and the barcode/catno pinning use case, but leaves type, genre, style, track, format, country, release_title, page, and per_page entirely unexplained.

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?

States a specific verb and resource ('Search the Discogs database') and signals the mix of free-text query plus field filters. It partially differentiates from siblings by routing detail lookups to get_release/get_master/get_artist/get_label, but never says how it relates to collection-scoped siblings like find_in_collection or query_collection.

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?

Gives concrete strategy: combine `query` with field filters, use barcode or catno to pin down a specific pressing, and fetch details via the get_* tools. It stops short of exclusions (e.g. that this does not search the user's own collection), so it is clear context without full when-not guidance.

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 the safety profile (not read-only, idempotent, non-destructive, open-world), so the description need not restate it. It adds genuinely useful behavior beyond that: values are validated against the dropdown option set from get_collection_fields, and the call is a dry-run unless explicitly applied.

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 short sentences, front-loaded with the action and with zero filler. The trailing 'Dry-run by default' is slightly detached but still earns its place as a critical behavioral note.

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?

There is no output schema and no annotations covering auth or side effects, and 5 parameters are undocumented at 0% coverage. The description never states what a dry-run returns, whether an existing field value is overwritten, or how release_id and instance_id relate, so an agent must infer the invocation contract.

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 0%, so the description carries the full burden and only partially discharges it. It explains the constraint on 'value' (must be an option returned by get_collection_fields) and the dry_run default, but release_id, instance_id and field_id are left with no meaning beyond their 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?

States a specific verb and resource ('Set a custom field ... on a collection instance') and scopes it to a collection instance rather than a release, which separates it from the release-level siblings. It also names the related tool get_collection_fields, so an agent can place it in the workflow 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?

Gives clear context: use get_collection_fields to obtain valid options for dropdown fields, and the operation is dry-run by default. It does not, however, say when to flip dry_run=false or compare itself against sibling mutators such as add_to_collection or move_collection_item.

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 declare it as a non-read-only but non-destructive local operation, and the description adds real behavioral detail beyond them: incremental default behavior, what full=true additionally catches (removals, folder moves, edits), and that tracklists/countries come from a separate sibling. It stops short of mentioning failure modes or re-sync cost.

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?

Four compact sentences, front-loaded with the core action, then mode semantics, then usage ordering, then a related-tool pointer. Every sentence carries distinct information with no 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?

With no output schema, the description adequately covers what the sync produces conceptually, its two modes, and its prerequisite role. It could be more complete on error/partial-sync behavior, but nothing essential for correct invocation is missing.

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 0%, so the description carries the burden for the single 'full' parameter, and it does so well: explaining that default is incremental and full=true re-reads everything and catches removals/moves/edits. Minor gap is that it doesn't describe the boolean's default in-line, though the schema supplies that.

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?

States a specific verb (copy/sync) and resource (collection, folders, wantlist) plus the destination (local SQLite cache). It is immediately distinguishable from query_collection, collection_summary, and sync_release_details, which are named or clearly separate.

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?

Gives explicit ordering guidance ('Run this before using query_collection or collection_summary') and explains the incremental-vs-full choice. It doesn't state when not to use the tool, but the operational context is clear and actionable.

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?

Adds real behavior beyond the sparse annotations: one API request per release, a 60/min provider limit, background-by-default semantics, resumability, and rate-limit headroom reservation. Minor tension with openWorldHint=false since the tool explicitly calls the external Discogs API, but the annotation may be intended for the closed local cache it writes.

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?

Four short sentences, front-loaded with what it fetches and what it costs, with no filler. Slightly fragmented by line breaks, but every sentence carries 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?

No output schema is needed since the description names the fetched fields and points to sync_status for progress. For a resumable, rate-limited background sync the description covers the behavior an agent needs before invoking it.

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 0%, so the description must carry both parameters. It explains the background default well, but max_releases is never mentioned or given units/bounds, so the description only partially compensates for the undocumented schema.

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?

States a specific verb+resource ('Fetch full release detail') plus the exact scope that separates it from get_release: 'for cached releases that lack it'. The parenthetical enumerates the added fields (tracklist, country), so an agent can tell it apart from the other release-fetching 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?

Gives clear operational context: default is background execution and progress is checked via sync_status, plus it is resumable. It never explicitly says when NOT to call it (e.g., vs get_release for a single release), so it falls short of full when/when-not guidance.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral content by stating that it reports progress of background detail fetches (implying asynchronous state) and cache counts, but it says nothing about refresh behavior, polling cadence, or what an in-progress vs. idle state looks like.

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?

A single front-loaded sentence with no filler; every clause enumerates a distinct piece of returned information. It is efficiently sized for a no-argument status tool, though it stops just short of fully exploiting its brevity.

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 no output schema and no parameters, the description is the only source of information about what comes back, and it lists the reported categories but not their shape, units, or how to interpret progress values. Adequate for a simple status read, but an agent cannot tell from this alone what a returned record looks like.

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 takes zero parameters, so the schema imposes no semantic burden and the baseline of 4 applies. Nothing in the description is needed to disambiguate arguments.

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 names the specific resource it reports on — sync times, cache counts, and background detail-fetch progress — which is distinct from sibling action tools like sync_collection and sync_release_details. It lacks an explicit verb, but 'sync_status' plus the enumerated contents make the 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?

There is no guidance on when to call this versus the sync_* tools that actually trigger syncing, nor any stated precondition (e.g., check before starting a sync to avoid redundant work). The agent must infer that this is the read-only status companion to sync_collection and sync_release_details.

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=true and openWorldHint=true, covering the safety profile. The description adds value by disclosing the shape of the payload (profile plus collection and wantlist counts) in the absence of an output schema, but it stops short of describing what 'profile' contains or how counts are scoped.

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?

A single front-loaded sentence with no filler; every clause (identity, profile, sizes) carries information about the response.

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 read with annotations covering safety and no output schema, the description does enough by previewing the returned fields. It is slightly thin on what 'profile' and the size values actually contain.

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 takes zero parameters, so the baseline of 4 applies; there is no parameter meaning for the description to supply.

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 names a specific resource (the authenticated Discogs user) and enumerates what it returns (username, profile, collection/wantlist sizes), so an agent can tell it apart from the many collection-mutating siblings at a glance. It lacks an explicit verb like 'get', but the intent is 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?

Usage is only implied: an agent can infer this identifies the current user before calling user-scoped tools, but the description names no when-to-use condition and no alternative. There is no obvious sibling that does the same thing, so the omission costs little.

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