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. 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?

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?

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.