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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose what the status comprises (logged-in user, token validity, expiry), whether it requires a prior login, or whether it is a safe read-only call, leaving the agent to infer all of this.

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. Nothing is wasted and the purpose is stated immediately.

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

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

For a zero-parameter, no-annotation tool with no output schema, the description is minimal but leaves the agent guessing what the status result actually contains and whether any prerequisite state is required. Adequate, but a sentence on the expected outcome would close the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies since no parameter-level semantics are needed.

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

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

States a specific verb+resource: check the current authentication status with the DSpace instance. This is clearly distinguishable from siblings dspace_login and dspace_logout, though it doesn't explicitly name those siblings as the contrasting alternatives.

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

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

Usage is only implied: an agent can infer this is a read-only probe used to determine whether it needs to call dspace_login. There is no explicit statement of when to call it (e.g., before authenticated operations) or when it is unnecessary.

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?

With no annotations, the description carries the full behavioral burden and does disclose two meaningful traits: it requires admin privileges and the item is immediately visible in the repository (no staged/draft state). It omits failure behavior, metadata validation requirements, and what the call returns, but the permission and visibility disclosures are exactly the non-obvious facts an agent needs.

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, zero filler, with the purpose front-loaded and the admin/visibility constraints following immediately.

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 annotations and no output schema, the description covers the essentials: what it does, who can do it, and the immediate-visibility side effect. The notable remaining gap is the return value (e.g. the new item's UUID) and any required-metadata constraints, which the agent must learn from elsewhere.

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% (owningCollectionUuid, metadata, discoverable are all documented in the schema, including Dublin Core key format and multi-value handling). The description adds nothing beyond that, 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 specific verb and resource ("Create an archived item") plus the scope qualifier ("directly in DSpace"), and the phrase "bypasses submission workflow" implicitly distinguishes it from the workspace/submission siblings like dspace_create_workspace_item. An agent can tell it apart from the other create-path tools without opening a 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?

"admin only, bypasses submission workflow" gives clear context for when this tool applies and a precondition for calling it. It stops short of naming the alternative explicitly (e.g. use dspace_create_workspace_item for the normal submission path), so no exclusions or routing guidance are 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is the entry point to a multi-step deposit workflow and that metadata is not added here, but it omits auth requirements (there is a dspace_login sibling), whether the item is reversible/deletable before submission, and what identifier the caller receives for the next step.

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 workflow sequence. Every sentence earns its place by establishing either what the tool does or what the caller must do next.

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 annotations and no output schema, the description covers the workflow position but leaves gaps: it does not say what the return value contains (presumably the workspace item handle/UUID needed by the next call), nor the authentication precondition. 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 description coverage is 100%, so both parameters (metadata and owningCollectionUuid) are already documented with examples and defaults in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Create a new workspace item (submission) in DSpace.' The parenthetical clarifies that this is the workspace/submission model rather than a published item, which is meaningful given the sibling dspace_create_item. It stops short of explicitly contrasting itself with that sibling, so an agent must infer the distinction.

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

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

Gives clear workflow context: creation starts the deposit workflow, then route to dspace_update_workspace_item to add metadata and submit for review. It names the next tool explicitly. It does not, however, state when to prefer this over dspace_create_item or what prerequisites (e.g., being logged in) apply.

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?

With no annotations, the description carries the full behavioral burden and does well: it declares the operation irreversible, discloses the cascade (bundles/bitstreams removed), and states the admin-only authorization requirement. It omits error/response behavior, but the destructive and auth semantics are covered.

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

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

Two sentences, front-loaded with the action and identifier, followed immediately by the critical irreversibility warning. 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 destructive, single-parameter mutation tool with no output schema and no annotations, the description supplies the essential context: destructiveness, cascade scope, and auth requirement. Response/error behavior is unaddressed, but no output schema exists to defer to.

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 'uuid' parameter, so the schema already documents it; the description only restates 'by UUID'. Per the baseline rule for high coverage, a 3 is appropriate with no added syntax or format detail.

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 ('Permanently delete'), resource ('an item from DSpace'), and identifier ('by UUID'), which cleanly distinguishes it from read/update siblings like dspace_get_item and dspace_update_item_metadata. An agent can identify the operation 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 '(admin only)' qualifier gives a clear precondition for use, effectively telling the agent when this tool is applicable. It does not name alternatives (e.g., 'use dspace_update_item_metadata to modify instead of delete') or state explicit when-not conditions, so it falls short of the top band.

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?

With no annotations, the description carries the full behavioral burden and delivers little: it does not state auth requirements, error behavior for a bad/unknown UUID, or whether metadata is complete vs. partial. 'Including all metadata' is the only behavioral hint offered.

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 sentence, front-loaded with verb and resource, with zero filler. Well-sized for a single-parameter lookup 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 trivial single-param read with no output schema, the description is minimally adequate but silent on return shape and auth context. Since no output schema exists, it could usefully describe what the item payload looks like.

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

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

Schema description coverage is 100% and the single uuid parameter is documented as 'Item UUID' in the schema, so the description's 'by UUID' adds essentially nothing. 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 (Get) and resource (DSpace item) scoped by UUID, and notes it returns all metadata. It does not explicitly differentiate from read-side siblings like dspace_search, but the resource+identifier combination is unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. whether login is required), and no pointer to alternatives such as dspace_search when the UUID is unknown. The agent must infer 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?

No annotations are provided, so the description carries the full behavioral burden. "List" implies a read, but the description discloses nothing about permissions, ordering, pagination beyond what the schema shows, or return format, leaving significant gaps for a tool with zero annotation coverage.

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

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

A single, front-loaded sentence with no wasted words that conveys the tool's action and its one notable option.

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 read-only list tool with complete schema coverage and no output schema, the description is minimally adequate. It omits any note of default ordering or that results are paginated, but the essential action 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 100%, so the schema already documents page, size, and communityUuid. The description restates the community filter without adding format or defaulting detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (collections) with the optional community scoping, which is clear. However, it does not explicitly differentiate itself from the sibling dspace_list_communities, leaving the agent to infer the distinction from the names 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?

"Optionally filtered to a specific community" implies when the communityUuid parameter is useful, but there is no explicit when-to-use guidance, no mention of alternatives like dspace_list_communities, and no exclusions or 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the fact that it is a read: no auth/permission requirements, no pagination default behavior, no indication of whether results are limited or how many are returned. For a repo-listing call with zero annotation coverage this is a real gap.

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 filler. It says exactly what the tool is and nothing more, which is structurally ideal for a simple list operation.

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

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

For a trivial paginated list with a fully documented input schema and no output schema, the description is minimally sufficient. It stops short of telling the agent anything about result shape, ordering, or how it differs from sibling listing tools, which leaves the definition merely 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?

Both parameters (page, size) have 100% schema description coverage and the description adds no format or default-value detail beyond them. With the schema doing all the work and no parameters required, the baseline of 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 names a specific verb (List) and resource (communities) with the scope qualifier 'top-level', so the operation itself is unambiguous. However, it never distinguishes itself from the close sibling dspace_list_collections or dspace_list_workspace_items, which an agent could easily confuse with it.

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, when-not-to-use, or alternative-tool guidance. The agent is left to infer that this is a browsing/entry-point call rather than a search, and must guess how it relates to dspace_search and dspace_list_collections.

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?

With no annotations, the description carries the full behavioral burden. 'List' safely implies a read operation, but it does not disclose the authentication requirement (only implies it via 'current user'), pagination behavior or defaults, or what an empty result means. It adds little beyond restating the name.

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 resource front-loaded and the parenthetical clarification placed exactly where comprehension needs it. 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 simple two-parameter, no-output-schema list tool this is minimally adequate: the read scope and subject are clear and the schema handles pagination. It falls short on prerequisites (auth/session state) and any indication of result shape beyond 'items', which matters because a workspace list is user-scoped.

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%: both 'page' (0-based) and 'size' (1-100) are fully documented in the schema, including bounds. The description adds no additional meaning such as default values or ordering, so 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 verb (List) and resource (workspace items) with scope (for the current user), and clarifies the domain jargon by equating workspace items with in-progress submissions. It does not explicitly distinguish itself from siblings like dspace_search or dspace_get_item, but the resource is unambiguous.

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

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

There is no when-to-use guidance: no mention of when to prefer this over dspace_search, dspace_list_collections, or how it relates to dspace_create_workspace_item / dspace_update_workspace_item. The phrase 'for the current user' implies a logged-in context but stops short of stating a prerequisite.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the session persists across subsequent tool calls, but says nothing about token lifetime, what happens on failure, whether credentials are stored, or how to re-authenticate after expiry.

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, zero filler, with the core purpose front-loaded and the two login modes immediately following. Every sentence 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 3-param tool with no output schema and no annotations, the description covers the essentials: purpose, the two modes, and session persistence. Missing failure/expiry behavior keeps it short of a 5, but nothing critical blocks correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema by stating the either/or constraint: token OR email+password. That mutual exclusivity is not expressible in the flat schema and is the key semantic an agent needs.

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 ('Authenticate with a DSpace instance') and is clearly distinguishable from siblings like dspace_auth_status and dspace_logout. An agent can immediately tell this establishes a session rather than checking or ending 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?

Explicitly lays out the two mutually exclusive entry paths (JWT token OR username+password), which is real usage guidance for how to call it. It does not, however, say when to prefer this over dspace_auth_status or when to call it again if a session already exists.

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?

With no annotations, the description carries the full burden, and it does disclose the key side effect: the current JWT token is invalidated, which tells the agent the session becomes unusable. It omits other relevant traits such as whether an already-logged-out or invalid token errors, and whether invalidation is server-side only.

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

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

A single front-loaded sentence that names the action first and the effect second, with no filler or redundancy.

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

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

For a zero-parameter tool with no output schema, the description covers all an agent needs to call it: the action and its effect on the token. Only minor edge-case behavior (already-invalid sessions, authentication prerequisites) is unaddressed.

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

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

The tool takes zero parameters and the description correctly introduces none. Baseline of 4 applies for a parameterless tool; there is simply nothing further to document.

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 (logout) and resource (the DSpace instance), and adds the concrete effect ('invalidating the current JWT token'). This cleanly distinguishes it from its direct sibling dspace_login and from dspace_auth_status, which reads session state instead of ending it.

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 verb and by the presence of dspace_login/dspace_auth_status as siblings, but the description never explicitly says when to call it (e.g. at end of a session, before switching accounts) or what happens if no session exists. Adequate but no 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It identifies a search operation but does not state read-only safety, authentication requirements, pagination behavior, rate limits, or result format; the schema supplies parameter details but not behavioral guarantees.

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 purpose followed by supported capabilities. There is no filler, and every sentence contributes to a quick understanding of the tool.

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

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

For a 7-parameter search tool with no annotations, no output schema, and many sibling tools, the description omits when to use this versus list/get tools and provides no behavioral or authentication context. The rich schema helps with invocation mechanics but not selection.

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%, with all 7 parameters already documented in detail (Solr/Lucene syntax, UUID scope, enum type, filter key-value examples). The description restates parameter categories without adding syntax, defaults, or examples beyond the schema, so the baseline of 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 verb ('Search') and resource (DSpace items, communities, collections), making the core action clear. However, it does not explicitly differentiate this tool from sibling list/get tools such as dspace_list_communities or dspace_get_item, so an agent must infer when search is preferred.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The description lists capabilities (full-text queries, type filtering, scoping, advanced filters) but never names alternatives or the conditions under which this tool should be chosen over sibling list/get 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the mutation mechanism and the supported ops, which is useful, but says nothing about permission/auth requirements, whether 'remove' is irreversible, whether operations are atomic or can partially fail, or what the response looks like — all critical for a mutation tool with zero annotation coverage.

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

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

Two tight sentences with no filler, front-loading the core action and then the supported operation set. Every clause earns its place.

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

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

No output schema exists, so the description need not explain return values, and the schema is rich enough to cover parameters. However, for a mutation tool with no annotations, the description omits auth/permission expectations and the consequences or reversibility of operations — a meaningful gap for an agent about to modify live metadata.

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 nested operations schema already documents op, path, from, and value with examples, so the schema does the heavy lifting. The description adds only the RFC 6902 reference and the op enumeration, which are marginal gains beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Update metadata on an existing DSpace item') and names the mechanism (JSON Patch / RFC 6902) plus the supported operations, so the agent knows exactly what the tool does. It does not, however, explicitly differentiate itself from the sibling dspace_update_workspace_item, leaving that distinction to the agent.

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 (e.g. authentication or required permissions), and no mention of when to prefer this over dspace_update_workspace_item or dspace_create_item. The agent must infer all routing decisions from the tool 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only the patch mechanism (JSON Patch), which is meaningful, but says nothing about mutation semantics such as whether remove operations are destructive, whether the item must be unlocked, auth requirements, or error behavior on invalid paths, leaving a write tool substantially under-documented.

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 verb+resource first and the mechanism last; nothing is wasted. It is arguably too terse to address a JSON Patch write tool, but as a sentence it is well structured.

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

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

The schema is fully documented and the description names the resource and patch mechanism, so an agent can call it correctly. For a mutation tool with no annotations and no output schema, though, missing guidance on permissions, item state, and patch failure behavior leaves real 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 100%: the schema documents the required id and the operations array with op/path/from/value semantics and a concrete JSON Pointer example. The description adds only the mechanism name and no extra parameter guidance, 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 specific verb (update) and resource (metadata on a workspace item) and helpfully glosses 'workspace item' as a submission in progress, which disambiguates the resource. It does not, however, distinguish itself from the sibling dspace_update_item_metadata, leaving the agent to infer that one targets in-progress submissions and the other archived items.

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 '(submission in progress)' implies the usage context, so an agent can roughly infer when this tool applies. However, it never states when to use this instead of dspace_update_item_metadata or dspace_create_workspace_item, nor any preconditions such as required submission state or permissions.

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?

With no annotations, the description carries the full burden: it usefully discloses the admin-only auth requirement, the default ORIGINAL bundle, and that the bundle is auto-created as a side effect. However, it omits return value, overwrite/duplicate-name behavior, and size limits, which matter for a mutation 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?

Two sentences, zero waste, purpose front-loaded followed by the bundle behavior. 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?

Covers purpose, auth gate, and bundle side effects for a 6-parameter mutation tool with no annotations or output schema. It is nearly complete, but the absence of return-value and overwrite/error semantics leaves a modest gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only reinforces the bundleName default and ORIGINAL semantics that the schema already states, adding no new parameter-level detail such as name collisions or path constraints.

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 ('Upload a local file as a bitstream ... to a DSpace item') and scopes it clearly against siblings like dspace_create_item and dspace_update_item_metadata. An agent can identify the operation 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?

Provides the key usage constraint '(admin only)' and implies the item must already exist as the attachment target, which gives real context. It does not explicitly name when to prefer this over alternatives, but no sibling competes for the same bitstream-upload job.

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