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

Annotations already declare a non-readonly, non-destructive, open-world write, so the safety profile is covered. The description adds only that the note lands in the asset's activity log (an append/audit hint), but omits auth/permission needs, whether notes are editable, and what is returned.

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 action and target are stated first. It is efficient, though extremely terse for a mutating 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 simple 3-param append operation with no output schema, the description is minimally viable, but two required parameters are undocumented and the note's visibility/lifecycle is unexplained. It does enough to call the tool correctly but little more.

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 only 33% – orgId is documented but the two required parameters, assetId and content, have no descriptions. The description does not compensate, adding no detail about note content limits (beyond minLength 1) or assetId format.

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 note to an asset's activity log.' An agent can immediately tell this appends a note versus e.g. updating the asset itself. There is no sibling note tool to disambiguate against, so no explicit differentiation is needed.

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, prerequisites, or alternative guidance. It reads as an obvious operation but the description never states when a note is appropriate versus, say, shelf_update_asset or shelf_assign_custody, nor whether the note is user-visible.

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, and openWorldHint=true, so the safety profile is partly covered. The description adds one genuinely useful constraint — that the asset must be quantity-tracked — but says nothing about permission needs, whether the adjustment is reversible/audited, or how direction and quantity interact.

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, but it is arguably under-specified for a 6-parameter mutation rather than truly optimized.

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, low schema coverage, and only minimal annotations, the description should carry more weight than one sentence. An agent lacks the details needed to know how to combine direction, quantity, and category correctly, or what a successful adjustment returns.

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 only 17% (only orgId is documented), leaving assetId, quantity, direction, category, and note bare. The description's 'restock, correction, or loss' hints at the category enum but does not explain direction ('add'/'subtract'), the quantity>0 constraint, or the note field, so 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 a specific verb (Adjust) and resource (stock of a quantity-tracked asset) with the three motivating intents in parentheses. No sibling tool performs quantity adjustment, so the scope is distinguishable, though it doesn't explicitly name a contrast case.

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 parenthetical 'restock, correction, or loss' implies the situations that motivate the call and maps loosely to the category enum, but there is no explicit when-not or guidance on choosing between the categories or handling direction.

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, covering the safety profile. The description adds the precondition that only completed/cancelled bookings are eligible, but says nothing about what archiving actually does (soft vs hard removal), 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?

A single front-loaded sentence with no wasted words. It is efficient, though the brevity comes at the cost of the guidance and behavioral detail noted elsewhere.

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 mutating tool with no output schema and only half the parameters documented, the description is thin. It omits the effect of archiving, the alternative siblings, and details about the undocumented required bookingId, so an agent lacks enough 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 coverage is only 50%: orgId has a description (defaulting to SHELF_ORG_ID/current workspace) while bookingId has none. The description contributes no additional parameter meaning, leaving the required bookingId undocumented in both description and 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?

The description states a specific verb (archive) and resource (booking) and adds a state qualifier (completed/cancelled). It is clear what the tool does, but it does not differentiate itself from sibling tools like shelf_delete_booking or shelf_cancel_booking, which occupy adjacent conceptual space.

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 explicit when-to-use guidance. The description implies archiving applies to completed or cancelled bookings but never states when an agent should choose this over cancel_booking, delete_booking, or simply leaving the booking as-is.

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 readOnlyHint=false and destructiveHint=false, so the agent knows this mutates but is non-destructive. The description adds value by clarifying the quantities payload for quantity-tracked assets, but says nothing about permissions required, whether it overwrites existing custody, or what happens to partially-tracked items.

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 the core action front-loaded and the parameter nuance second. Nothing is wasted, though the quantities clause is slightly jammed in without clear separation from the main action.

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-param mutation tool with a nested quantities object and no output schema, the description covers the tricky nested parameter but leaves permissions, overwrite behavior, and return expectations unaddressed. Adequate but with real gaps for a custody-changing 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 coverage is only 50%: assetIds and quantities have no schema descriptions. The description does compensate for the opaque nested quantities parameter by specifying the {assetId: qty} shape, but assetIds and the overall ID format remain undocumented, so it only partly fills the 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 ('give into custody') and resource ('one or more assets'), and implies the custodian is a team member. It reads clearly, but it never names its counterpart shelf_release_custody or otherwise differentiates itself from the release path beyond intuition.

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 explicit when-to-use/when-not guidance and no mention of shelf_release_custody as the inverse operation. The only guidance is a fragment about quantity-tracked assets, which is closer to parameter help than usage routing.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond them: the availability/time-window notion is already expressed by the required bookingFrom and bookingTo schema fields, and pagination behavior, default page size, and how availability conflicts are computed are all undisclosed.

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, tightly front-loaded sentence with zero filler or redundancy. It is efficient, though arguably undersized for a seven-parameter tool, which is captured under contextual completeness rather than here.

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 seven-parameter availability query with no output schema, the description leaves major gaps: it does not explain the search parameter, pagination defaults, the bookingId inclusion rule, or the relationship to the sibling listing tools. The schema covers most fields, but the description does nothing to complete the picture an agent needs to call 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 86%, so the schema already documents page, perPage, orgId, bookingId, and the ISO date params. The description contributes no additional meaning for any of the seven parameters, so the baseline 3 applies.

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 phrase 'Assets available for booking in a given period' identifies the resource and the scoping window, but it is a noun phrase with no verb, so it never says it is a list/query operation. It also does not distinguish this from the sibling shelf_list_assets or shelf_booking_add_assets, leaving the agent to infer the difference.

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, when-not-to-use, or alternative is named. An agent cannot tell from the description whether this should be preferred over shelf_list_assets when checking availability, nor what happens if bookingFrom/bookingTo are omitted or cover a partial period.

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-read-only, non-destructive, open-world mutation, so the safety profile is covered. The description adds nothing behavioral: no indication of whether assets must be available, whether quantities/availability are affected, whether reserved bookings are allowed, or what happens on partial 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?

A single front-loaded sentence with zero filler, and the target resource appears immediately. It is arguably under-specified rather than wasteful, which is a completeness issue rather than a conciseness one.

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 with no output schema and 25% schema coverage, the description is far too thin: it does not say what state the booking must be in, what the effect on booking contents or availability is, or what the caller gets back. Only the core intent is conveyed.

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 only 25% — bookingId, kitIds, and assetIds have no schema descriptions. The phrase 'assets and/or kits' hints that assetIds and kitIds are the payload and may be combined, but the description adds no format, defaults, or ID-sourcing context for the two undocumented array parameters.

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 assets and/or kits to a booking') and covers both addable entity types in one clause. It does not explicitly name the inverse sibling shelf_booking_remove_assets, but the resource scope 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?

No when-to-use guidance, no preconditions (booking must exist, must not be checked out/archived/cancelled), and no routing against siblings such as shelf_create_booking, shelf_reserve_booking, or shelf_booking_remove_assets. The agent must infer all selection logic 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond the action itself, such as whether removing an asset from a booking affects booking status, what happens with invalid IDs, or whether the operation is reversible.

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 extraneous words. It delivers the core purpose efficiently.

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

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

Given the tool is a mutation with no output schema and low schema description coverage, the description is too sparse. It omits prerequisites (e.g., booking must exist), parameter semantics for three of four parameters, and any behavioral details an agent would need to invoke 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 only 25%, with just orgId documented. The description implies that assetIds and kitIds can be specified ('assets and/or kits') and that bookingId is the target ('from a booking'), but it does not name the parameters, clarify that both arrays are optional, or explain orgId defaults or the required bookingId.

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 (Remove), resource (assets and/or kits), and scope (from a booking). This clearly distinguishes it from siblings like shelf_booking_add_assets and shelf_kit_remove_assets, which operate on different resources or directions.

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 no explicit guidance on when to use this tool versus alternatives such as shelf_booking_add_assets or shelf_kit_remove_assets. It merely restates the action, leaving the agent to infer usage context and prerequisites.

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 the 'overlapping' semantics (vs. fully-contained ranges), a genuine behavioral detail, but says nothing about pagination, result ordering, or return 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?

A single front-loaded sentence with no wasted words. It is appropriately terse for a simple read tool, though it is arguably under-specified rather than optimally 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 filtered-list tool with no output schema and 80% schema coverage, the essentials are present. But the description omits any routing guidance against shelf_list_bookings and does not explain how search/statuses interact with the date range.

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 80%, so the schema already documents start, end, orgId, and statuses. The description's 'ISO 8601 dates' merely restates the schema's 'ISO date/time' and adds no syntax or format meaning beyond it. Baseline 3 applies.

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 (bookings) and scope (overlapping a date range), so the agent knows what it retrieves. However, it offers no differentiation from the very close sibling shelf_list_bookings, leaving ambiguity about which to pick.

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 explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as shelf_list_bookings. Usage is only implied by the phrase 'overlapping a date range'.

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=false, destructiveHint=false, openWorldHint=true), yet the description adds nothing beyond them. For a bulk mutation it says nothing about partial-failure behavior, whether the move is atomic, per-asset error reporting, or permission requirements — exactly the context annotations cannot 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?

A single front-loaded sentence with zero padding, which is the right size for a simple batch operation. The terseness is a coverage problem, not a structural one.

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, no parameter documentation for two required fields, and a bulk mutation whose failure semantics are unstated, the definition leaves meaningful gaps an agent would need in order to call it reliably.

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 only 33% (only orgId is documented), so the description carries the burden for assetIds and locationId. 'Several assets' and 'one location' loosely map to the two required params, but no format, ID shape, or constraint detail is added.

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) and resource (assets to a location), and the word 'several' signals the bulk scope that separates it from the single-asset sibling shelf_update_asset_location. It does not name that sibling explicitly, so sibling differentiation is implied rather than stated.

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 plural 'several assets' implies this is the batch variant to use when moving more than one asset, but the description never states when to prefer it over shelf_update_asset_location or what preconditions apply (e.g. location must exist). Usage is inferable but not 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 flag destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no mention of irreversibility, downstream effects on attached assets, 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?

The sentence is short and front-loaded with the action, with zero waste. The problem is under-specification rather than verbosity, so it earns a middling score rather than a high one.

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 unnamed required parameters, no output schema, and no usage or behavior context, the definition is too thin. An agent cannot tell what happens on success, whether the booking's assets are released, or why this differs from archive/delete.

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 only 33%: bookingId and cancellationReason are undocumented in the schema, and the description adds no meaning for any parameter. With three parameters and low coverage, the description fails to compensate for the 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 verb 'cancel' and the resource 'booking', so the core action is clear. However, it gives no differentiation from closely related siblings like shelf_archive_booking, shelf_delete_booking, or shelf_release_custody, which is exactly where an agent needs disambiguation.

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 is provided. The description does not say how cancelling differs from archiving or deleting a booking, nor whether it requires specific booking states, so the agent must infer usage purely 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?

Annotations already declare this is a non-read-only, non-destructive, open-world operation. The description adds the meaningful scope detail that ALL assets in the booking are checked in at once, but says nothing about required permissions, whether the action is reversible, or what happens with already-returned assets.

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 short sentence, front-loaded with verb and resource, with zero filler. Every token contributes to selection or scoping.

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 state-changing booking operation with no output schema, the definition covers the core action but omits the preconditions and outcome semantics an agent needs (must the booking be checked out? what state results?). Annotations carry the safety profile, so the gap is moderate rather than severe.

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 67%, with orgId and timeZone documented but bookingId bare. The '(all assets)' note slightly clarifies the semantics of the booking reference, but the description adds no format, constraint, or default information beyond the 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?

Specific verb ('check in') plus resource ('booking'), with scope qualifiers ('ongoing/overdue', 'all assets'). It is distinguishable from the inverse sibling shelf_checkout_booking, though it never names or contrasts with any sibling 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?

The phrase 'ongoing/overdue booking' implies the eligibility condition for use, but there is no explicit when-to-use guidance, no prerequisites (e.g. booking must already be checked out), and no named alternative for the reverse operation.

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, and openWorldHint=true. The description adds that it checks out all assets and that the booking must be reserved, but it does not explain side effects such as status transitions, permissions, or whether the operation is reversible.

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 wasted words. It is appropriately terse for a simple mutation, though the brevity contributes to gaps in other dimensions.

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 no output schema and moderate schema coverage, the description is too thin. It omits what happens to the booking status, what happens to individual assets, required permissions, and any return information, relying almost entirely on annotations for safety 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?

Schema coverage is 67%, and the required bookingId parameter has no schema description. The description does not mention any parameters or add syntax/format meaning beyond what the schema provides, leaving the key required parameter under-documented.

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 ('Check out') and resource ('booking'), plus the scope ('all assets') and precondition ('reserved'). This distinguishes it from siblings like shelf_checkin_booking and shelf_reserve_booking, though it does not explicitly name them.

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 'reserved booking' implies the tool should be used only after a booking has been reserved, but it gives no explicit when-not guidance or alternative tool names for related operations like check-in, cancel, or reserve.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds one operational constraint — that category/location/tag/custom-field values are IDs that must be resolved first — but says nothing about permissions, whether the asset is immediately visible/claimable, or what happens on 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 short sentences, zero filler, with the core action front-loaded ahead of the prerequisite. Efficient, though terse enough that it leaves obvious gaps rather than being a model of well-budgeted conciseness.

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 9-parameter write tool with no output schema and only 33% schema coverage, the description is thin: it never mentions the one required field (title), the orgId default, or what a successful call yields. Annotations and the schema cover enough that an agent can still call it, but the definition is only minimally 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 only 33% across 9 parameters, so the description must compensate. It partially does by naming four of the parameters (categories, locations, tags, custom fields) and clarifying they take IDs, but title, valuation, description, and categoryId/locationId semantics remain undocumented in both places.

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 ('Create a new asset'), which is unambiguous and clearly distinct from shelf_update_asset and shelf_delete_asset in the sibling list. It stops short of any explicit sibling differentiation, but the verb alone is enough to route correctly.

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 a concrete prerequisite: look up IDs via shelf_list_categories/locations/tags/custom_fields before calling. This names four specific alternative tools and the condition that selects them. It omits any when-not-to-use guidance (e.g., for bulk creation or kits), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds the genuinely useful behavioral fact that creation results in a DRAFT rather than a confirmed booking, which is not encoded in the schema or annotations. It does not mention permission or validation behavior, so it is not a full 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 tight sentences, front-loaded with the action and state, followed by the sequencing instruction. 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?

No output schema exists, and the description says nothing about the returned booking or required-field expectations, though annotations cover the safety profile. For a 9-parameter creation tool the description is adequate as a routing cue but leaves the agent relying entirely on the schema for inputs and return shape.

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 67%, below the 80% threshold at which the schema would carry the burden, and the description adds no parameter meaning at all. Nine parameters (name, tags, assetIds, dates, custodianTeamMemberId, timeZone, orgId) are left entirely to the schema, so the description does not compensate for the uncovered third.

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 ('Create a booking') and adds the lifecycle state ('as DRAFT'), which clearly separates it from sibling booking tools. It names shelf_reserve_booking as the follow-up, so an agent can tell this tool does not reserve. Slightly short of a 5 only because the crowded set of shelf_*_booking siblings (duplicate, update, checkout) is not otherwise differentiated.

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: create here, then call shelf_reserve_booking to reserve. This tells the agent when this tool is the right first step in the workflow. No exclusions or preconditions (auth, availability checks) are stated, keeping it from a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the write/open-world profile is covered. The description adds that the call returns the created kit and that asset inclusion can happen at creation time, but says nothing about required permissions, validation failures, or the effect of omitted orgId.

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, and the core action is front-loaded. It is arguably terse to the point of under-specification, which caps it below 5.

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

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

For a 7-parameter mutation tool with no output schema and low parameter documentation, the description is thin. It does tell the agent a kit object is returned, but not enough about the optional parameters or mutation behavior to call this 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?

With only 43% schema description coverage across 7 parameters, the description is expected to compensate but does not. It only gestures at assetIds/quantities via 'filled with assets', leaving orgId, categoryId, locationId, and the quantities semantics entirely to the 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 and resource ('Create a new kit') and adds scope ('optionally filled with assets right away'), which distinguishes it from shelf_kit_add_assets in spirit. However, it never names siblings or clarifies when to create-with-assets versus create-then-add, so it stops 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 explicit when-to-use or when-not-to-use guidance and no named alternative. The phrase 'optionally filled with assets right away' faintly implies the create-empty-then-add path, but the agent must infer it.

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, and openWorldHint=true, so the safety profile is covered. The description adds nothing on top: no mention of whether duplicate tag names are rejected, whether the call is idempotent, what the created tag looks like, or any auth requirement.

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 filler, which is efficient. It is arguably over-lean rather than poorly structured, so the sizing itself is not the defect.

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 should at minimum indicate what is returned (e.g., the new tag's ID/object) and how orgId scoping affects the result. For a creation tool it leaves the agent without the behavioral and return context needed to call 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 only 50% — orgId is documented in the schema, but the required 'name' parameter carries no description beyond minLength: 1. The description supplies no semantics for either parameter (e.g., uniqueness or naming rules), so 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?

The description states a clear verb+resource ('Create a new tag'), but it essentially restates the tool name shelf_create_tag and gives no signal to distinguish it from the many other create tools in the sibling set (create_asset, create_kit, create_booking). An agent knows what resource is targeted but not why this creator differs.

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 vs. alternatives — no mention of how tags relate to shelf_list_tags, whether tags are org-scoped, or when creating a tag is appropriate versus attaching existing ones. Nothing about preconditions or exclusions 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=true and openWorldHint=true, so the safety profile is covered. The description adds useful but shallow context about what the dashboard surfaces (counts, overdue items). It does not say whether the data is scoped per user vs. whole org or how fresh it is.

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 short, front-loaded sentence with no repetition. The trailing 'etc.' is slightly unhelpful but costs little; the definition is as tight as it can be while remaining this vague.

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 carries some burden for describing returns; it gestures at counts and overdue items but leaves the rest undefined. For a simple read-only aggregate with one optional param that is borderline acceptable, though the 'etc.' leaves a real gap.

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

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

Single optional orgId parameter with 100% schema description coverage, which already explains the SHELF_ORG_ID default. The description contributes nothing additional about the parameter, so the baseline 3 applies.

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 (a workspace dashboard) and enumerates some contents (asset/booking counts, overdue items), which no sibling tool provides. But there is no verb and the enumeration trails off with 'etc.', so the scope is only loosely delimited. An agent knows it's an aggregate summary view, but not exactly what it returns.

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 reach for this dashboard rather than the many listing tools (shelf_list_assets, shelf_list_bookings, shelf_bookings_calendar). No prerequisites, no exclusions, not even an implied trigger beyond 'workspace dashboard'. The agent must infer purpose 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 destructiveHint=true and readOnlyHint=false, so the bar is lower. The description still adds the stronger, operationally important claim that the deletion is irreversible and that user confirmation is required, which goes beyond the boolean hints.

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

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

Two short sentences, zero filler, with the destructive consequence front-loaded before the confirmation requirement. 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?

For a two-parameter delete whose safety profile is already carried by annotations, the description communicates enough to call it safely. The remaining gap is the undocumented required assetId and side effects on kits/placements/bookings, but the core risk disclosure is 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 coverage is only 50%: orgId is documented in the schema but assetId has no description in either place. The description adds nothing about identifier format, whether assetId must be a full ID vs. a code, or any constraints, leaving the required parameter's semantics 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 ('delete an asset') with the modifier 'Permanently' that separates it from softer siblings like shelf_update_asset or archive-style operations. It does not name a sibling directly, but the destructive scope 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?

'Confirm with the user first' gives one concrete precondition for invoking, which is more than most definitions offer. However, it does not say when to prefer this over alternatives (archive/update) or what happens if the asset is in a kit, booking, or placement.

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, so the description's job is to add context. It does: 'Permanently' and 'Irreversible' quantify the destructiveness beyond the boolean hint, and the confirmation instruction is actionable guidance not present in annotations. No return or error behavior is described.

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, zero filler, with the destructive nature front-loaded before the caution. Nothing could be trimmed without losing meaning.

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 tool with no output schema, the description covers the essential safety caveat. It leaves gaps on what happens to a booking's attached assets and whether the call errors on an unknown ID, which matters for an irreversible 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?

The description never mentions either parameter, and bookingId (the required one) has no schema description at all; only orgId carries documentation. With schema description coverage at 50% and the required parameter undocumented, the description should 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?

States a specific verb (delete) and resource (booking), with the qualifier 'Permanently' that implicitly separates it from shelf_cancel_booking and shelf_archive_booking in the sibling list. It does not name those siblings explicitly, so differentiation still requires the agent to infer from the adverb.

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?

'Confirm with the user first' gives one concrete precondition for invoking. However, it never states when to choose permanent deletion versus the sibling shelf_cancel_booking or shelf_archive_booking, which is the real routing question for this family of 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=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one meaningful behavioral fact — the result is a new *draft* rather than a confirmed booking — but says nothing about which fields are copied, whether the source is untouched, or the state of the duplicate.

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 filler, which is well structured. It is arguably too terse for a mutation tool, but nothing in it 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 and a required parameter that is undocumented in both the schema and description, the definition is only minimally complete. An agent knows what the tool produces (a draft) but not the new booking's identifier, copied fields, or whether the draft needs reserving/checkout afterwards.

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 only 50%: bookingId is required but has no description anywhere, and the description adds nothing about it. Only orgId is documented (in the schema itself), so the description fails to compensate for the undocumented required parameter.

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 (Duplicate) and resource (booking) plus the output form (a new draft), which is enough to distinguish it from shelf_create_booking or shelf_get_booking. It does not explicitly contrast itself with the sibling create/update tools, so it stops 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 guidance on when to duplicate versus creating a booking from scratch with shelf_create_booking, nor any prerequisite (e.g. the source booking must be visible/accessible, or that this does not modify the original). The agent must infer usage entirely.

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 naming the categories of data returned (custody, bookings, custom fields, quantities), but says nothing about permissions, empty-field behavior, or pagination.

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 parenthetical field list is the only elaboration and it earns its place by previewing the return payload. Slightly terse given the missing parameter context.

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 correctly compensates by enumerating the detail categories returned, and annotations cover the read-only nature. The only real gap is assetId semantics, which is left undocumented in both the schema and the description.

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 only 50%: orgId is documented in the schema but assetId has no description at all. The description does not compensate, giving no hint about the expected assetId format (ID vs code) or how orgId scoping interacts with it. With low coverage the description should carry more of this burden.

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 ('Get') and resource ('asset') and enumerates the detail categories returned (location, custody, bookings, notes, custom fields, quantities). This clearly distinguishes it from shelf_list_assets, which returns a collection rather than one asset's full record, though the description never names that sibling 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?

No when-to-use or when-not-to-use guidance is given. The requirement of an assetId implies it is for a single known asset, and 'full details' implies detail lookup rather than listing, but the agent is left to infer that against shelf_list_assets and shelf_lookup_code.

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 value by disclosing that the response includes assets and kits, but it says nothing about pagination, missing-booking behavior, or output 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?

A single short sentence with zero waste, front-loading the verb and resource. It is efficient, though arguably too terse to carry the required behavioral and parameter context.

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 partially compensates by noting assets and kits are returned, and annotations cover safety. However, the undocumented required bookingId parameter and absent usage/routing guidance leave the definition only minimally 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 only 50%: orgId is documented in the schema, but bookingId has no description. The description adds nothing about either parameter (e.g. ID format or what happens if orgId is omitted), so it fails to compensate for the undocumented required parameter.

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 (get) and resource (booking) and adds scope ('incl. assets and kits'). It is distinguishable from list-style siblings by the singular 'get', but the description never names the closest alternative (shelf_list_bookings) to confirm this is the single-booking lookup rather than a filtered list.

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 alternatives named. An agent must infer from the name alone that this is the ID-based single-booking retrieval versus shelf_list_bookings or shelf_bookings_calendar.

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 safe-read nature is covered. The description adds one genuinely behavioral detail beyond the annotations — that contained assets are included in the response — but says nothing about pagination, error behavior when a kit is missing, or permission 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?

A single short sentence with zero filler and the key payload (contained assets) front-loaded. It is efficient, though borderline terse given the gaps elsewhere.

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

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

For a read-only lookup with no output schema, the description covers the essential 'what you get' but is thin on what 'details' comprises and omits any error or scope notes. Annotations carry the safety profile, so this is 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 only 50%: orgId is documented in the schema, but the required kitId has no description anywhere. The description's mention of 'kit' only loosely implies the identifier and adds no format or sourcing detail, so it does not compensate for the 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 states a specific verb+resource ('Get kit details') and adds useful scope ('incl. contained assets'), so an agent knows this returns a single kit with its assets. It does not differentiate itself from close siblings like shelf_list_kits or shelf_get_asset, leaving the retrieval-vs-list distinction 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as shelf_list_kits (enumeration) versus this single-kit fetch. The agent must infer the use case from the name 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the batch scope ('bulk', multiple kitIds) and the three intent modes, but says nothing about partial-failure semantics, permissions, or batch limits for a multi-record mutation.

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 resource and the operation set arrive immediately. It is arguably too terse given the tool's complexity, 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?

For a bulk mutation over multiple kit IDs with no output schema, the definition leaves the agent guessing about return shape, partial-failure behavior, and how this differs from the single-item custody and location siblings. Annotations carry the safety profile, so the omission is real but not severe.

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 60%, and the schema itself already documents orgId's default and the conditional requirement of custodianId/newLocationId. The description's three intent names simply restate the enum values, adding no syntax, format, or conditional-binding detail beyond the 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?

The description names a specific verb (bulk action), the resource (kits), and enumerates the three supported intents, matching the intent enum exactly. The 'on kits' scoping does differentiate it from the asset-oriented siblings like shelf_assign_custody and shelf_bulk_update_location, though it never names them.

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 explicit when-to-use, when-not, or alternative routing, despite heavy sibling overlap with shelf_assign_custody, shelf_release_custody, and shelf_bulk_update_location. The word 'bulk' weakly implies 'use this for many kits at once', but the agent must infer that on its own.

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, and openWorldHint=true, so safety is largely covered. The description usefully confirms merge-not-replace behavior, which is real added value, but says nothing about partial failures, quantity conflicts, or return behavior for a write 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 tight sentence with the key additive constraint front-loaded and no filler. It is efficient, though perhaps too terse given the tool's 4-parameter complexity.

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

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

For a 4-parameter mutation with a nested quantities object, no output schema, and half the parameters undocumented in the schema, the description leaves out important details such as quantity semantics, orgId defaults, and result/error 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 only 50%: kitId and assetIds carry no descriptions, and only 'quantities' is documented in the schema. The description adds no parameter-level meaning (e.g., quantity semantics, whether quantities overrides defaults) to compensate for that 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 (add) and resource (assets to an existing kit), and the parenthetical 'existing contents are kept' clarifies the additive scope. It distinguishes itself in spirit from shelf_kit_remove_assets, though it never names a sibling 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 statement of when to use this versus shelf_kit_action, shelf_create_kit, or shelf_kit_remove_assets. The only usage-adjacent signal is the additive note, which must be inferred rather than stated.

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, destructiveHint=false, and openWorldHint=true, so safety is partially covered. However the description adds nothing about whether removal is reversible, whether it requires kit ownership/permission, or how it interacts with the open-world hint — notably it does not clarify why a removal mutation is flagged non-destructive.

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 padding, appropriately sized for a simple tool, though its brevity comes at the cost of substance rather than being genuinely efficient.

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

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

For a mutation tool with no output schema and only 33% parameter coverage, the description is far too thin; it omits reversal semantics, permission requirements, and the meaning of the required parameters an agent needs to call it correctly.

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

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

Schema coverage is only 33% (only orgId is documented). The description mentions neither kitId nor assetIds, adds no format, batching, or minItems context, and does not compensate for the undocumented required parameters as the low-coverage case demands.

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 ('Remove assets from a kit'), which is enough to distinguish it from the sibling shelf_kit_add_assets by contrast. It is clear but offers no further detail about scope or effect.

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 prerequisites, and no explicit reference to the sibling shelf_kit_add_assets as the inverse operation. The agent must infer the usage context entirely.

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, and openWorldHint=true, so the agent knows this is a non-destructive write. The description adds only the weak precondition implied by 'existing', and says nothing about whether re-linking an already-linked code overwrites or errors, nor about required 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?

A single grammatical sentence with the operation front-loaded and no filler. It is efficient, though its brevity borders on under-specification rather than tight editing.

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 no output schema and two of three parameters undocumented, the description should describe the link semantics (what happens on conflict, whether the link is reversible) and the qrId format. None of that is present, leaving the agent to guess before calling.

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 only 33% – only orgId is documented (defaulting to SHELF_ORG_ID). The description mentions 'QR code' and 'asset' but does not clarify the expected form of qrId (raw code string vs. internal ID) or assetId, so it does not compensate for the documented 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 states a specific verb+resource pair ('Link ... Shelf QR code to an asset'), so an agent knows exactly what operation is performed. It does not, however, distinguish this from related tools such as shelf_lookup_code or explain how it differs from other asset-mutating siblings like shelf_update_asset.

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 statement of preconditions (e.g., the QR code must already exist and be unlinked), and no mention of alternatives. The word 'existing' hints at a precondition but is not framed as usage 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=true, so the safety profile is covered. The description adds nothing beyond that structured data: no pagination behavior, no default page size, no note on how search matches fields, and no indication of result shape. With annotations carrying the safety burden, the description still fails to add the contextual traits an agent would benefit from.

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 short, front-loaded sentence with zero filler, so it is efficiently sized. But brevity here reads as under-specification rather than disciplined conciseness — nothing is wasted because almost nothing is said.

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 6-parameter list/search tool with no output schema and a dense sibling set, the definition is too thin. Key agent-relevant details — default paging, how search and status filters combine, when to prefer shelf_available_assets — are all absent, leaving the agent to infer behavior from the schema 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 83%, above the 80% threshold, so the schema documents page, orgId, search, perPage, and myCustody on its own — baseline 3 applies. The description contributes no additional parameter meaning; notably the 'status' enum carries no description in either place, which the prose could have clarified 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?

The description gives a verb ('Search/list') and a resource ('assets') scoped to the workspace, so the basic intent is graspable. However, it conflates two distinct operations and offers no differentiation from siblings like shelf_available_assets, shelf_get_asset, or shelf_lookup_code that also surface assets. 'Search/list assets' leaves the agent guessing which sibling is the right one.

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 statement, no mention of the alternative shelves (e.g., shelf_available_assets for availability-filtered listings), and no prerequisites such as org context. The single sentence simply restates the capability without routing guidance, which is exactly the gap the sibling landscape makes costly.

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, and the description is consistent with them (no contradiction). But the description adds zero behavioral context beyond the annotations — no mention of pagination, filtering behavior, or result 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 two-word fragment. This is under-specification rather than effective conciseness — nothing is front-loaded because there is essentially no 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?

With 7 optional parameters, no output schema, and only 57% schema coverage, the description is far too thin to let an agent call this correctly. It does not compensate for the missing parameter documentation or explain the return shape.

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 only 57%, so several parameters (search, status, sortOrder) lack documentation. The description adds no parameter meaning at all, leaving the coverage gap unfilled.

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 verb and resource ('Search/list bookings'), so the agent knows the general operation. However it is vague about scope and filtering, and gives no differentiation from siblings like shelf_bookings_calendar or shelf_get_booking. It is a bare verb+resource with no distinguishing detail.

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 tool versus shelf_bookings_calendar or shelf_get_booking, nor any prerequisites or context. The description offers nothing beyond the operation 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, covering the safety profile, but the description adds nothing further: no pagination behavior, no result ordering, no indication of whether results are scoped to the workspace or to all bookings. With zero added behavioral context, it does not clear the lower bar set by 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?

A single front-loaded sentence with no filler or redundancy. Its brevity works against it in substance, but judging conciseness and structure alone, there is no wasted text and the purpose leads.

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 annotations limited to readOnly/openWorld hints, the description must carry the burden of explaining what is returned and in what scope, and it does not. For a listing tool whose scope against shelf_list_tags is unclear, this leaves an agent guessing before invocation.

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

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

Schema description coverage is 100% for the single orgId parameter, including its default fallback to SHELF_ORG_ID or the current workspace, so the schema carries the semantics fully. The description repeats none of this, which is acceptable at baseline 3 for a one-parameter tool.

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 verb and resource ('List booking tags'), so the basic action is clear, but it does not distinguish the tool from the very similar siblings shelf_list_tags and shelf_list_bookings. It is ambiguous whether this returns tag definitions available for bookings or tags already attached to a specific booking, and no scope or relationship is stated.

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 indication of when to use this tool, what prerequisites apply, or how it differs from shelf_list_tags. With an orgId default already documented in the schema, an agent gets no routing guidance for choosing this over the generic tag-listing sibling.

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 no behavioral context such as pagination, return structure, whether categories are workspace-scoped, or how the optional orgId default behaves.

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 wasted words and the core action is front-loaded. It is terse to the point of omitting useful context, but not structurally poor.

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 list tool with 100% schema coverage and read-only annotations, the description is minimally adequate. However, with no output schema, it still does not tell the agent what shape the returned categories take or whether they are scoped to the default workspace.

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

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

Schema description coverage is 100%, and the single orgId parameter already documents its default behavior. The description adds no parameter syntax or scope detail beyond what the schema provides, so the baseline 3 is appropriate for high 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 and resource: 'List asset categories.' That is clear enough for an agent to identify the operation. It does not, however, distinguish this tool from sibling list tools such as shelf_list_tags or shelf_list_locations beyond naming the category 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 exclusions, and no mention of alternatives. The agent must infer that this is the lookup for asset categories rather than for tags, locations, or custom 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 the meaningful 'active' qualifier, telling the agent archived definitions are excluded, but says nothing about ordering, pagination, or return 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?

A single front-loaded sentence with no filler. The scope ('active') and the optional filter appear immediately and 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?

For a two-parameter, read-only list tool with no output schema and safety already covered by annotations, this is close to sufficient. The only gap is the absence of any note on result ordering or pagination for a potentially long list.

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 only 50%: orgId is documented in the schema but categoryId is not. The description compensates by explaining categoryId's semantics — restrict results to definitions applying to one category — which is the one undocumented parameter.

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 and resource ('List active custom field definitions') with a scope qualifier, which distinguishes it from siblings like shelf_list_tags and shelf_list_categories. It stops short of explicitly naming an alternative sibling, but the resource noun 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?

'optionally those applying to one category' implies when to pass categoryId, so usage is inferable. There is no explicit when-to-use vs. alternative guidance and no statement of when this tool is the wrong choice.

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 externally. The description adds no behavioral context of its own: no pagination behavior, no note that results are workspace-scoped, no indication of what filtering is supported.

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 extremely short and front-loaded, but the brevity comes at the cost of under-specification rather than efficiency. Two words cannot carry the informational load of a six-parameter listing 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 tool with six optional parameters, no output schema, and workspace scoping, the description is far too thin. An agent knows it lists kits but not what filters exist, what the results look like, or how paging behaves.

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?

Three of six parameters (search, status, myCustody) have no schema description and the description supplies nothing to fill the gap. Even the documented parameters (page, orgId, perPage) get no additional meaning from the description text.

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 verb (search/list) and a resource (kits), so the basic purpose is clear. However, it does not distinguish this tool from shelf_get_kit or shelf_create_kit, and the merged 'search/list' phrasing leaves the scope ambiguous (is it a fuzzy search, a paginated browse, or both?).

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 tool versus alternatives such as shelf_get_kit for a single kit or shelf_list_assets for other resource types. At best, 'list' weakly implies bulk browsing, but nothing is stated explicitly.

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 nothing beyond that: no pagination behavior for a paginated endpoint, no default workspace resolution behavior, and no note on the openWorld search 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 single sentence is front-loaded with no filler, but it is under-specified rather than concise: it omits the scope, target resource meaning, and pagination contract that an agent needs. Brevity here costs information rather than saving 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?

For a read-only listing tool with no output schema, the description should at least describe what a location record is and how results are paged/defaulted. None of that is present, leaving the agent with only the tool name and schema to work from.

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 75% (page, orgId, perPage are documented; search is not). The description's mention of 'search' loosely maps to the undocumented param but adds no syntax, matching, or format detail, so it does not compensate for the gap. Baseline 3 given the largely self-documenting 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?

The description names a verb ('List/search') and a resource ('locations'), which is enough to distinguish it from shelf_list_assets or shelf_list_tags. However, it never says what a 'location' is in this domain or what the combined list/search behavior means, so the purpose is only vaguely conveyed.

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 indication of when to call this versus siblings such as shelf_lookup_code, shelf_bulk_update_location, or shelf_list_assets, nor any stated preconditions (e.g., workspace scoping). Usage must be inferred entirely.

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 nothing beyond that — no note on pagination, result ordering, or scope of 'asset tags' versus other tag types.

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 four-word sentence is front-loaded and wastes nothing, but it is under-specified rather than genuinely concise — the brevity comes at the cost of any useful 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 trivial read-only list tool with full schema coverage and annotations covering safety, the description is minimally adequate. It is not misleading, but it leaves the agent without any context on what tags are returned or how they relate to sibling tag tools.

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

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

Schema description coverage is 100% and the single optional orgId parameter is fully documented in the schema (including the SHELF_ORG_ID default). The description adds no parameter meaning, so the baseline 3 applies.

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 clear verb+resource ('List asset tags'), which distinguishes it from shelf_create_tag. However, it does not differentiate itself from the closely related shelf_list_booking_tags or shelf_list_custom_fields, so an agent must infer scope from the name alone.

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 prerequisites, and no mention of alternatives such as shelf_list_booking_tags. The agent gets no routing help 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that results feed custody and booking flows, but says nothing about pagination behavior, result size limits, or whether the list is scoped to a single workspace.

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 the action first and the motivating context second; no filler. It is efficient, though the parenthetical is doing guidance work that could be stated more directly.

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 should ideally say what a member record contains or how results are paginated. It covers the 'why' (custodians) adequately but leaves the agent without return-shape expectations for a four-parameter 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 coverage is 75%: page, perPage and orgId carry their own descriptions, while 'search' has none. The description's 'List/search' hints that a search term is supported but adds no syntax, matching behavior, or scope details beyond the schema. Baseline 3 applies when the schema does most of the work.

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 pair (list/search) and resource (team members), which is unambiguous and does not overlap with any sibling tool such as shelf_list_assets or shelf_whoami. It stops short of distinguishing itself from siblings explicitly, but the resource is unique enough that differentiation is unnecessary.

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 parenthetical 'needed as custodians for custody and bookings' implies when the tool is useful, i.e. when you need member identities for shelf_assign_custody or booking operations. That is contextual usage, but it is stated as a reason rather than an explicit when-to-use rule and gives no exclusions or alternative 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 and openWorldHint=true, so the safety profile is covered by structured data. The description adds the useful behavioral fact that resolution returns an owning asset or kit, but says nothing about lookup failure behavior, precedence between qrId and barcode, or whether resolution is exact-match.

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-formed sentence with the verb and outcome front-loaded and no filler. Nothing needs to be trimmed.

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

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

For a read-only lookup with full schema coverage and no output schema, the description covers the essential contract: input is a scanned code, output is the owning asset/kit. It is slightly thin on edge cases (all three params are optional, so an agent gets no guidance on which one to supply or what happens if none is), but it is adequate.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and the baseline is 3. The description maps conceptually to qrId and barcode but adds no syntax, format, or precedence detail, and does not mention the orgId parameter at all.

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 ('Resolve') and specific resources ('Shelf QR code ID or a barcode value') and names the outcome ('the asset/kit it belongs to'). This is far more informative than the name alone, though it does not explicitly contrast itself with lookup siblings like shelf_get_asset or shelf_link_qr.

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 word 'scanned' implies the usage context (an agent holding a QR/barcode string), which is useful implied guidance. However, there is no explicit statement of when to prefer this over shelf_get_asset with an asset ID, nor any exclusion or prerequisite conditions.

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 safety bar is lower. The description earns credit beyond that by disclosing the replacement semantics — that the supplied set of placements is the authoritative full state, which is exactly the behavior an agent must not get wrong on a 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?

One dense sentence with the mutation semantics front-loaded in the parenthetical. Every clause carries meaning and nothing is 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?

For a nested-array mutation with no output schema, the definition covers the core replacement behavior but omits expected failure modes (non-quantity-tracked asset, invalid locationId, negative quantity), the response shape, and any partial-application semantics. 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 only 33% (only orgId is documented). The description compensates partially by constraining the target to a 'quantity-tracked asset' and clarifying that quantity is per-location, but it says nothing about assetId format, placement item structure, or what an omitted locationId means.

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), the resource (units of a quantity-tracked asset at each location), and the operative scope ('full replacement'), which cleanly separates it from the incremental shelf_adjust_quantity sibling. It stops short of naming that alternative explicitly, so it is clear but not fully differentiated in-language.

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 '(full replacement)' parenthetical implies the usage context (bulk authoritative placement vs incremental adjust) but never states when to choose this over shelf_adjust_quantity or shelf_update_asset_location, nor any prerequisite that the asset be quantity-tracked. Usage is inferable, not stated.

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 agent knows this is a non-destructive mutation. The description adds nothing beyond that: it does not say whether release is reversible, what permissions are needed, or what state the assets end up in.

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, the core action is front-loaded, and the special-case format follows immediately. 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 mutation tool with no output schema and 33% schema coverage, the description is thin. It omits what happens to the assets, whether custody must exist first, and any permission requirements.

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 33% (only orgId is documented). The description compensates for the undocumented quantities parameter by giving its format {assetId: qty}, which is genuinely useful, but leaves assetIds semantics (plural, minItems 1) 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 (release) and resource (custody of assets), which implicitly contrasts with the sibling shelf_assign_custody. It doesn't name that sibling explicitly, but the operation 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 a hint about the quantity-tracked case, but no when-to-use guidance, no prerequisites (e.g. must the asset currently be in custody?), and no explicit routing against shelf_assign_custody or shelf_adjust_quantity.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's 'DRAFT' qualifier adds a real behavioral constraint (the target booking must be in draft state), but it omits what the reservation does to the booking's state, whether it is reversible, and any 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?

A single short sentence with no filler, and the state qualifier is front-loaded. It is concise, though the brevity borders on under-specification rather than pure economy.

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 no output schema and a partially documented schema, the description should explain the draft precondition, the resulting state, and failure behavior. It delivers only the draft qualifier, leaving most of what an agent needs to invoke it correctly unstated.

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 67%, and the required parameter bookingId has no description in the schema at all; the tool description does nothing to clarify it (e.g., that it must reference a draft booking). The description adds no meaning beyond what the schema partially 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 ('Reserve') and resource ('booking'), and adds a state qualifier ('DRAFT'). However, it doesn't distinguish this from close siblings like shelf_create_booking, shelf_checkout_booking, or shelf_update_booking, leaving the agent to infer which booking-transition 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?

No explicit when-to-use or when-not-to-use guidance. The word 'DRAFT' hints at a precondition (the booking must be a draft), but the description never states this as a requirement, nor does it name an alternative tool for non-draft bookings.

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 is a write with openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds format constraints, but omits whether an existing main image is replaced/overwritten, any size limits, and permission requirements — meaningful gaps for an upload 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?

One tight sentence that front-loads the action ('Upload a local image file') and immediately qualifies accepted formats and target. Nothing is wasted or 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 3-parameter tool with one undocumented parameter, no output schema, and no annotations covering replacement semantics, the description is workable but leaves open what happens to a pre-existing main image and how failures surface. It covers enough to attempt the call but not enough to predict its effects.

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 67%: filePath and orgId are described in the schema, but assetId is bare in both places. The description adds format details for the file (jpg/png/webp) and clarifies that assetId targets the asset's main image, which is modest but real added 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?

The description gives a specific verb+resource ('Upload a local image file... as the asset's main image') and constrains accepted formats (jpg/png/webp). It clearly reads as an image-setter rather than a generic asset mutation, though it does not name or contrast with siblings like shelf_update_asset.

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 by the action itself: set the primary image for an existing asset. There is no explicit when-to-use vs alternative (e.g., general asset update), no prerequisite the asset must already exist, and no stated exclusions, so guidance is only 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation-but-safe profile is already covered. The description adds a genuinely non-derivable behavioral fact: the change is session-scoped and only affects subsequent calls, not persistent state. It does not say whether an existing default is overwritten or what happens on an invalid orgId, so it is good but not complete.

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, front-loading the verb and resource and closing with the scoping constraint that matters most for correct invocation.

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

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

For a one-parameter session setter with annotations covering the safety profile and no output schema, the description is nearly sufficient. It omits only edge behavior (overwriting an existing default, error handling on an unknown orgId), which is a minor gap rather than a blocking one.

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?

There is one parameter at 100% schema description coverage, and the schema already explains that orgId comes from shelf_whoami. The description's parenthetical '(organization)' clarifies the workspace/org equivalence, which is minor added value; baseline 3 applies when the schema does the heavy lifting.

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 specific resource ('the default workspace (organization)'), and the effect scope ('for subsequent calls in this session'). No sibling tool does anything comparable, so the agent can place it immediately 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 phrase 'for subsequent calls in this session' implies when the tool is useful (before other calls that need a workspace context), but it never states a when-not condition, prerequisites, or that the orgId must first be obtained from shelf_whoami. Usage is inferred rather than instructed.

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, destructiveHint=false, openWorldHint=true, so safety profile is covered. The description adds two genuinely useful traits beyond that: partial-update semantics (omitted fields stay unchanged) and, critically, that `tags` is a full-set replacement so callers must resend every tag or lose the rest.

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 core action and followed by the two constraints that most affect correct invocation. Zero 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 an 8-parameter mutation tool with low schema coverage and no output schema, the description covers the mutation model well but omits per-parameter meaning and any note on which fields are optional versus required. 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 only 25% of 8 parameters, so the description carries a heavy compensation burden. It adds meaning for `tags` only and says nothing about orgId, valuation, categoryId, customFields, title, or description, leaving most parameters documented nowhere.

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 ('Update fields of an asset'), which clearly separates it from shelf_update_asset_location and shelf_update_booking by naming the asset as the target. It does not explicitly contrast itself against the other update siblings, 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?

No statement of when to use this versus shelf_update_asset_location, shelf_bulk_update_location, or shelf_create_asset, and no prerequisites or permissions mentioned. The only guidance is semantic (omitted fields unchanged), not conditional.

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, and openWorldHint=true, consistent with the 'Move' verb, so safety is covered. The description adds the conditional quantity nuance but says nothing about whether an existing placement is overwritten, permission requirements, or reversibility. With annotations carrying the safety profile, this is adequate but thin.

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 written sentences with the primary action front-loaded and the conditional detail second. No filler, no repetition of the name or annotations.

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 for a mutation the description does not address what a successful move returns, how it interacts with existing placements, or cross-model context (e.g., does assetId accept a code vs an ID). It is minimally complete given annotations cover the safety signals, but leaves notable 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 only 25% (only orgId is documented in-schema), so the description must compensate. It usefully clarifies quantity semantics for quantity-tracked assets, but assetId and locationId carry no explanation in either place, leaving half the parameters unelaborated.

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?

Clear verb+resource+destination: 'Move an asset to a location' tells an agent exactly the operation performed. The singular 'an asset' implicitly distinguishes it from the bulk sibling shelf_bulk_update_location, but the description never names or contrasts that sibling 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?

The clause 'For quantity-tracked assets, optionally pass a quantity' gives real conditional usage guidance about when to supply a parameter. However, it offers no routing against near-neighbors like shelf_bulk_update_location or shelf_adjust_quantity, leaving alternative selection 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=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive mutation. The description adds the useful constraint that all core fields are required, but does not disclose whether unspecified fields (e.g. tags, description) are cleared or preserved, nor any 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?

A single tight sentence, front-loaded with the verb and field list; the trailing parenthetical carries the important 'all core fields required' constraint. No wasted text, though the phrasing is slightly cramped.

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 9-parameter mutation with no output schema, the description covers the intent and the required-field constraint, and annotations cover the safety profile. It omits update semantics (replace vs merge for optional fields like tags) and confirmation of what the response returns, leaving modest 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 coverage is 67%, with descriptions on endDate, startDate, custodianTeamMemberId, orgId, timeZone, and tags. The description lists the mutable fields but adds no format or merge semantics beyond what the schema already provides, so it sits at the mid-coverage baseline.

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

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

The description states a specific verb (Update) and resource (booking), and enumerates the mutable fields (name, dates, custodian, description, tags). An agent can distinguish it from shelf_create_booking and shelf_get_booking, though no sibling is explicitly named.

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 for related mutations (e.g. shelf_reserve_booking, shelf_checkout_booking), and no prerequisites stated. The only constraint, 'all core fields required,' is a schema note rather than routing 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=true, so the safety profile is covered. The description adds one useful behavioral fact — that the first workspace in the result is the default — but says nothing about auth requirements, latency, or whether results are cached.

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 zero filler, and the most decision-relevant fact (what identity and workspace data comes back) is front-loaded. The trailing 'first workspace is the default' is a compact, high-value detail rather than 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?

With no parameters and no output schema, the description largely compensates by naming the returned fields (user, workspaces, IDs, roles, default ordering). It falls short only on how to interpret the result set (e.g. whether all memberships are returned and how the default relates to subsequent workspace-scoped calls).

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 there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly describes only return content and does not invent parameter semantics.

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 ('Show') and resource ('the logged-in user and the workspaces (organizations) they belong to'), plus the payload contents (IDs and roles). This is clearly distinguishable from siblings like shelf_set_workspace (a mutation) and shelf_list_team_members (lists other users, not the caller).

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 is the identity/context call to make before workspace-scoped operations. There is no explicit when-to-use, no when-not-to-use, and no named alternative (e.g. shelf_set_workspace) despite that sibling being the natural counterpart.

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