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

No annotations are provided, so the description carries the full burden. 'Add a comment' implies a mutating operation, but it does not disclose permissions, idempotency, whether the comment is appended or replaces existing comments, or what the response will contain.

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

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

A single, front-loaded sentence with no filler. Every word contributes to the core action and target.

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 mutation with no output schema, this is adequate but minimal. It covers the basic action, but omits any guidance on return values, edge cases, or behavioral expectations beyond the literal sentence.

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 documentId and body are already documented in the schema. The description adds no additional parameter-level meaning, which matches the baseline of 3.

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 the clear verb 'Add' with a specific resource ('comment') and target ('document'). This distinguishes it from sibling tools like delete_document or list_comments, though it does not explicitly name alternatives.

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

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

Usage is implied: use this tool when you need to add a comment to a document. However, there is no explicit guidance on when to choose this over list_comments or how it relates to update_document, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the full burden for a mutating schema-change operation. It does not state required permissions, whether adding a property is reversible, what happens if the name collides with an existing column, or what the call returns. Only the type default is disclosed, which is already in the schema.

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

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

Three short sentences, front-loaded with the action, then the type vocabulary, then the conditional options format. Every sentence earns its place and nothing is padded.

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

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

With no annotations and no output schema, the description should cover side effects and result shape for a write operation, and it does not. It is adequate for choosing arguments but incomplete for predicting consequences of the call.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the enum and the options sub-object shape; baseline is 3. The description restates the type list and the options format without adding syntax, constraints, or examples beyond the schema, so it adds little marginal meaning.

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 with clarifying parenthetical: "Add a new property (column) to a collection." An agent immediately knows this creates a schema field. It does not explicitly distinguish itself from sibling delete_property or list_properties, but the verb 'add' makes the direction obvious.

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 creation verb and the note that options only apply to SELECT/MULTI_SELECT, which helps the agent pick valid argument combinations. However, there is no explicit when-to-use guidance, no mention of prerequisites (does the collection need to exist unlocked?), and no reference to the sibling delete_property as the inverse 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?

No annotations are provided, so the description carries the full burden. It states only the core mutation ('create') but does not disclose whether a collection must already exist, how ID assignment works, whether properties are validated, what side effects occur, or what the response will be. This is a key transparency gap for a write 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?

The description is a single, efficient sentence with no redundant wording. It is easy to parse, but its brevity leaves out behavioral and usage context that would improve the definition.

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 create operation with nested properties, no output schema, and no annotations, the description is incomplete. It does not explain what happens after creation, whether a response returns the new document, how to locate the collection, or how properties and content relate to the document. The provided context signals do not compensate for this 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 schema already documents all four parameters. The description itself adds no parameter-level meaning beyond what the schema provides, meeting the baseline 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 uses a clear verb+resource pair ('Create a new document') and clarifies the container ('in a collection'). It distinguishes this from sibling tools that update, delete, or list documents. However, it is quite close to the title and doesn't add much depth about the collection concept.

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

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

The description implies usage when you want to add a new document, but it gives no explicit when-to-use guidance, no conditions, and no pointers to alternatives such as update_document for existing documents or list_collections to find collection IDs. There are no exclusions or prerequisites 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?

With no annotations provided, the description carries the full burden. It does disclose a key behavioral distinction: archive=true moves to trash, otherwise it is permanently deleted. Yet it omits consequences like whether trash items are recoverable, permission requirements, cascading effects on comments, or what response 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?

The description is two sentences with no filler. The primary statement is front-loaded, and the conditional behavioral detail is placed in the second sentence. Every word earns its place.

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

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

For a simple delete tool with two parameters and no nested objects, the description is largely complete: it identifies the action, required resource, and the important archive distinction. It could mention side effects on related resources or error conditions, but those are secondary for basic 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%, so the schema already documents both parameters. The description adds only modest interpretation by rewording the archive flag ('moved to trash instead of being permanently deleted'), which is essentially the same as the schema's 'Archive instead of hard-delete.' Therefore 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 clear verb and resource: 'Delete a document.' It also clarifies the two possible outcomes (trash vs permanent deletion), which distinguishes it from siblings like create_document and update_document. However, it does not explicitly name or contrast itself with sibling tools.

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

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

The tool's purpose is implied by its name and description: use when a document should be removed. The archive condition provides parameter-level guidance but no explicit when-to-use versus alternatives like update_document or list_documents. There are no exclusions or prerequisites mentioned.

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 critical data-loss behavior: 'Removes the column and all its values.' However, it says nothing about irreversibility, required permissions/ownership of the collection, or whether dependent views, formulas, or automations referencing the column are affected.

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 right after the action statement. Nothing could be removed without losing 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 simple two-parameter destructive tool with full schema coverage and no output schema, the description covers what it does and what data is lost. The remaining gap is safety context — irreversibility and permission requirements — which matters more than usual given the absence of annotations.

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 both parameters are documented in the schema, so the baseline of 3 applies. The description's 'by name' adds only a slight hint that name is the addressing key, not additional semantics 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 and resource ('Delete a property (column) from a collection') plus the lookup key ('by name'), which makes it trivially distinguishable from siblings such as add_property and list_properties. The parenthetical '(column)' disambiguates the domain term 'property' for an agent unfamiliar with the vocabulary.

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

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

No guidance on when to use this versus alternatives, no prerequisites, and no exclusions (e.g., when a property should instead be renamed or when deletion is blocked by dependent views/formulas). Usage is only inferable from the purpose statement itself.

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 behavioral burden. It makes the read-only nature clear through 'Get' and adds that property values are returned, but it does not disclose error behavior, permissions, or whether a missing ID returns an error or empty result.

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 concise sentence with no filler. Every word contributes meaning: 'single', 'by ID', and 'including its property values' are all useful to the agent.

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 one-parameter read operation with no output schema, the description is sufficient: it tells the agent the required input and the returned content. It could optionally mention not-found behavior, but that is not essential for invoking the tool 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%, with documentId already described as 'Document ID', so the baseline is 3. The description adds essentially nothing about parameter format beyond 'by ID', though it does clarify the return content by mentioning property values.

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

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

The description uses a specific verb ('Get') and resource ('single document by ID'), and 'single' clearly differentiates it from sibling tools like list_documents and create_document. An agent can immediately tell this is the fetch-one-document operation.

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 context of needing a single document by ID is implied, and 'including its property values' hints at what the caller receives. However, it does not explicitly state when to prefer this over list_documents or mention any exclusions or alternative 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?

With no annotations, the description carries the behavioral burden. It adds useful scope and terminology context, but does not disclose return format, ordering, pagination, or any constraints. The read-only nature is implied by 'List' but not explicit.

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

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

The description is a single sentence with no filler, front-loading the action and scope immediately. Every word contributes 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 zero-parameter tool with no output schema, the description adequately identifies the operation and scope. It could mention that the result is a list of collection definitions, but this is largely implied by 'List all collections'.

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 the baseline is 4. The description appropriately does not need to explain parameter semantics since there are none to clarify.

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

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

The description states a specific verb ('List') and resource ('collections (databases)') within a defined scope ('Shoanta workspace'). It is clearly distinguishable from sibling tools like list_documents, which targets a different resource.

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

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

No guidance is provided about when to use this tool versus alternatives such as list_documents. The intended context is only implicit from the name and description, with no exclusions or routing cues.

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 only states that comments are listed, but does not mention ordering, pagination, response shape, permissions, or whether deleted/threaded comments are included.

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

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

The description is a single concise sentence with no fluff. It conveys the core action and object efficiently, and the structure is easy to parse quickly.

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

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

For a simple one-parameter read tool, the description is minimally sufficient to invoke it correctly because the documentId is clear. However, with no output schema and no annotations, the absence of return format or additional behavioral details leaves 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 100% and the documentId parameter is already described as 'Document ID'. The description adds a small amount of context by clarifying that comments are associated with a document, but does not significantly expand on 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 'List comments on a document' uses a specific verb and resource, and scopes it to a document, which clearly distinguishes it from siblings like list_documents, get_document, and add_comment. An agent can identify exactly what this tool does without needing to inspect the schema.

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

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

The description provides no guidance on when to use this tool versus alternatives such as add_comment or get_document. There is no mention of exclusions, prerequisites, or preferred use cases beyond the implied 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 provided, the description carries the full burden of behavioral disclosure. It only says 'List all documents' and does not state return format, pagination or ordering behavior, error handling, or whether it is strictly read-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 with no filler or redundant wording. Every word contributes to the core 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?

The operation is simple and the only parameter is fully documented, but with no output schema or annotations, the description could usefully mention what is returned and any default ordering or pagination 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?

The schema already describes collectionId with 100% coverage as 'ID of the collection (database)'. The description adds no additional parameter meaning, 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 (List), resource (documents), and scope (a collection), and is clearly distinguishable from siblings like get_document, list_collections, and list_comments.

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 intended use case is implied: retrieving all documents within a collection. However, it does not explicitly contrast with alternatives such as get_document for a single document or list_collections for 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?

No annotations are provided, so the description carries the behavioral disclosure burden. The word "List" and phrase "all property definitions" imply a read-only, complete enumeration operation, but the description does not explicitly state read-only safety, permissions, or whether results are paginated.

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

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

The description is a single efficient sentence with no wasted words, and the core action and scope are front-loaded.

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 one required, fully documented parameter and no output schema, the description is largely complete. It could be slightly stronger by clarifying read-only behavior or result completeness, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the single collectionId parameter is already fully documented as "ID of the collection (database)." The description reinforces that properties belong to a collection, but adds no syntax, format, or validation details 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 and resource: "List all property (column) definitions for a collection." This is clear and distinguishes it from siblings like list_collections, list_documents, add_property, and delete_property, though it does not explicitly name those alternatives.

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

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

Usage is implied by the description: use this to inspect schema/property definitions for a known collection. However, there is no explicit guidance on when to use this versus list_collections, list_documents, or other sibling tools, and no stated prerequisites or exclusions.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals that documents travel with the collection and that membership in the target workspace is required, but it never states whether the source copy is removed (move vs. copy), whether the operation is reversible, or what happens to name collisions in the target.

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 waste, with the core action stated first and the prerequisite following. Nothing redundant.

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 should explain more about side effects and failure modes. It covers the action and the auth prerequisite adequately, but whether this is destructive to the source and what the response contains are left 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 100%, so both parameters are already fully documented in the schema. The description only restates that a target workspace slug is required, adding no format, lookup, or validation detail beyond structured fields — baseline 3.

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 (transfer) and resource (a collection and its documents), plus the destination scope (another workspace). This is unambiguous, though there are no similarly-named siblings to contrast against, so no explicit differentiation is offered or 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?

Gives a clear precondition — the API token's user must be a member of the target workspace — and states the required input (target workspace slug). It does not cover when not to use it (e.g., moving a single document belongs to update_document) or any alternatives, keeping it just 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?

With no annotations, the description carries the full burden of behavioral disclosure. The phrase 'Only provided fields are changed' is valuable because it reveals partial-update semantics that are not obvious from the schema alone. However, it does not mention permissions, reversibility, or how nested properties are merged or replaced.

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 front-loaded sentence with no filler. It states the operation, the target, the affected fields, and the key partial-update behavior 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?

For a mutation tool with no annotations and no output schema, this is adequate but minimal. It covers the core operation and the partial-update rule, yet it leaves out explicit usage guidance, return/response expectations, and any error or authorization context that would help an agent 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 100%, so every parameter already has a description in the schema. The description adds the meaningful patch-like semantic that only provided fields change, but it does not go beyond what the schema and that sentence already convey.

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 ('Update document') and enumerates the exact affected attributes: title, content, and/or property values. This clearly distinguishes update_document from create_document, get_document, delete_document, and the comment 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?

No explicit when-to-use or when-not-to-use guidance is provided, and sibling tools are not named. Usage is implied by the verb and resource rather than stated, so an agent must infer that this is for modifying an existing document rather than creating or deleting one.

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