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

With no annotations, the description must carry the behavioral burden. It discloses important preconditions (status requirements, approver requirement) and the authenticated-user context. However, it does not state the outcome of approval (e.g., status changes to 'Approved') or any reversibility or response behavior, leaving some behavioral ambiguity.

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

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

The description is three sentences with no fluff. The core action is front-loaded, followed by conditions and a helpful pre-call instruction. 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 single-parameter mutation tool with no output schema, the description covers the essential invocation context: the action, valid input source, preconditions, and a verification step. It does not explain the response or post-approval state, but the provided guidance is sufficient for an agent 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 100% and the parameter description already explains document_id as the SharePoint objectID and where to obtain it. The tool description adds no additional parameter meaning, so the baseline score 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 opens with a specific verb and resource: 'Approve a document in Hermes as the currently authenticated user.' It clearly distinguishes this tool from siblings like hermes_update_document or hermes_request_review by stating the approval action and the required document status and approver role.

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 strong context on when to call the tool: the document must be 'In-Review' or 'Approved' and the user must be an approver. It also instructs to use hermes_get_document to check status and approver list first. It does not explicitly name alternatives or when not to use the tool, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the creation side effect, the WIP status, the returned ID, and the publishing path. This is strong behavioral context for a create operation, though it doesn't cover permissions or failure behavior.

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

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

The description is two concise sentences with no filler. The most important facts—what it creates, what it returns, and the WIP/publish status—are front-loaded and clearly stated.

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 create tool with no output schema, the description fully covers the purpose, return value, and lifecycle status. An agent can invoke it correctly and understand what to do next with the returned ID.

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 each parameter is already documented. The description adds no parameter-specific meaning beyond the schema, which is acceptable given the high 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 clearly states the action ('Create a new document draft'), the target resource (Hermes), and distinguishes its output (new document ID) and lifecycle state (WIP until published). It is easy to tell apart from sibling update/review tools.

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

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

The description gives clear lifecycle context: the draft is WIP and published later via hermes_request_review. This implies when to use the tool, though it does not explicitly mention alternatives like hermes_update_draft for editing or when not to use this tool.

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 available, the description carries the full burden. It discloses the input format requirement, the 404 error behavior for wrong IDs, and the output contents, which is strong for a simple read operation.

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

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

Every sentence earns its place: purpose, returned fields, critical input warning, and the prerequisite workflow. The most important information is front-loaded, and the description stays focused despite the warning 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 single-parameter read tool with no output schema and no annotations, this description is complete. It tells the agent what to pass, how to obtain it, what will be returned, and what happens if the wrong value is supplied.

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 schema already covers the parameter at 100%, so the baseline is 3. The description adds value by emphasizing the objectID versus docNumber distinction and the required upstream call to hermes_search, going 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?

States the specific verb 'Get' and resource 'full metadata for a specific Hermes document by its SharePoint objectID,' and enumerates the returned fields. This clearly differentiates it from search and create/update siblings.

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

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

Explicitly instructs to call hermes_search first to obtain the objectID, warns against using the human-readable docNumber, and states the 404 failure mode. This provides concrete when-to-use and when-not-to-use 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 must carry the behavioral disclosure burden. It accurately communicates a read-only listing operation and the content of the response, but it does not mention permissions, pagination, or output format. For a simple 0-parameter metadata list, this is adequate but not rich.

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

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

The description is one sentence with no wasted words, front-loads the primary action, and gives just enough detail to clarify purpose and return contents. It is concise without being under-specified.

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

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

For a parameterless metadata-listing tool with no output schema, the description fully covers what the tool does and what it returns. It includes examples and names the fields included in the response, so an agent has enough context 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?

The tool has no parameters and the input schema is complete and empty, so there is nothing for the description to add about parameter semantics. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for any gaps.

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

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

The description clearly states the action (list), the resource (document types), and the scope (all in this Hermes instance). It also includes concrete examples and the data returned (descriptions and custom fields), making it easily distinguishable from sibling list tools.

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

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

The description implies this should be used when an agent needs to enumerate available document types, but it provides no explicit when-to-use/when-not-to-use guidance or comparison with alternatives. Its intended context is reasonably clear from the resource name, but the guidance is 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?

There are no annotations, so the description carries the burden of behavioral disclosure. It explicitly states that only WIP-status documents are returned and that owner filtering is optional, which makes the tool's behavior predictable. The read-only nature is reasonably implied by 'List' and 'Returns', and no destructive side effects are suggested.

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

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

The description is two focused sentences with no filler. The core action and status are front-loaded, and the optional filter is stated clearly at the end.

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 list tool with one optional parameter and no nested objects or output schema, the description provides enough context to invoke it correctly: it names the resource, the status filter, and the optional owner filter. It does not mention pagination or ordering, but those are minor gaps for this low-complexity tool.

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

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

Schema description coverage is 100%, and the schema already documents the owner parameter as 'Filter drafts by owner email address'. The description repeats this in prose ('Optionally filter by owner email address') but adds no new semantic detail beyond what the schema provides.

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

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

The description uses a specific verb ('List') and resource ('draft documents in Hermes'), and further clarifies that drafts are WIP-status documents. This clearly distinguishes the tool from siblings like hermes_list_products and hermes_list_projects and from hermes_get_document.

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

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

The description clearly indicates when to use the tool: when listing draft/WIP documents, with an optional owner filter. It does not explicitly mention alternatives or exclusions, such as using hermes_search for broader queries, but the intended context is unambiguous.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly states the operation is a list (read-only) and defines the scope as all configured products/areas in the Hermes instance. It does not describe the exact return format or pagination, but for a zero-parameter listing tool this is largely sufficient.

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

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

The description is two short sentences with no filler. The main action and resource are front-loaded in the first sentence, and the second sentence adds practical usage guidance. Every word earns its place.

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

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

This is a very simple tool with no parameters and no output schema. The description fully covers what the tool returns and why an agent would call it, making it complete for the tool's complexity level.

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 schema has zero parameters and 100% coverage, so there is no parameter documentation burden. The description reinforces that no filters are needed and implies the return values are valid product filter values, which is useful context beyond the empty 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 uses a specific verb ('List') and resource ('all products/areas configured in this Hermes instance'), making the tool's function immediately clear. It also distinguishes itself from sibling tools like hermes_list_projects and hermes_list_document_types by naming a distinct resource type.

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 explicitly notes the tool is useful for knowing valid product filter values when searching, which gives the agent a concrete use case. It does not explicitly mention when not to use it or name alternative tools, but the use case is clear enough for such a simple list 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?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only listing operation and the grouping purpose, but it does not describe pagination behavior, ordering, or response format. The page parameter in the schema partially compensates for the pagination 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?

The description consists of two short sentences with no filler. The core action and resource are front-loaded, and the second sentence adds relevant domain context without unnecessary verbosity.

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's very low complexity—one optional pagination parameter and no required inputs—the description plus schema is sufficient for basic invocation. It could mention return shape or when to choose this over sibling list tools, but these omissions are minor for this use case.

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 only parameter, page, is already fully described in the input schema with type, default, minimum, and a description. The tool description adds no additional parameter semantics, and the schema coverage is 100%, 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 clearly states the action ('List') and the specific resource ('projects'), and adds useful domain context ('in Hermes') plus the meaning of projects ('group related documents together'). This distinguishes it from sibling tools like hermes_list_products and hermes_list_drafts.

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 statement 'Projects group related documents together' implicitly suggests this tool is useful when needing to enumerate project groupings, but it does not explicitly state when to prefer this over alternatives such as hermes_list_products or hermes_search. Usage context is only implied, 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?

No annotations are provided, so the description carries the burden of behavior disclosure. It communicates that this is a read-only operation ('Get') and that authentication via session cookie is involved. However, it does not mention response format, potential errors, or any side effects, though those are less critical for a zero-parameter profile lookup.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the secondary usage hint adds value without redundancy.

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

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

For a zero-parameter read-only profile endpoint with a simple purpose and no output schema, the description is sufficiently complete. An agent can determine what this tool does and when to call it without additional 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?

The tool has zero parameters, so there is no parameter meaning to add beyond the schema. The baseline of 4 applies because the absence of parameters makes parameter documentation unnecessary.

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

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

The description uses a specific verb and resource: 'Get the currently authenticated user's profile in Hermes.' This clearly distinguishes it from the sibling tools, which all operate on products, projects, drafts, or documents.

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 explicitly states a concrete use case: 'Useful to confirm the session cookie is working.' It does not name alternative tools or when not to use it, but no sibling tool appears to be a direct alternative for retrieving the current user's profile.

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 behavioral burden. It discloses key effects: the document moves from WIP to In-Review and notifies assigned approvers. It does not address permissions, reversibility, failure modes, or output behavior, so it is informative but not fully transparent.

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 concise sentences with the primary action and state change first, followed by prerequisite and ID requirement. No fluff or repetition; every sentence carries useful information.

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

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

For a single-parameter tool with no annotations and no output schema, the description adequately covers the action, side effects, prerequisite, and parameter semantics. Minor gaps around error handling and permissions exist, but the tool is simple enough that this feels sufficient.

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

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

Schema description coverage is 100% and already explains document_id as the SharePoint objectID of the draft. The description reinforces this by specifying it must be a draft and can come from list/create operations, but it doesn't add substantial new meaning 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 states a specific verb (Publish/request review), the resource (draft document), and the exact state transition (WIP to 'In-Review'). It clearly differentiates from nearby siblings like hermes_update_draft, hermes_approve_document, and hermes_get_document by focusing on the publication-for-review action.

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

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

Provides a clear prerequisite: approvers must already be set, and explicitly directs users to hermes_update_draft to add them. It also scopes the document_id to a SharePoint objectID of a draft. It lacks an explicit when-not-to-use or exclusion list, but the usage context is solid.

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 burden and discloses the search scope (published documents only), the result shape (titles, owners, product areas, document types), and a critical failure mode — passing docNumber to hermes_get_document returns 404. Pagination behavior and empty-result semantics are left to the schema and inference, which keeps this from a 5.

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

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

Three sentences with zero filler: purpose first, then the result contract, then a caution about the docNumber pitfall. Every sentence carries operational value, and the critical integration warning is placed last without burying the purpose.

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 or annotations, the description compensates by specifying the result fields the agent can expect and the exact follow-up contract with hermes_get_document. The notable omission is explicit treatment of pagination and empty-result behavior, which the schema only partially covers via the page and hits_per_page parameters.

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

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

Schema description coverage is 100% with all five parameters documented, so the baseline is 3. The description adds no parameter-specific semantics beyond the schema (e.g., query operators, case sensitivity, or how product/doc_type filters combine), so it neither improves nor degrades the 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?

States a specific verb and resource ('Search documents in Hermes using full-text search') and immediately scopes behavior to 'matching published documents,' which distinguishes it from sibling draft/list tools. It also names its follow-up sibling, hermes_get_document, making the tool's role in the workflow 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?

Provides explicit workflow routing: results contain an objectID that must be passed to hermes_get_document, and warns against passing docNumber. However, it does not contrast itself with list-based siblings (e.g., hermes_list_drafts) or state when browsing is preferable to searching, so the when-to-use guidance is partial but clear.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates that this is a mutation, limits the operation to published documents, and enumerates supported fields and valid statuses, but it does not describe side effects, permission requirements, list-replacement semantics, or return behavior. The schema covers some parameter-level replacement behavior, but the tool description itself remains shallow on consequences.

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

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

The description is short and front-loaded with the primary action and scope. The final sentence repeating the valid statuses is slightly redundant with the parenthetical list earlier, which keeps it from a perfect conciseness score, but overall it is efficient and easy to scan.

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 nine parameters and full schema coverage, the description provides sufficient scoping: it names the resource, lists mutable fields, gives valid statuses, and routes draft usage away. It falls slightly short of fully complete because there is no output schema and the description does not state what the update returns or disclose any side effects beyond the update itself.

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 input schema already documents all nine parameters in detail, including the custom_fields name/type/display_name constraints. The tool description only repeats field names and valid statuses, adding no new parameter-level meaning 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 opens with a specific verb and resource: 'Update a published document's metadata in Hermes.' It lists exactly which metadata fields are supported and explicitly distinguishes this tool from hermes_update_draft, so an agent can identify what it does without relying on 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?

It explicitly states the intended scope ('published document') and gives a direct when-not-to-use instruction: 'For drafts (WIP), use hermes_update_draft instead.' This provides clear routing to the main sibling alternative while other siblings are distinguishable by name and purpose.

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 behavioral disclosure burden. It does explain partial-update semantics ('only provided fields are changed') and the WIP-only restriction, which is valuable. However, it does not mention what the operation returns, whether there are permission requirements, or how errors are surfaced, leaving meaningful gaps 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?

The description is three sentences with no filler: purpose/WIP restriction, partial-update semantics, and the source of document_id. The information is front-loaded and every sentence contributes to 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?

The combination of description and a fully covered schema gives an agent the necessary info to call the tool correctly: WIP-only eligibility, patch semantics, required document_id, and detailed custom field rules. Missing behavioral details like response shape or non-WIP failure behavior are notable but not blockers given the rich schema.

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 input schema already documents every parameter, including the detailed custom_fields object. The description adds the useful patch behavior ('only provided fields are changed') but mostly lists fields that the schema already names, so it does not substantially extend the schema's semantic value.

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

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

The description states a specific verb ('Update') and resource ('a document draft in Hermes') and adds the critical WIP-status constraint, which distinguishes this tool from the sibling hermes_update_document. It also enumerates the updateable fields, making the tool's scope immediately clear.

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

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

The description clearly scopes usage to WIP drafts and explains that all fields are optional with only provided fields changed, plus the required document_id provenance. However, it does not explicitly name an alternative tool for non-WIP documents, so the when-not-to-use guidance is mostly implicit rather than explicit.

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