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

Annotations already signal that this is a non-read-only, non-destructive, non-idempotent operation. The description adds the precondition that the target collection must already exist, but it does not disclose behaviors such as duplicate handling, whether ROMs are appended, or what happens if any ROM ID is invalid. It does not contradict the annotations.

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

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

The description is one short, front-loaded sentence containing no filler or repetition. Every word contributes to the core meaning, and it is appropriately sized for a simple two-parameter operation.

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 low-complexity tool with two required parameters and an output schema, the description is mostly adequate: it states the operation and the existing-collection precondition. It lacks any guidance on when not to use it or what happens in edge cases, but the output schema and annotations cover some of the missing context.

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

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

With 0% schema description coverage, the description must compensate for missing parameter details. It maps the two parameters well: 'ROM IDs' to rom_ids and 'existing collection' to collection_id, adding meaning to collection_id beyond the bare title. It does not elaborate on constraints or behavior, but the parameter names and schema types are already fairly self-explianatory.

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

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

The description states a specific verb and resource: it adds ROM IDs to an existing collection. This clearly distinguishes it from sibling tools like remove_roms_from_collection and create_collection because it specifies 'add' and 'existing 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 phrase 'existing collection' implies the intended use case: the collection must already exist, so creating a collection would be a different tool. However, it does not explicitly name alternatives or state when this tool should be chosen over related 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 readOnlHint=false and destructiveHint=false, so the write nature is covered. The description adds the important behavioral detail that no artwork will be uploaded, which is not in the annotations and helps an agent understand this tool's scope. It doesn't describe other side effects or return behavior, but the annotations plus this extra detail provide reasonable transparency.

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, direct sentence that front-loads the core action and resource. Every phrase earns its place, and it avoids any redundant or vague wording. It is appropriately concise.

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 an output schema present, return values are covered by structured data. The description, combined with annotations, gives enough context for the tool's purpose and the 'without uploading artwork' distinction. It could mention uniqueness constraints or prerequisites, but for a simple create with a single required parameter, the provided context is largely 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 provides no information about the parameters (name, is_public, description, is_favorite). There is no added meaning beyond the property names in the schema. The description fails to compensate for the complete lack of parameter documentation.

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 action ('Create') and a specific resource type ('normal RomM collection'), and the qualifier 'normal' distinguishes it from the sibling create_smart_collection. The phrase 'without uploading artwork' further clarifies the scope of the operation. This is a clear, unambiguous statement of what the tool does.

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

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

The description gives clear context that this is for creating a normal collection, which impliedly contrasts with smart collections among the siblings. However, it does not explicitly state when to use this tool versus create_smart_collection or other alternatives. The user is left to infer the exclusion, though the 'normal' tag makes it straightforward.

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

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

Annotations already indicate a non-read-only, non-idempotent mutation, but the description adds no behavioral context beyond the word 'Create'. It does not describe side effects, authorization needs, or how optional fields like content, tags, and is_public behave.

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 sentence with no redundant phrases, and it front-loads the action and resource. The phrase 'with explicit supported fields' is somewhat uninformative, but overall the text is concise and easy to parse.

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 5-parameter creation tool with 0% schema description coverage, this description is far from complete. The output schema reduces the need to describe return values, but the parameter semantics and usage context are still missing, making correct invocation uncertain.

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 does not compensate by explaining any parameters. 'Explicit supported fields' is unhelpful because it names no fields. An agent is left to infer the meaning and relationship of rom_id, title, content, tags, and is_public entirely from names and defaults.

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

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

The description clearly specifies the verb 'Create' and the resource 'RomM note', which distinguishes it from siblings like update_rom_note, delete_rom_note, and list_rom_notes. However, the phrase 'with explicit supported fields' is vague and does not enumerate what those fields are.

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

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

The description provides no guidance about when to use this tool versus updating, deleting, or listing notes. It also does not mention prerequisites, such as needing a valid rom_id or that this tool is for creating new notes only.

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 establish this as a mutating, non-idempotent create operation, so the description does not need to repeat that. However, it adds only a small scoping detail ('explicit RomM filter criteria') and does not disclose side effects, permissions, uniqueness behavior, or any post-create behavior. This is consistent with the annotations, so no contradiction, but the added behavioral context is minimal.

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

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

The description is a single front-loaded sentence with no filler: it states the action, the resource, and the defining input in order. It is appropriately concise for a tool summary.

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?

Despite the output schema covering the return value, the overall definition is inadequate for a tool with this complexity. The large filter_criteria object has 0% schema description coverage, and the one-line description provides no guidance on constructing valid filters or choosing between similar collection tools. An agent would likely need external RomM knowledge to invoke this 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 the tool description does not explain any parameter semantics. The top-level parameter names are readable, and filter names like tags/genres are suggestive, but fields such as has_ra, matched, order_by, and the various *_logic combos remain opaque. The nested schema's note about RomM 5.1 filters provides some context but does not describe valid values or how criteria combine.

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

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

The description uses a clear verb ('Create') and names the exact resource ('smart collection'), and further specifies how it is created: 'from explicit RomM filter criteria.' This distinguishes it from static collection creation tools such as create_collection and from update_smart_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?

No explicit when-to-use or when-not-to-use guidance is provided. The phrase 'smart collection' implies the tool is for filter-based collections, but the description never names alternatives like create_collection or update_smart_collection, so an agent receives no routing guidance beyond 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 mark the tool as destructive, but the description goes further by explaining the exact boundary of destruction: 'ROM files are never deleted.' This is valuable behavioral context that prevents an agent from overestimating the impact of deletion. It does not contradict the destructiveHint annotation and adds a meaningful safety guarantee.

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 conveys the action, the confirmation requirement, and the safety boundary. Every word earns its place and there is no redundancy or 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 simple two-parameter destructive operation with an output schema and annotations, the description covers the essential points: what is deleted, what is not deleted, and the need for confirmation. It does not explicitly route the agent away from sibling tools, but the tool name and sibling list make the distinction reasonably clear. Minor gaps remain around the exact meaning of the confirm parameter and the result of the operation.

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. It only adds partial meaning for the confirm parameter via 'after explicit confirmation,' and gives no additional context about collection_id or how to obtain valid values. The description adds minimal value beyond the raw schema properties.

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

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

The description uses a specific verb and resource: 'Delete a collection' and adds a critical distinguishing detail: ROM files are never deleted. This helps an agent understand it is deleting the collection container, not the ROM files themselves, and separates it from tools like remove_roms_from_collection or delete_smart_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 phrase 'after explicit confirmation' provides a clear prerequisite: the confirm flag must be set. However, the description does not explicitly state when to choose this tool over alternatives such as remove_roms_from_collection or delete_smart_collection, so the guidance remains implied rather than explicit.

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 include destructiveHint=true, but the description adds valuable context beyond that: it specifies exactly what gets destroyed (the note, not ROM files) and emphasizes the explicit confirmation requirement. This is a meaningful safety-oriented behavioral disclosure that prevents catastrophic misuse.

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

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

The description is two tight sentences, front-loaded with the action and resource, then the confirmation requirement, then the safety clarification. 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?

For a destructive single-note deletion tool, the description covers the two most critical aspects: the confirmation guard and the non-destruction of ROM files. The output schema exists to describe return values. Minor gaps remain around the exact role of rom_id and potential error states, but these are secondary given the simplicity of the operation.

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 for undocumented parameters. It does clarify the non-obvious confirm flag by stating 'after explicit confirmation,' and implies that note_id identifies the target note. However, the required rom_id parameter is left unexplained beyond its title, leaving some ambiguity about its role and relationship to note_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 states a specific verb and resource: 'Delete one RomM note' and adds a crucial scoping statement, 'This does not delete ROM files,' which prevents misreading the tool as deleting ROMs. The resource is clearly distinguished from sibling delete_collection and delete_smart_collection 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?

The description communicates a clear condition for use: deletion happens only 'after explicit confirmation,' i.e., confirm=true. It also states what the tool does not do—delete ROM files—which is a useful exclusion. However, it does not explicitly name an alternative tool for related operations, such as update_rom_note for edits.

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

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

Annotations already indicate destructive behavior, and the description adds valuable context: explicit confirmation is required, and ROM files are untouched. This goes beyond the structured hints without contradicting them.

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

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

A single, well-structured sentence leads with the core action, states the confirmation requirement, and clarifies the non-destructive scope regarding ROM files. No unnecessary words or repetition.

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

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

The description covers the essential behavior for a destructive operation, including confirmation and safe handling of ROM files. With an output schema present and annotations already marking destructiveness, the remaining minor gap is not explicitly stating how confirmation is represented in the call.

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 links 'explicit confirmation' to the confirm parameter and 'smart collection definition' to the target resource, but it does not explicitly name the parameters or explain that confirm must be set to true to proceed.

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

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

The description clearly states the action ('Delete'), the resource ('smart collection definition'), and a crucial boundary ('does not delete ROM files'). This distinguishes it from sibling tool delete_collection, which targets regular collections, and from destructive ROM operations.

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 the intended use: delete a smart collection definition while preserving ROM files. It also conveys the prerequisite of explicit confirmation. However, it does not explicitly name alternatives like delete_collection or state when to choose one over the other.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'compact' and 'normal' as behavioral context, but does not explain what 'compact' means or what the response includes. With rich annotations, this is adequate but not exceptional.

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 with no filler words. It is appropriately sized for a simple getter tool, though the terms 'compact' and 'normal' could have been clarified without much added length.

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 one-parameter read-only getter with rich annotations and an output schema, the description is largely sufficient. The 'normal' qualifier helps distinguish from smart collections, and the output schema covers return shape. The only minor gap is the unexplained 'compact' behavior, but this does not prevent 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%, so the description carries the burden of explaining the parameter. It does not explicitly describe collection_id or how it selects the collection; the schema's title 'Collection Id' is the only semantic signal. 'Get one' only weakly implies that collection_id identifies which collection to fetch.

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 verb ('Get'), a clear resource ('one ... RomM collection'), and adds the qualifiers 'compact' and 'normal,' which help distinguish this from list_collections and get_smart_collection. It is not a tautology and conveys the core action, though it does not explicitly contrast with its siblings.

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

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

The phrase 'one compact normal RomM collection' implies use when fetching a single normal collection by ID, as opposed to listing collections or retrieving a smart collection. There is no explicit guidance on when to use this tool versus get_smart_collection or list_collections, leaving some inference 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'compact' as a behavioral trait of the response, which is useful but minimal beyond what annotations provide.

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

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

One sentence that front-loads the verb and resource, includes the key distinguishing detail ('compact', 'internal ID'), and contains zero filler. 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 single-parameter read operation with an output schema and rich annotations, the description is nearly complete. It does not mention not-found behavior or how to obtain a valid platform_id, but those are minor gaps given the tool's simplicity.

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. The phrase 'by internal ID' clarifies that platform_id is an internal identifier rather than a user-facing slug or name, adding meaning beyond the raw schema. With a single self-explanatory integer parameter, this is sufficient.

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

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

The description uses a specific verb ('Get'), a resource ('RomM platform summary'), and a clear lookup key ('by internal ID'). This distinguishes it from list_platforms, which fetches a collection, and from get_rom, which targets 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?

The description implies usage: call when you have a platform's internal ID and need a compact summary. However, it does not explicitly state when not to use it or mention alternatives like list_platforms to discover IDs, leaving the selection logic partially 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add beyond safety. It does add behavioral scoping: the returned view excludes provider internals, filesystem details, hashes, and credential URLs, which is useful context for what the agent will receive.

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?

One concise sentence with no filler. The action and key exclusions are front-loaded, so the description is easy to scan and 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 single-parameter read-only getter with an output schema, the description is nearly complete. It could add guidance on how to find rom_id or when to prefer list_roms, but the annotations and output schema cover most operational needs.

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 does not explain rom_id provenance, format, or how to obtain it. With only one parameter, the description could easily compensate, but it 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 and resource: 'Get one bounded ROM view.' It also explicitly scopes out provider internals, filesystem details, hashes, and credential URLs, which distinguishes it from lower-level or listing tools like list_roms.

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 this is for retrieving a single bounded ROM view rather than listing or getting internals, but itname does not name an alternative tool or provide when-to-use versus when-not-to-use guidance. The usage must be inferred from the word 'one' and the 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds little beyond the annotations; 'bounded' is ambiguous and no behavior such as not-found handling, access requirements, or open-world implications is disclosed.

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

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

The description is a single short sentence with no filler, which is good for front-loading. However, the word 'bounded' is vague and does not earn its place, so the sentence sacrifices clarity for 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?

For a one-parameter read operation with an output schema and safety annotations, the description is nearly sufficient. It omits explicit retrieval semantics and alternative routing, and the ambiguous 'bounded' leaves room for misinterpretation.

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 parameter, but it does not explain collection_id beyond what the parameter name and title already suggest. It fails to state that collection_id identifies the single smart collection to retrieve.

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

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

The description uses a specific verb ('Get') and a specific resource ('RomM smart collection') and says it returns one item, which separates it from list-style siblings. It does not explicitly distinguish get_smart_collection from get_collection, but the resource names themselves do.

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?

No guidance is provided about when to choose this over list_smart_collections, get_collection, or other siblings. The singular 'one' weakly implies a fetch-by-ID scenario, but there are no explicit conditions or alternatives.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful response-scope context by clarifying that authorization and UI/device details are excluded, which is not present in the annotations.

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

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

The description is a single, front-loaded sentence that communicates the core purpose and an important exclusion without any 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?

For a simple single-parameter read-only getter with an output schema, this description is complete enough: it identifies the resource, states what is returned, and declares meaningful exclusions. Annotations fill in the safety profile.

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 does not mention user_id at all. While the parameter name is self-explanatory, the description provides no added meaning or compensation for the missing param documentation.

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

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

The description uses a specific verb and resource: 'Get minimal RomM user identity.' It also states clear exclusions ('authorization and UI/device details are excluded'), which helps distinguish this from list_users or other user-related 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?

Usage context is implied: this is the tool to use when you need a single user's minimal identity. However, it does not explicitly mention alternatives or when not to use it, leaving some routing judgment 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 provide read-only and idempotent hints, and the description adds the important behavioral guarantee that only non-sensitive identity data is returned. This is consistent with the annotations and gives an agent useful privacy and scope information.

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 sentence with no filler words. The core action and the non-sensitive scope are front-loaded and directly useful for selecting and invoking 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?

For a parameterless health check with read-only annotations and an output schema, the description covers all necessary selection and invocation context. It explains what the tool verifies and what it returns, with no missing prerequisites or caveats.

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 is empty with zero parameters, so there is nothing for the description to clarify. The baseline for no parameters is 4; the description does not need to add parameter guidance.

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

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

The description uses a specific verb and resource ('Verify authenticated RomM API access') and states the precise outcome ('return non-sensitive connectivity identity only'). Among the siblings, all are CRUD operations, so this clearly identifies health as the connectivity/auth check 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?

The description clearly identifies the tool's use case: verifying authenticated access and getting a safe connectivity identity. It doesn't explicitly name alternatives or exclusions, but no sibling performs a health check, so the intended context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the 'compact' behavior, indicating the response is a condensed representation, but gives no further detail about pagination, ordering, or response structure. This is acceptable given the annotation coverage.

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, efficient sentence. Both modifiers ('compact' and 'normal') add meaning and the sentence is front-loaded with the action verb 'List'.

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-only listing tool with an output schema present, the description covers the essential selection information. The only minor gap is that 'compact' is not defined, but the output schema likely clarifies the return format.

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 zero parameters, so the baseline is 4. There are no parameter semantics to explain; the description correctly focuses on the operation itself.

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

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

The description uses a specific verb ('List') with a clear resource ('RomM collections') and adds the qualifier 'normal' to distinguish from smart collections. This effectively differentiates the tool from list_smart_collections without needing to open 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 term 'normal' implies this tool is for regular collections, not smart collections, but it never explicitly states when to use this tool versus list_smart_collections or other listing tools. Usage context is inferable but not directly spelled out.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context about compact output and token-visible scope, going modestly beyond the structured 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?

A single, front-loaded sentence with no filler. Every phrase contributes meaning: list, compact, platform summaries, visible to the token.

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 parameters, an output schema present, and rich annotations covering safety and idempotence, the description supplies the remaining necessary context: resource type, scope, and output compactness. Nothing critical 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?

The tool has zero parameters, so there is no parameter detail for the description to add beyond the empty schema. This earns the baseline score for no-parameter tools.

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?

Description states a specific verb and resource: 'List compact RomM platform summaries'. It is clearly distinct from get_platform and other sibling tools, and the qualifier 'visible to the token' adds scope.

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 an auth-scoped listing operation and makes clear it returns summaries, not full platform details. It does not explicitly name get_platform as the alternative for single-platform lookups, but the usage context is sufficiently clear.

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 readOnly, openWorld, idempotence, and non-destructiveness. The description adds useful context beyond those by clarifying that results are bounded summaries and that device/sync internals are deliberately omitted, which helps set caller expectations about the response shape and scope.

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, well-structured sentence that front-loads the core action and resource. Every phrase adds meaning: 'bounded', 'summaries', 'for the token owner', and 'without device/sync internals' all contribute without redundancy.

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

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

Given the low complexity, robust annotations, and presence of an output schema, the description covers the essential purpose and scope. It could add an explicit note about when to prefer this tool over others, but that is not strongly needed here since no sibling play-session tool exists.

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 for the undocumented limit and offset parameters. It only hints at boundedness without explaining how limit/offset control pagination or what values are expected, leaving the agent with minimal semantic guidance.

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 ('List'), a specific resource ('bounded play-session summaries'), and a precise scope ('for the token owner'). It also explicitly excludes 'device/sync internals', which differentiates it from lower-level data tools and makes the tool's purpose unambiguous.

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

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

The phrase 'for the token owner' gives clear context about whose data this returns, and 'without device/sync internals' acts as an implicit exclusion if internal details are needed. There are no direct sibling play-session tools, so explicit alternative routing is less necessary.

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 disclose read-only, idempotent, and non-destructive behavior. The description adds a meaningful behavioral constraint: the result list is capped at 100 notes, which is not expressed in the schema. It does not mention ordering or pagination, but the cap plus the annotation coverage provide solid transparency.

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?

Single sentence with no filler and the key constraint ('up to 100') front-loaded. It is appropriately sized for the tool's simplicity.

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

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

The tool is simple: one required parameter, a bounded result set, and rich annotations covering safety. The output schema exists, so return value documentation is not required. The only missing details are ordering or pagination behavior, which are minor for a bounded list operation.

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 needs to compensate. It relates rom_id to the ROM through the phrase 'attached to a ROM', but it does not explain how the id should be obtained, what the integer represents, or any edge cases. With only one obvious integer parameter, the gap is minor but still uncompensated.

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'), a clear resource ('notes attached to a ROM'), and an output bound ('up to 100'). This clearly distinguishes the read-only note-listing operation from the sibling create/update/delete_rom_note 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?

The description implies the use case is retrieving notes for a particular ROM, and the readOnlyHint supports non-mutating use. However, it does not explicitly state when it should be used instead of alternatives, nor give any exclusions or conditions. Usage must be inferred from the tool name and sibling context.

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 establish read-only, idempotent, non-destructive behavior. The description adds behavioral context beyond that by mentioning bounded pagination and a compact response that excludes provider-internal fields, which informs the caller about output shape and limits. The phrasing is somewhat vague but still provides useful extra transparency.

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 states the primary purpose first. 'Provider-internal-free' is awkward jargon and slightly hurts readability, but overall the description is compact and avoids redundancy with the schema.

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 ight parameters and a rich filter set, this description is under-specified. It does not explain filter semantics, the meaning of matched/missing/favorite, ordering behavior, or pagination bounds. An output schema exists, but input semantics are largely left to an agent to infer from parameter names alone.

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 for parameter meaning. It only vaguely relates to limit/offset through 'bounded pagination' and to search_term through 'Search', but leaves the other 11 parameters such as matched, missing, favorite, platform_ids, collection_id, smart_collection_id, and ordering controls semantically 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 opens with a specific verb and resource: 'Search/list ROMs'. It further clarifies scope with 'bounded pagination' and 'compact provider-internal-free response', setting expectations for a listing operation rather than a single-record fetch like get_rom. This distinguishes it clearly from sibling ROM-related 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?

The description implies use for searching and listing ROMs, which gives a clear general context. However, it does not explicitly state when to prefer this tool over alternatives such as get_rom, nor does it provide exclusions or conditions under which another tool should be used.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds little beyond the word 'compact' and an unclear schema-related phrase; it does not contradict the annotations.

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

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

The description is a single concise sentence with the main verb and resource front-loaded. The phrase 'with only the explicit supported filter schema' is somewhat awkward and adds limited clarity, costing it a top score.

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 list operation with an output schema and safety annotations, the description is largely sufficient. It could briefly mention that get_smart_collection provides full details or how 'compact' differs from the full representation, but those gaps are minor.

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 and the schema coverage is 100%, so there is nothing for the description to document. Baseline for 0-param tools is 4, and no parameter guidance is needed.

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

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

The description clearly states the action ('List') and resource ('RomM smart collections'), and 'compact' suggests a limited field set. It is distinguishable from list_collections and get_smart_collection, though it does not explicitly name those 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?

No guidance is provided on when to use this tool versus list_collections, get_smart_collection, or other collection tools. The phrase 'with only the explicit supported filter schema' is ambiguous and does not clarify selection criteria.

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 operation read-only, idempotent, and non-destructive. The description adds useful behavioral context by stating the response is intentionally minimal and enumerating excluded fields, which helps set expectations beyond the schema.

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 sentence with the primary purpose front-loaded, followed by a compact list of exclusions. Every word adds value, with no redundancy or unnecessary detail.

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 parameterless, read-only list operation with annotations and an output schema already present, the description provides all necessary context: what is returned, why, and what is intentionally omitted. Nothing important 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?

The tool has zero parameters, so there is nothing for the description to explain beyond the schema. A baseline score of 4 is appropriate for a parameterless tool with full schema coverage.

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 ('List') and resource ('users') and further clarifies that it returns minimal user identity for follow-up calls. The explicit list of excluded fields distinguishes it from a full user retrieval tool like get_user.

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

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

The description clearly signals when to use the tool: when minimal user identity is needed for follow-up calls. It does not explicitly name get_user as the alternative for fuller user details, but the context and exclusions make the usage boundary reasonably clear.

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 and destructiveHint=false, so the operation is known to be a non-read-only, non-destructive write. The description adds meaningful specificity: the effect is limited to removing ROM-collection associations, not deleting ROM entities. This goes beyond what the annotations convey about the scope of the write.

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 sentence with no filler. The core action is front-loaded, and the clarifying 'without deleting ROMs' is placed immediately after, making the sentence both efficient and informative.

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 two-parameter write operation, the description plus schema plus annotations give enough information for an agent to invoke it correctly: purpose is clear, parameter names are self-descriptive, and an output schema exists so return values need not be documented. Missing are explicit usage guidance versus siblings and behavior on partial or invalid ROM IDs, but these are minor for this tool's simplicity.

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 adds no parameter-level detail beyond paraphrasing the names (collection, ROM IDs). It does not explain that rom_ids is an array that can contain multiple integers, that both parameters are required, or any constraints or validation behavior. The schema provides types and requiredness, but the description fails to compensate for the absent parameter documentation.

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?

Description states a precise action ('Remove ROM IDs from a collection') and explicitly clarifies the non-destructive scope ('without deleting ROMs'), distinguishing it from delete_collection and aligning it as the inverse of add_roms_to_collection. The verb and resource are specific and unambiguous.

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

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

The description implies the use case: modifying a collection's membership rather than deleting the collection or the ROMs themselves. However, it does not explicitly name alternative tools or state when to prefer this over delete_collection or add_roms_to_collection, leaving the guidance 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 communicate the mutation safely: readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds a useful scope constraint, 'without artwork changes,' but does not disclose whether updates are partial/merge semantics, whether rom_ids replaces or modifies membership, or whether null values clear fields. These are meaningful behavioral gaps.

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 with no filler. Every word adds scope and purpose, making it easy for an agent to parse quickly.

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

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

For a mutation tool with five parameters and no schema-level descriptions, the description is too thin. It omits update semantics, membership replacement behavior, and how this relates to the add/remove-roms sibling tools. The existence of an output schema reduces the need to document return values, but the missing usage and semantics are still significant.

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, but it only gestures at 'metadata/membership.' It does not explain what collection_id targets, how rom_ids behaves, or whether omitted versus null parameters differ. The parameter names carry most of the meaning, leaving important semantics undocumented.

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 begins with a specific verb and resource, 'update collection', and narrows the scope to 'metadata/membership without artwork changes.' This clearly distinguishes it from rom-focused tools and create/delete collection operations, though it does not explicitly contrast with update_smart_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?

There is no guidance about when to use update_collection versus sibling tools like add_roms_to_collection, remove_roms_from_collection, or update_smart_collection. The phrase 'without artwork changes' is a scope restriction, not a selection criterion.

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

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

Annotations already indicate a non-read-only, non-destructive mutation. The description adds the scope constraint that only bounded text metadata is affected and explicitly excludes asset fetch/write and provider-ID mutation. It doesn't explain null-clearing behavior, partial updates, or open-world side effects, so it adds some but not rich behavioral 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?

One efficient sentence that front-loads the action and scope. The semicolon cleanly separates the core statement from the boundary exclusions, with no unnecessary filler.

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

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

The description leaves important gaps: no alternative routing, no partial-update/null semantics, and no acknowledgment of openWorldHint. The schema lists fields, but the agent still cannot confidently determine when this tool is appropriate versus update_rom_user_properties or how null values are handled.

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 categorizes fields as 'bounded text metadata' and doesn't explain the semantics of nulls/defaults or whether omitted optional fields leave values untouched. This adds little meaning beyond the schema's property titles.

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?

Description uses a specific verb 'Update' and scopes it to 'bounded text metadata', explicitly excluding asset fetch/write and provider-ID mutation. This makes the operation reasonably clear, though it doesn't name the exact fields or differentiate from update_rom_user_properties, so it falls 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 description provides useful boundary guidance: only text metadata, never asset operations or provider-ID changes. However, it doesn't explicitly state when to use this tool instead of alternatives like update_rom_user_properties, leaving the agent to infer routing from tool names.

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

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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds one useful behavioral detail: only explicitly supplied fields are updated. However, it does not disclose what happens to omitted fields, whether explicit nulls clear values, or any error/validation 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 short and front-loaded with the action, but the wording 'only the explicit fields supported by RomM notes' is vague and somewhat redundant. It is concise but not as informative as it could be in the same space.

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 six-parameter mutation tool with 0% schema description coverage and no parameter-level documentation, this description is too sparse. The presence of an output schema reduces the need to describe return values, but the missing usage guidance and parameter semantics leave significant gaps for an agent deciding how and when to call the 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%, and the description names none of the six parameters. The phrase 'only the explicit fields' adds generic partial-update semantics, but the description does not compensate for the lack of parameter documentation by explaining rom_id, note_id, tags, title, content, or is_public.

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 clear verb ('Update') and resource ('RomM notes'), which is enough to distinguish this tool from note creation/deletion/list siblings and from ROM metadata tools. However, it doesn't explicitly say 'existing note' or explain what 'explicit fields' means, so it falls just short of full clarity.

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 about when to use this tool versus create_rom_note, delete_rom_note, or update_rom_metadata. The verb 'Update' and required note_id imply the tool targets existing notes, but no explicit when-to-use or when-not-to-use 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 indicate a write operation that is non-destructive and not read-only, so the safety profile is covered. The description adds the useful scope that updates are limited to the token owner's properties, but it does not disclose partial-update behavior, null semantics, or response details.

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?

Single sentence with no filler; the operation, resource, and scope are front-loaded. 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 tool with seven mostly-optional properties, an existing output schema, and annotations covering safety, the description supplies the essential owner-scoped intent. It does not specify update semantics for omitted fields, but the schema and output schema cover the remaining invocation details.

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 needed to compensate, but it only names three property categories (status/rating/completion) and omits hidden, backlogged, and difficulty. It adds the owner-scoped interpretation, but leaves several parameters dependent on self-explanatory names and schema enums.

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 operation ('Update'), a precise resource ('personal ROM status/rating/completion properties'), and an authentication scope ('for the token owner'). This clearly differentiates it from the sibling update_rom_metadata, which targets shared ROM metadata rather than owner-specific 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?

It gives clear context: use this tool for personal, owner-scoped ROM fields, not for general ROM data. It does not explicitly enumerate when-not conditions or alternatives, but the 'personal/token owner' framing is enough to route an agent correctly.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) are not contradicted by the description — 'update' implies mutation consistently. However, the description adds no behavioral context beyond the annotations: it does not disclose whether filter_criteria is replaced wholesale or merged, whether changes apply immediately, or what side effects might occur.

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 words cannot be called concise in the meaningful sense; this is under-specification. A single sentence that merely echoes the tool name earns no structural credit.

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?

This is a mutating tool with5 parameters including a ~37-field nested SmartCollectionFilterCriteria object,0% schema coverage, and a thin annnotation set. The description is far too sparse for an agent to know what to pass, how the update semantics work, or how this differs from update_collection.

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% — none of the5 properties (name,is_public, description, collection_id, filter_criteria) have descriptions,and the description does not compensate. It does not even hint that collection_id is required or that filter_criteria carries the meaningful update payload.

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 'Update a smart collection' is a word-for-word restatement of the tool name — the only addition is the article 'a'. It identifies the verb and resource but gives no detail about what is updatable (name, visibility, description, filter criteria) and does not differentiate 'smart' collections from the sibling update_collection 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?

No when-to-use guidance, no exclusions, and no mention of alternatives. With siblings like create_smart_collection, delete_smart_collection, and update_collection, an agent gets nothing to help route between them.

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