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

Annotations already indicate a write operation (readOnlyHint false, openWorldHint true, idempotentHint false). The description adds that duplication stays under the same parent and allows a new title, which is useful. However, it does not disclose whether folder page duplication is recursive (copying children) or describe permissions/side effects, which are important given openWorldHint.

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 concise sentences with the core action first, followed by title handling and applicability. No fluff or redundancy.

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

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

As a mutation tool with openWorldHint and no output schema, the description should clarify return values and side effects. It does not explain how folder pages are duplicated (whether subpages are copied) or any constraints. This ambiguity leaves an agent without critical information for correct invocation.

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

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

The schema provides descriptions for index and newTitle, but not for required collectiveId and pageId. The tool description repeats newTitle behavior but does not explain collectiveId or pageId, nor does it clarify index semantics. With 50% schema coverage, the description fails to compensate for missing parameter documentation.

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 a specific action (duplicate) on a specific resource (page) under the same parent, and notes title handling. It distinguishes from siblings like create_page, move_page, and rename_page by emphasizing duplication. The scope (leaf and folder pages) adds clarity.

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 when to use it (when duplicating a page) but provides no explicit guidance on alternatives or exclusions. It does not mention when not to use it or how it differs from create_page or move_page. The context is clear but lacks explicit routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds genuine value by disclosing that creating a Collective also creates a Nextcloud Team, which is behavioral context beyond the annotations. However, it does not disclose failure modes, name-conflict behavior, or what happens on duplicate names. No contradiction with annotations.

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

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

Two sentences with no filler, front-loading the core purpose before the side effect and the optional parameter. Efficient and scannable; nothing extraneous.

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 2-parameter create tool with annotations covering the mutation profile, the description covers the purpose and the important Team-creation side effect. No output schema exists and the description doesn't describe the return value, but that is a minor gap for a create operation. Reasonably complete.

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

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

Schema coverage is 100% — both name and emoji are documented in the schema, including that name becomes the folder name in Files. The description merely echoes the emoji parameter ('Optionally set an emoji icon') without adding anything beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb (Create) and resource (Collective), and adds the meaningful side-effect that the underlying Nextcloud Team is also created. The 'create' verb clearly differentiates it from siblings like update_collective, list_collectives, and delete_collective. Unambiguous and specific.

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, and no alternatives are named. Usage is implied by the verb and tool name rather than stated. The side-effect note about creating a Nextcloud Team provides some decision-relevant context, but nothing routes the agent away from the closely related update_collective or delete_collective.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is consistent with the write nature. It adds context that the share is public, that edit can be enabled later via update_share, and that a token is returned—useful behavioral details beyond 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?

The description is a single clear sentence with an additional URL-building hint. It is front-loaded and concise, with no wasted words.

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

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

With no output schema, the description appropriately explains the return token and how to build the final URL. It doesn't cover error cases or permissions, but for a simple two-parameter tool with annotations covering safety, it is reasonably complete.

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

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

Schema description coverage is 50%; only password has a description. The tool description mentions the collective as the target but doesn't explicitly explain the collectiveId parameter or the password's role beyond what the schema already says. It fails to compensate for the missing schema documentation on collectiveId, leaving the agent to infer its meaning from the tool's name and description.

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 tool creates a public share link for a Collective, with a specific verb and resource. It implicitly distinguishes from page-level shares and mentions the update_share sibling for enabling edit, making its purpose 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?

The description explains the sharing model (public, read-only by default, editable later) and how to construct the URL, which gives an agent context for when to use it. It doesn't explicitly contrast with create_page_share or list_shares, but the scope is clear enough.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the mutating and non-destructive nature. The description adds the key side effect of auto-promoting a leaf page to a folder, which is not evident from the annotations. It does not disclose permission requirements or error behavior, but the addition of the promotion effect provides meaningful context beyond the structured fields.

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 core action is front-loaded ('Create a new page under a parent'), followed immediately by the key behavioral note and the optional template feature. Every sentence 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?

The description covers the essential purpose, the promotion side effect, and the optional template, which together with the schema (that explains the landing page for root and marks required fields) provide sufficient context for an agent to invoke the tool correctly. It does not mention permissions or failure modes, but for a create tool with this schema coverage, it is reasonably complete.

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

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

Schema coverage is 83%, so the schema already documents most parameters. The description only restates the roles of parent (parentPageId) and template (templateId) without adding new semantic details. For example, it does not clarify the meaning of collectiveId or any constraints beyond what the schema provides. This aligns with the baseline 3 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 clearly states the tool's function with a specific verb ('Create') and resource ('page'), and specifies the context ('under a parent'). It also adds two distinctive behaviors—promoting a leaf page to a folder and optional template initialization—which distinguishes it from sibling tools like update_page, delete_page, and copy_page.

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 when to use the tool (to create a page under a parent, optionally from a template) but does not explicitly mention alternatives or conditions for when not to use it. It lacks direct routing to sibling tools like copy_page or list_templates, 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?

The description discloses the creation side effect, public nature, and returned token/URL. Annotations already indicate non-idempotent and non-destructive, so the description adds useful context without needing to restate those flags.

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, focused sentence that front-loads the action and includes key return information without unnecessary fluff.

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?

It covers the core purpose, return value, and URL construction. It does not mention related share management operations, but for a simple create action the essential context is present.

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

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

The password parameter has a helpful schema description, but collectiveId and pageId are not elaborated in either schema or description. Their names are somewhat self-explanatory in context, but the low schema coverage is not fully compensated.

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 tool creates a public share link for a single page, distinguishes it from a whole-Collective share, and explains the return value and URL format.

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 contrasts with sharing a whole Collective, implying when to use this tool versus a collective-level share. It could more directly name sibling tools like create_collective_share, but the primary usage context is 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds minimal behavioral insight beyond the obvious creation action. It does not mention potential side effects such as duplicate tag handling or whether the creation is idempotent, leaving room for ambiguity about the operation's full 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 a single, focused sentence that directly conveys the action, required inputs, and a concrete example for the color format. There is no redundant wording or unnecessary detail, making it highly concise and well-structured.

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

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

The description covers the core purpose and required parameters, but it omits several contextual details: the meaning of 'collectiveId' is not explicit, there is no mention of the return value (since no output schema is provided), and potential error conditions (e.g., invalid collective or duplicate tag name) are not addressed. This leaves some gaps for an agent relying solely on the description.

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

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

Schema coverage is 67% with descriptions for 'name' and 'color', and the tool description enriches the color parameter with an example format. However, the 'collectiveId' parameter lacks a description in both the schema and the tool description, forcing the agent to infer its meaning from the phrase 'in a Collective'. This partial coverage warrants a mid-range score.

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 verb 'create', the resource 'tag', and the scope 'in a Collective'. It also mentions the required parameters (name and color), making the purpose easy to understand. However, it does not explicitly contrast with sibling tools like update_tag or delete_tag, so it misses a slight opportunity for further clarity.

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 explicit guidance on when to use this tool. It mentions that a name and hex color are required but does not indicate prerequisites (e.g., the collective must exist) or situations where create_tag is preferred over update_tag. This leaves usage decisions largely to the agent's inference.

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

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds that it creates a template, but does not explain side effects, permissions, or duplicate behavior despite idempotentHint=false.

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?

Single concise sentence with no fluff; every word carries meaning and the primary action is 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?

Adequate as a minimal create-operation description, but lacks parameter context and usage guidance; given the low schema coverage, it is not fully self-contained.

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 low (only parentId has a description) and the description provides no additional meaning for collectiveId or title, leaving important parameters underdocumented.

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?

Clearly states the action ('Create'), the resource ('page template'), and the location ('in a Collective'), distinguishing it from related template operations like update or delete.

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 tool versus alternatives such as create_page or create_collective, nor any mention of prerequisites or conditions.

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

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

The description discloses that the deleted attachment is returned and that its ID is needed for restore_attachment, adding useful behavioral context beyond the destructiveHint and idempotentHint annotations. It does not mention all side effects, but the annotations cover core 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?

Two concise sentences without redundancy. The description is front-loaded with the core action and follows with relevant return 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?

The tool is simple and the description covers the core action and return value, but missing parameter context and lack of error/edge-case guidance leaves some ambiguity for an agent invoking the tool with three required 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?

Only filename is described in the schema, and the description does not clarify the roles of collectiveId and pageId. With schema coverage at 33%, the description should compensate by explaining parameter relationships, but it does not.

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

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

The description clearly states the action ('Delete an attachment') and the target resource ('from a page'), and distinguishes this from related operations like restore_attachment, list_attachments, and upload_attachment.

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 identifies when to use the tool (to delete an attachment) and references the complementary restore_attachment operation, though it does not explicitly discuss when not to use it or compare with alternative deletion/restoration flows.

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?

Beyond the annotations (destructive, idempotent), the description adds key behavioral context: it performs a soft delete, moves the item to trash, and is recoverable. This clarifies the exact nature of the destructive action, which annotations alone do not convey.

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

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

The description is concise, using two short sentences to convey the primary action and the alternative. It is well-structured and free of unnecessary detail.

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

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

The description provides sufficient context for a simple soft-delete operation, including recoverability and the existence of a trash. It does not mention error cases or permissions, but these are not critical for this straightforward action.

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 one integer parameter 'id' with no description, and the tool description does not explain what 'id' refers to. While the tool name suggests it is the Collective's ID, this is not explicitly stated, leaving the parameter's meaning under-specified.

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 tool's function: soft-deleting a Collective by moving it to trash, with recoverability. It also explicitly distinguishes it from the permanent deletion alternative, making its purpose 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?

The description provides explicit guidance on when to use this tool versus the permanent deletion tool, noting that this is for recoverable deletion and directing to permanently_delete_collective for permanent removal.

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?

Discloses the destructive side effect (trash), recoverability, subtree cascade behavior, and the Landing page restriction. Annotations already include destructiveHint true, and the description adds meaningful behavioral details without contradicting them.

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, each adding distinct information: the primary action, the subtree side effect, and the Landing page exception. No redundancy or fluff.

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

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

Covers the essential behavior, side effects, and exceptions for a simple mutation. Lacks explicit parameter semantics and return/error behavior, but there is no output schema and the operation is low-complexity.

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 has 0% description coverage and the description adds no meaning beyond the parameter names. collectiveId and pageId are self-explanatory to some degree, but the description does not clarify their relationship, whether pageId is scoped to the collective, or any other parameter-specific requirements.

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?

Description opens with a clear verb and object ('Trash a page'), distinguishes recoverable trash from permanent deletion, and explicitly names the one exception (Landing page), making the tool's purpose unambiguous relative to sibling delete/purge operations.

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 when-not-to-use guidance: folder pages move their entire subtree, and the Landing page cannot be deleted and should be handled via delete_collective. It does not explicitly contrast with purge_page or restore_page, but 'recoverable' and 'trash' make the primary use case 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?

Annotations already declare destructiveHint: true, readOnlyHint: false, and idempotentHint: true. The description adds meaningful context by stating 'The link stops working immediately for everyone holding it,' which clarifies the immediate impact. It also clarifies the scope distinction (page vs. collective). No contradiction with annotations; it complements them.

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 long with zero fluff. It front-loads the core action and immediate effect, then provides the parameter-specific guidance. 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 simple destructive operation with three parameters and no output schema, the description covers the essential behavioral aspects (immediate effect, page/collective distinction). Annotations cover destructive and idempotent hints. The description does not mention failure scenarios or prerequisites, but these are not critical for correct invocation. It is complete enough for an agent to call 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 description coverage is 67% (token and pageId have descriptions, collectiveId does not). The description adds value by clarifying that token comes from list_shares and by explaining the pageId usage. However, collectiveId is not explained in the description, though its purpose (identifying the collective) is fairly obvious from the name and required status. Overall, the description enhances parameter understanding 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 clearly states the action ('Revoke a public share link') and the resource (share link). It distinguishes between page shares and Collective-wide shares, which differentiates it from sibling tools like create_share, update_share, and list_shares. The immediate effect is also stated, making the purpose 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?

The description provides explicit usage guidance for the pageId parameter ('Pass pageId for a page share; omit it for the Collective-wide share'), which is a key decision point. However, it does not mention alternatives (e.g., update_share for modifying a share) or when not to use this tool. It implies token retrieval from list_shares but does not explicitly state that. Overall, clear context without 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?

Annotations already indicate destructive and idempotent behavior. The description adds no extra details like cascading effects, but for a simple delete operation it is sufficiently 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?

The description is a single, concise sentence that fully conveys the purpose without unnecessary words.

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

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

For a simple delete operation with no output schema, the description is complete. It covers the essential action and target without missing critical 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 parameter names (collectiveId, tagId) are self-explanatory, but neither the schema nor the description provides further details. Since the description does not compensate for the lack of parameter docs, the score is baseline.

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

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

The description clearly states the action (Delete) and the target (a tag from a Collective), which distinguishes it from other tag-related tools like list_tags or create_tag.

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 is straightforward for a delete operation and implies usage when a tag should be removed. It does not explicitly mention alternatives, but the intent is clear given the sibling tools.

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

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

The description does not disclose whether deletion is permanent, whether it affects pages using the template, or any other side effects, despite the destructiveHint annotation.

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, and clear sentence with no unnecessary words.

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

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

The description is minimal and lacks important context such as permanence, impact on associated data, or prerequisites, making it incomplete for a destructive operation.

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

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

The parameter names (templateId, collectiveId) are self-explanatory and the schema fully covers them, but the description adds no additional context about their relationship or usage.

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 (delete) and the resource (a page template), making its purpose immediately 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?

The description provides no guidance on when to use this tool over other delete operations (e.g., delete_page, delete_collective) or any prerequisites or side effects.

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

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

Annotations already declare readOnlyHint=false (mutation), destructiveHint=false (not destructive), and idempotentHint=true. The description adds little beyond that, only implying the favorite is scoped to the authenticated user. It does not describe any additional side effects, permissions, or response behavior, but does not contradict the annotations either.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It states the action, target, and scope immediately, which is ideal for an agent scanning the tool list.

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 mutation tool with two required integer parameters and no output schema, the description is insufficiently complete. It lacks any explanation of the parameters (especially collectiveId), which are not covered by the schema. It also does not mention what happens on success (e.g., no return value or confirmation), though that is minor for a favorite action.

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 0%, so the description must explain the parameters. It does not mention pageId or collectiveId at all. While the parameter names are somewhat self-explanatory (page identifier and collective/space identifier), the description provides no explicit guidance on their meaning or relationship, leaving an agent to infer from the tool name.

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 ('Mark') and resource ('a page as a favorite') and clarifies it's for the authenticated user. This distinguishes it from sibling unfavorite_page and other page operations, so an agent knows exactly what action this performs.

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 is clear: use this to favorite a page for the current user. It doesn't explicitly mention when not to use it or alternatives like unfavorite_page, but the action is unambiguous and the sibling list makes the opposite operation obvious. No exclusions are stated, but none are critical here.

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?

Beyond readOnlyHint/idempotentHint annotations, the description discloses the return format (utf8 or base64 with encoding stated) and the 5 MB refusal. No contradictions with annotations.

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

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

Two sentences, no filler. The purpose is front-loaded, and the size limitation is stated clearly. Every sentence adds value.

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 tool with annotations covering safety, the description covers purpose, output format, and a size constraint. It doesn't mention error cases or parameter relationships, but these are not critical for a straightforward download operation.

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

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

Schema already documents encoding and filename with descriptions. The description does not add parameter semantics for pageId and collectiveId, which remain undocumented. Coverage is 50%, and the description doesn't compensate for the missing two.

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: 'Download an attachment's contents.' Clearly distinguishes from sibling attachment tools (upload, delete, rename, restore) by naming the download action and specifying the output format.

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 an explicit exclusion for files over 5 MB, directing users to fetch them directly from Nextcloud. This gives clear when-not guidance. Does not explicitly contrast with list_attachments, but that is a listing tool and not a competitor for this action.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds the behavioral detail that it scans the linkedPageIds field on all pages in the Collective, which hints at the potential cost and scope. This goes beyond the annotations and gives useful context about the underlying implementation.

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, well-structured sentence that front-loads the purpose ('Find pages that link to the given page') and then explains the mechanism. There is no redundant information or unnecessary detail, making it highly efficient.

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

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

For a simple read-only tool with two integer parameters and no output schema, the description provides enough to understand the operation. It implies the return of a list of pages, though it doesn't explicitly describe the output format. The openWorldHint might suggest partial results, but that isn't addressed. Overall, it is adequate for an agent to call 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 description coverage is 0%, so the description must compensate for the lack of parameter explanations. It indirectly refers to 'the given page' (pageId) and 'the Collective' (collectiveId), but doesn't explicitly state that collectiveId scopes the search and pageId identifies the target page. This is a partial compensation but not fully explicit, leaving some ambiguity for an agent.

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 tool's function: finding pages that link to a given page. It specifies the mechanism (scanning linkedPageIds) and the scope (in the Collective), making it distinct from siblings like get_page or list_pages, which handle different page-related operations. No other sibling tool addresses backlinks, so the purpose is unambiguous.

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

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

The description implies when to use the tool: whenever you need to identify incoming links to a specific page. It doesn't explicitly name alternatives, but the unique functionality makes the usage context clear. It doesn't provide exclusions or alternative suggestions, but the purpose is self-explanatory enough for an agent to decide.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds clarity about the return format (metadata block and markdown body), which is useful context.

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, focused sentence that communicates the essential information without unnecessary detail.

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

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

The description explains the output format well, which is important given the absence of an output schema. It does not cover error cases, but for a simple read operation this is acceptable.

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 parameter names 'collectiveId' and 'pageId' are somewhat self-explanatory, but the description provides no additional explanation and the schema has no parameter descriptions, leaving the relationship between the two IDs implicit.

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 (fetch), the resource (a page), and the output format (markdown with metadata block and body), distinguishing it from other page-related 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 verb 'fetch' implies usage when retrieving a page's content, but there is no explicit guidance on when to use this tool versus alternatives like list_pages or get_backlinks.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns 'metadata and markdown body', which clarifies the output format beyond the annotations. No contradictions.

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 concise sentences with no redundancy. All information is relevant and directly useful.

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 operation, the description covers the essential context: what it does, what it returns, and a typical use case. No output schema exists, so no need to elaborate further.

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 50%: templateId has a helpful description ('from list_templates'), but collectiveId has none. The tool description does not add any additional parameter context, leaving collectiveId's role ambiguous. This is below average given the incomplete 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 clearly states the tool reads a page template's metadata and markdown body, and explicitly links to create_page(templateId) for inspection. This provides a specific verb and resource, making the purpose unambiguous even without comparing to 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?

It provides a concrete use case ('Use this to inspect what create_page(templateId) will produce'). While it doesn't explicitly contrast with alternatives like list_templates, the usage scenario is clear enough for an agent to decide when to call it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds behavioral context by specifying exactly what is returned (name, size, content type, markdown path), which is beyond the annotations. It does not contradict the annotations and provides useful detail about the output.

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 that front-loads the action and includes the key output details. There is no wasted wording, making it highly efficient and easy to parse.

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 operation with two parameters, the description covers the purpose and the return fields. It lacks an explanation of collectiveId, which is a completeness gap, but given the simplicity of the tool and the presence of annotations, it is mostly adequate. The missing parameter clarification prevents a perfect score.

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 0%, so the description must compensate for parameter meanings. It explains 'page' implicitly through 'for a page', but does not clarify the role of collectiveId, which is a required integer parameter. The description adds minimal semantic value beyond the schema, leaving the collectiveId parameter under-documented.

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

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

The description clearly states the action 'List' and the resource 'attachments for a page', and it enumerates the returned fields (name, size, content type, relative markdown path). This distinguishes it from sibling tools like get_attachment (single attachment) and delete_attachment, making its purpose 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?

The description conveys when to use this tool: whenever you need a list of attachments for a page. It does not explicitly mention alternatives or exclusions, but the context is clear given the sibling tools like upload_attachment and get_attachment. It lacks explicit when-not-to-use guidance, so it earns a 4 rather than 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?

The description discloses the authentication requirement ('authenticated user') and scope ('has access to'), which are behavioral traits beyond what annotations provide. It also states the return fields, adding value. The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description supplements this with scope and return info without contradicting annotations.

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

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

The description is two concise sentences. The first sentence front-loads the core purpose ('List all Collectives the authenticated user has access to'), and the second specifies the return payload. There is no filler or redundancy; 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 zero-parameter list tool, the description is complete: it states the operation, scope, authentication, and return fields. No output schema is provided, but the description explicitly lists what the tool returns. No missing information prevents an agent from calling 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 zero parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 4, and the description correctly avoids adding any unnecessary parameter information, leaving the schema empty and the description focused on behavior.

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 tool lists all Collectives the authenticated user has access to, specifying the verb 'List' and the resource 'Collectives'. It also enumerates returned fields (id, name, slug, emoji, permission levels), which distinguishes it from sibling tools like list_trashed_collectives, create_collective, and update_collective.

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 clear context for when to use the tool: when listing all accessible Collectives. It does not explicitly mention alternatives or exclusions (e.g., when to use list_trashed_collectives instead), but the scope and return fields make the intended use obvious. Since there are no exclusions or when-not-to-use guidance, it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety and idempotency are covered. The description adds value by specifying the return format (flat metadata with fields) and the guidance to reconstruct the tree via parentId. It does not mention potential pagination or exclusion of trashed pages, but these are minor gaps given the openWorldHint suggests a potentially large output.

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 concise with two sentences, front-loading the primary action and essential details. It avoids unnecessary words and effectively conveys the purpose and usage hint.

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 tool with annotations covering safety, the description adequately explains the return structure and usage. It could explicitly state that it lists only non-trashed pages (given list_trashed_pages exists) and mention if there are any limits, but these are minor gaps that do not hinder correct invocation.

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

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

Schema coverage is 100% for the single parameter, and the schema description already provides the source of the collectiveId. The tool description adds no additional meaning beyond what the schema offers, so a baseline score 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?

The description clearly states 'List all pages in a Collective' with a specific verb and resource, and specifies the return fields. It distinguishes from get_page (single page) and search (search-based) by focusing on the full listing. The addition of 'Use parentId to reconstruct the tree' clarifies the flat nature of the output, making it distinct from tree-structured 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?

The description clearly indicates when to use this tool (to list all pages) and provides a hint on how to use the returned parentId. However, it does not explicitly mention alternatives like get_page for single-page retrieval or list_trashed_pages for trashed pages. The existence of sibling tools implies these exclusions, but they are not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return-value semantics (version ids) and the relationship to restore_page_version, which is useful context beyond the annotations. It doesn't mention pagination or ordering, but that's minor given the simple nature.

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, concise, and front-loaded with the primary action. It delivers the essential information without any fluff. Every word contributes to understanding what the tool does and how to use the result.

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 simplicity (two integer parameters, no output schema, annotations covering safety), the description is mostly complete: it states the purpose and the return value. However, it doesn't explain the collectiveId parameter, which could cause confusion for agents unfamiliar with the domain. Since schema coverage is zero, this omission is a noticeable 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 0%, so the description must compensate by explaining the parameters. It does not mention collectiveId or pageId explicitly. The names are somewhat self-explanatory (pageId), but collectiveId is ambiguous without context. Since the description provides no parameter guidance, it fails to add value 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 clearly states the tool lists version history for a page and specifies the output (version ids). It also distinguishes itself from the sibling restore_page_version by explicitly linking the returned ids to that tool. This makes the purpose unmistakable and differentiates it from other page-related 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 usage: you use this tool when you need to see revision history or obtain version ids for restoration. It names the related tool (restore_page_version) and the linkage, which guides the agent. However, it doesn't explicitly state when not to use it or mention alternatives, but given the context it's clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the ordering-by-last-edit-time behavior, which is useful, but it does not mention pagination defaults (limit) or any edge cases. Given the annotation coverage, a 3 is appropriate – it adds some behavioral context without being exhaustive.

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

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

A single, well-structured sentence that front-loads the action and scope. No filler or redundancy – 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?

The tool is a simple read-only list operation with only two parameters, both fully documented in the schema. The description explains the purpose and ordering. Although there is no output schema and the return format is unspecified, that is typical for list operations and not a critical gap given the tool's simplicity.

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

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

Schema description coverage is 100% – both 'limit' and 'collectiveId' have clear descriptions. The tool description does not add anything about parameter semantics beyond what the schema already provides, 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 states a clear verb ('List'), a specific resource ('recently-modified pages for a Collective'), and an ordering constraint ('ordered by last edit time'). This distinguishes it from the sibling 'list_pages' by scope (recent vs all) without needing to open 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?

There is no guidance on when to use this tool versus alternatives like 'list_pages' or 'search'. The context implies it is for recent pages, but no explicit when/when-not or alternative routing is provided, leaving the agent to infer the selection criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable detail about the returned fields (scope, token, edit permission, password flag) and explicitly states that passwords are never returned, which is important security context not captured 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?

The description is two sentences with no redundant information. The core purpose is front-loaded, and the details about the returned fields are presented compactly without fluff.

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 description explains what the tool returns (each entry's scope, token, edit permission, password flag) and highlights the security aspect of not returning passwords. For a simple list operation with one parameter, this is sufficient for an agent to call it correctly, though pagination or result limits are not mentioned.

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 input schema has a single required parameter, collectiveId (integer), with no description in the schema and 0% coverage in the tool description. The description does not explain the parameter, relying on its name to convey meaning. Given the low schema coverage, the description should have compensated but did not.

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

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

The description states a specific action ('List all public share links') on a specific resource ('Collective') and distinguishes between collective-level and per-page shares. It clearly separates this from sibling tools like create_collective_share, update_share, and delete_share, which handle mutations.

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 a clear context (listing shares) but does not explicitly mention when to use this instead of other share-related tools. It doesn't state any exclusions or alternatives, leaving the agent to infer that this is the read operation among the share tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds no conflicting information and is consistent with these annotations. Since it is a simple read-only listing operation, no extra side effects need disclosure, so the existing annotations suffice.

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 unnecessary words. It directly states the action and target, adhering to best practices for tool descriptions.

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

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

There is no output schema, and the description does not specify the return format (e.g., array of tag objects, fields included, ordering). It only says 'List all tags', leaving the response structure undefined. This is a gap because without an output schema, the agent may not know what to expect from the 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?

The only parameter 'collectiveId' is an integer with no schema description. The tool description compensates by indicating it refers to a Collective, giving the parameter context. While minimal, this is enough to infer that the ID identifies the collective whose tags are to be listed.

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 tool's function: listing all tags for a Collective. It uses a specific verb and resource, and the tool name ('list_tags') aligns perfectly. It is easily distinguishable from sibling tools like create_tag, update_tag, and delete_tag.

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 one needs to retrieve tags for a collective, but it does not explicitly mention alternatives or conditions (e.g., 'use instead of list_collectives when you need tag data'). While the purpose is clear, explicit guidance on when to choose this over related tools is absent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no new behavioral details beyond the fact that it lists templates, which is implied. It does not mention return format, pagination, or other runtime behavior. With annotations present, this is acceptable but adds minimal value beyond the annotations.

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

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

The description is a single, front-loaded sentence with no fluff. Every word contributes to the purpose, and it is efficiently structured.

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

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

For a simple list operation with one parameter and no output schema, the description provides sufficient context: it lists templates for a collective, and annotations cover safety. The only gap is the lack of explicit parameter explanation, but that is minor given the tool's simplicity. The description is adequate for an agent to correctly invoke the 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 0% and the description does not explain the parameter. The only parameter, collectiveId, is named clearly, but the description does not explicitly state that this ID identifies the collective whose templates are to be listed. Given the low schema coverage, the description should compensate by explaining the parameter, but it does not.

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

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

The description states a specific verb and resource: 'List page templates defined for a Collective.' This clearly distinguishes it from sibling tools like list_pages (which lists pages) and get_template (which retrieves a single template). The agent can immediately understand what this tool does without ambiguity.

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—listing templates for a specific collective—but does not explicitly state when to use this tool over alternatives. For example, it doesn't mention that get_template is for a single template or that list_pages is for pages. The context is clear, but there are no exclusions or explicit guidance on choosing between related list/retrieve tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations by clarifying the soft-deleted state and noting that items can be restored or permanently deleted. It does not contradict any annotations and enhances understanding of the operation's scope.

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

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

The description is two sentences with no fluff. The core purpose is front-loaded, and the second sentence adds relevant context about follow-up actions. Every word earns its place, making it concise and well-structured.

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

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

With no parameters and no output schema, the description is complete for a simple list tool. It states what is listed (soft-deleted collectives) and the relevant next steps (restore or permanent delete). No critical information is missing for an agent to correctly decide when to invoke it.

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

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

There are zero parameters, so the description has no parameter details to provide. Per the baseline for 0-parameter tools, this scores a 4. The description adds nothing about parameters because there are none, which 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 clearly states the verb 'List' and the resource 'Collectives' with a specific scope: 'soft-deleted'. It distinguishes itself from sibling list_collectives by explicitly narrowing to trashed items. It also adds the note about restoration/deletion, which clarifies the purpose further.

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: listing soft-deleted collectives is a precursor to restoring or permanently deleting them. While it does not explicitly name alternative tools or provide exclusions, the context of 'These can be restored or permanently deleted' signals when this tool is appropriate, and the sibling list_collectives is implicitly the non-trashed counterpart.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. The added note 'These can be restored or permanently purged' is about the items, not the tool's behavior, providing minimal additional behavioral disclosure. Given the annotations cover the essential traits, a score of 3 is appropriate for the limited extra context.

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 redundancy, and the primary purpose is front-loaded. Every phrase contributes meaning—listing, scope, and the associated actions—making it concise and structured well for quick comprehension.

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

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

For a read-only list operation with a single well-documented parameter and no output schema, the description provides all necessary context: what it lists, the scope, and what can be done with the results. No critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the only parameter collectiveId is already documented with 'Collective id from list_collectives.' The tool description adds no new parameter-specific meaning, so it does not improve on the schema. Baseline 3 is correct when the schema fully explains parameters.

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

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

The description clearly states the tool's action (list) and resource (pages in the trash for a Collective), distinguishing it from list_pages which likely returns non-trashed pages. The phrase 'for a Collective' scopes it precisely, and the mention of restore/purge options adds context about the items without ambiguity.

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 explains the context of use (listing trashed pages) and hints at downstream actions (restore or permanently purge), which guides an agent to when this tool is relevant. However, it does not explicitly exclude alternatives like list_trashed_collectives or state when not to use it, though the purpose is clear enough for an agent to infer.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the leaf promotion behavior, which is a significant side effect not covered by annotations. This extra context is valuable and goes beyond what annotations provide, though it does not describe other potential effects like child reordering or permissions.

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

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

The description is two concise sentences, front-loaded with the main purpose and immediately followed by a key behavioral detail. There is no fluff or redundant 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 mutation with no output schema, the description covers the core behavior and an edge case, but it omits return values, error scenarios, and potential side effects on children or ordering. Given the tool's simplicity, this is acceptable but not fully complete.

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

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

Schema description coverage is only 25% (only 'index' has a description). The description does not elaborate on pageId, collectiveId, or newParentPageId, nor does it clarify their semantics beyond their names. With low schema coverage, the description should compensate, but it does not. The parameter names are self-explanatory to some extent, but no additional meaning is added.

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

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

The description clearly states the verb (move), the resource (a page), and the scope (within the same collective). It also includes a specific behavioral nuance (leaf promotion), which distinguishes it from the sibling tool move_page_to_collective that moves across collectives.

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

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

The phrase 'within the same collective' implies the tool is not for cross-collective moves, but it does not explicitly name the alternative or provide an exclusion. The context is clear enough to infer, but there is no direct guidance on when to prefer this tool over move_page_to_collective or set_subpage_order.

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

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

Annotations already indicate destructive/non-read-only behavior. Description adds useful behavioral details: subpages and attachments are included, page id changes, and the returned page should be used for follow-ups.

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 concise sentences. The main action and key distinction are front-loaded, with copy behavior and alternatives stated 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?

Description covers the key side effects, copy/move behavior, and guidance on using the return value. It could mention permissions or error cases, but given the annotations and schema, it is sufficiently complete.

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

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

Input schema has 100% description coverage and each parameter already has a clear description. The tool description does not add much beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb ('Move or copy') and resource ('page ... into a different Collective'). Explicitly distinguishes it from move_page/copy_page, which are for reorganising within one Collective.

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?

Explains when to use this tool vs alternatives: 'For reorganising within one Collective use move_page or copy_page instead.' Also clarifies copy behavior with 'copy: true'.

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?

The description adds the critical irreversibility warning ('THIS IS IRREVERSIBLE') and the precondition (must be in trash), which go beyond the destructiveHint annotation. It also clarifies the deleteTeam parameter's effect on the underlying Team. This provides useful behavioral context without contradicting the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true).

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 waste. The purpose is front-loaded, followed by the irreversibility warning and the prerequisite, then the optional parameter behavior. Every sentence earns its place and no redundant details are included.

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 simplicity (2 parameters, no output schema) and the destructive nature, the description covers the essential aspects: what it does, its irreversibility, the required precondition, and the optional flag. It doesn't mention success responses or error cases, but those are not critical for calling this tool correctly. The description is sufficiently complete for an agent to use it properly.

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 (id from list_trashed_collectives, deleteTeam default false). The description adds a reminder that the Collective must already be in trash and that deleteTeam=true removes the Team, but this largely reinforces the schema. The added value is marginal, so baseline 3 is appropriate.

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

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

The description clearly states the action: permanently delete a Collective from the trash. It distinguishes this from siblings like delete_collective (soft delete) and restore_trashed_collective by emphasizing the irreversibility and the requirement that the item already be in trash. The verb, resource, and scope are specific.

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 the prerequisite: 'The Collective must already be in the trash (use delete_collective first).' This gives clear context on when to use the tool and points to the correct preceding action. It also explains the optional deleteTeam behavior. It doesn't explicitly mention alternatives like restore_trashed_collective, but the condition is clear enough to route an agent correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context by stating the tool reports the count of visible collectives, which is beyond annotation scope. It is consistent and provides a concrete behavioral detail.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the purpose and the added output detail, making it 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?

With no parameters, no output schema, and rich annotations covering safety, the description is fully adequate. It tells the agent exactly what the tool does and what it reports, leaving no gaps for successful 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?

The tool has zero parameters, so the description does not need to explain parameter semantics. The baseline is 4 for zero-param tools, and the description appropriately focuses on the tool's function rather than input handling, satisfying the expectation.

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 a specific action ('Verify connectivity') and a distinct resource ('configured Nextcloud instance'), plus the additional report of visible collectives. This distinguishes it from all sibling tools, which manage collectives or pages, making it 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?

The description implies its use as a connectivity check but does not explicitly state when to use it versus alternatives or provide exclusion criteria. Given it is a unique health-check tool with no similar siblings, the implied usage is acceptable but could be enhanced with guidance like 'Use before other operations to verify connectivity.'

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?

While annotations already indicate destructiveHint=true, the description adds crucial context about irreversibility and the precondition of being trashed. This goes beyond the annotations and fully informs the agent of the 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 extremely concise, using a single sentence plus a warning. Every word adds value, with no fluff or redundancy.

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

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

The description covers the essential context: what it does, the irreversibility, and the prerequisite. It lacks parameter details but for a simple two-integer operation, this is not a significant gap. No output schema is present, so no return value clarification is needed.

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 input schema has no descriptions and the tool description does not explain the parameters (collectiveId, pageId). With 0% schema description coverage, the description fails to compensate by clarifying parameter meaning or expected 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 clearly states the verb 'permanently delete' and the specific resource 'trashed page'. It distinguishes from siblings like delete_page (which moves to trash) and restore_page, making the purpose 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?

The description explicitly states the prerequisite: the page must already be in the trash, and instructs to use delete_page first. This clearly tells when to use this tool and differentiates it from alternatives.

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

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

Annotations already convey that this is a mutating (readOnlyHint=false) but non-destructive operation. The description adds value by disclosing that existing references are NOT rewritten and that the tool returns a relativePath, which is behavioral context beyond what annotations provide. No contradictions with annotations.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the critical side-effect note is concise and directly actionable. 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 tool with no output schema, the description covers the essential behavioral nuance (references not updated) and the follow-up action (use relativePath). It could mention uniqueness of newName or existence checks, but these are not critical for a well-functioning agent given the sibling tools and schema context.

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

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

Schema description coverage is only 50% (newName and filename have descriptions, pageId and collectiveId do not). The description does not compensate for the undocumented parameters; it mentions relativePath which is a return value, not a parameter. An agent may be unsure about the semantics of pageId and collectiveId beyond their obvious roles.

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 ('Rename an attachment on a page') and differentiates from siblings like delete_attachment and get_attachment by the specific verb and resource. It also adds a critical detail about side effects, making the purpose 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?

The description gives clear context for use: it renames an attachment and explicitly instructs the agent to update references manually using the returned relativePath. This provides strong guidance on what to do after calling, though it does not explicitly mention alternatives or when not to use it.

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

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

Beyond the annotations, the description provides no information about side effects, permissions, title uniqueness constraints, or any other behavioral details. It only restates the core action.

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 extremely concise and contains no irrelevant information. It is a single clear sentence with no wasted words.

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

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

For a simple rename action, the description is mostly adequate, but it omits details such as whether the new title must be unique, any error conditions, or what happens to the page's content. The 'within its current parent' clarification helps, but more context would improve completeness.

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 no per-parameter descriptions, and the tool description does not elaborate on collectiveId, pageId, or newTitle. While pageId and newTitle are somewhat inferable, collectiveId is not explained.

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 tool renames a page, and the phrase 'within its current parent' distinguishes it from move-related operations. It is specific and 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?

The description does not explain when to use rename_page versus alternatives like update_page or move_page. It lacks explicit guidance on selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by explaining the trash mechanics (no longer in list_attachments) and the id source, which is beyond the annotations. No contradiction found.

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

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

Two sentences, no fluff. The primary purpose is stated first, followed by a necessary clarification about id sourcing. 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 simple restore tool with three required params and no output schema, the description covers the critical nuance (id not name) and the prerequisite (delete_attachment). It omits explicit return value and error handling, but given the annotations covering idempotency and non-destructiveness, the description is adequately complete.

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

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

Schema coverage is only 33% (attachmentId has a description). The description adds meaning for attachmentId by explaining it is numeric and returned by delete_attachment, but it does not clarify collectiveId or pageId, leaving those to be inferred from naming and sibling context. It partially compensates for the low coverage but not fully.

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 precise verb and resource: 'Restore a deleted attachment from the page's attachment trash.' It clearly distinguishes from restore_page and restore_trashed_collective by specifying 'attachment.' The reference to list_attachments and delete_attachment further anchors its scope.

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 implicitly defines when to use: when a deleted attachment needs restoring, and it explains that a trashed attachment has no name, so the id from delete_attachment is required. It does not explicitly list exclusions or name alternative tools, but the context is clear enough for an agent to select this over related restore tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the mutation and safety profile are covered. The description adds the useful behavioral detail that the page returns to its 'original location,' which is a small increment beyond annotations. No contradiction with annotations.

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

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

A single, front-loaded sentence with zero waste. The core action and outcome are stated immediately with no filler.

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

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

For a simple two-integer-parameter restore operation with annotations covering safety and idempotency, the description captures the essential behavior (un-trash and restore location). The only gap is parameter detail, which is minor for such a simple tool. No output schema is needed for a void-style operation.

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

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

Schema description coverage is 0%, so the description must compensate, but it provides no explanation of pageId or collectiveId beyond the schema's bare names. The identifiers are self-descriptive, yet the description entirely omits parameter semantics, including which collective scope pageId belongs to.

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 ('Restore a trashed page') and adds a meaningful qualifier ('back to its original location') that distinguishes it from restore_page_version and restore_trashed_collective. However, it does not explicitly name those siblings, so differentiation is implicit rather than explicit.

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 (undoing a trash action on a page) is clearly implied by 'Restore a trashed page.' No explicit when-not conditions or alternative tools are named, leaving the agent to infer the boundary against restore_page_version (versions) and restore_trashed_collective (collectives).

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

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

Annotations already declare destructiveHint and readOnlyHint false. The description adds specific behavior about preserving the current version as a new entry, providing transparency beyond the annotations.

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

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

The description is a single concise sentence with no redundant information. It clearly conveys the operation and its effect in a well-structured manner.

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 tool is simple, and the description covers the core behavior. It does not explicitly state that list_page_versions must be called first to obtain a valid versionId, but that is implied by the parameter description, so the context is mostly complete.

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

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

Schema description coverage is low (only versionId described, 33%). The description does not compensate by explaining collectiveId or pageId, though they are standard IDs. This leaves ambiguity for an agent.

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: restoring a specific historical version of a page. It also explains the effect (current content replaced, current version preserved as new entry), which distinguishes it from restore_page (restoring a trashed page) and list_page_versions.

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 the use case (reverting to a past version) and the parameter description for versionId notes it comes from list_page_versions, giving context. However, it does not explicitly contrast with sibling tools like restore_page or mention when not to use it.

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

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

Annotations already cover idempotent and non-destructive behavior. The description adds the 'soft-deleted' detail and 'trash' context, which clarifies the state of the target, but does not disclose additional side effects or permission requirements beyond what annotations imply.

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, clear sentence with the verb first, providing maximum information in minimal space. No unnecessary wording.

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 tool is simple with one parameter; the description fully covers what it does and the parameter origin. No output schema is needed for such an operation, and no critical edge cases are omitted given the idempotent and non-destructive 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?

The only parameter (id) has a descriptive explanation 'Collective id from list_trashed_collectives' that exceeds the raw integer type by indicating the proper source and context for obtaining the value. Schema coverage is 100%.

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 (restore), the target (Collective), and the context (soft-deleted/trash). It is distinct from sibling tools like permanently_delete_collective or delete_collective.

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 implicitly indicates usage for restoring previously soft-deleted items, and the parameter description 'Collective id from list_trashed_collectives' provides a clear source for the required id. It does not explicitly contrast with alternatives, but the context is sufficient for an agent to infer when to use it.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that it uses the Nextcloud unified search provider but does not detail any additional side effects or limitations, which is acceptable given the annotations.

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

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

The description is two concise sentences. The main purpose is front-loaded, and the alternative tool is mentioned 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?

For a simple search tool with no output schema, the description sufficiently covers the scope, accessibility, and alternative usage. It does not explain result formatting, 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?

Parameter descriptions in the schema fully cover the meaning of query and limit (default 25). The description does not add extra context beyond the schema, but since coverage is 100%, the baseline score 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?

The description clearly states the tool performs full-text search across all accessible Collectives pages and explicitly distinguishes it from the more targeted search_in_collective tool.

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 provides explicit guidance on when to use this tool versus the alternative: 'For searching within a specific Collective, use search_in_collective instead.' This leaves no ambiguity about the intended use case.

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?

The description mentions returning 'matching page metadata' but adds little beyond the readOnly and idempotent annotations. It does not elaborate on side effects (though none are expected), pagination, or error behavior. Since annotations already cover the read-only nature, the description provides minimal additional behavioral context.

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 concise and well-structured: two sentences that state the action, scope, and return type without redundancy. It is appropriately sized for the tool's simplicity and avoids unnecessary detail.

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

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

While the description is clear, it lacks contextual details such as what 'content' refers to (e.g., page body, title, tags), what 'metadata' includes, or how results are ordered. Given the absence of an output schema, the description could be more complete to fully inform the agent about the expected 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 covers 2 parameters but only 'query' has a description ('Search text.'). 'collectiveId' is not described, and the tool description does not clarify its meaning or expected format. With 50% schema coverage and no compensation in the description, parameter semantics are weak.

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 tool's function: searching for pages by content within a specific Collective and returning matching page metadata. The verb 'search' and the resource 'pages' are explicit, and the scope is narrowed to a specific Collective, distinguishing it from the sibling 'search' tool which likely operates globally.

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 searching within a specific Collective, but it does not explicitly contrast this with the sibling 'search' tool or other alternatives. It lacks guidance on when to choose this tool over list_pages or the general search, leaving the agent to infer the appropriate context.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavior of clearing the emoji with an empty string, which is not captured in annotations. However, it does not describe overwriting behavior or any side effects, so the added value is moderate.

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 exactly two sentences with no redundant words. It front-loads the primary purpose and adds the clearing nuance in a concise 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 mutation tool with no output schema, the description is incomplete because it does not explain what pageId and collectiveId refer to. It also omits any prerequisites or consequences (e.g., overwriting an existing emoji). Given the low schema coverage, an agent is left without enough information to correctly construct a 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 description coverage is only 33% (only the emoji parameter has a description). The description does not compensate for the missing descriptions of pageId and collectiveId. It repeats the emoji clearing behavior already present in the schema, but provides no additional meaning for the other two required parameters.

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

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

The description clearly states the action: 'Set the single-emoji icon on a page.' This uses a specific verb and resource, and explicitly mentions 'page' to distinguish from similar tools like set_template_emoji. The additional instruction about passing an empty string to clear further clarifies the behavior.

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 clear context that this tool is for setting an emoji on a page, but it does not mention any alternatives or when not to use it. It fails to differentiate from the closely related set_template_emoji, so an agent has no guidance on choosing between them beyond the resource name.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the scope (Collective-wide vs per-user), which goes beyond the annotations. It does not describe side effects, but given the idempotent and non-destructive hints, this is adequate.

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 action and key distinguishing detail are front-loaded, making it efficient for an agent to parse.

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 toggle tool with three parameters and no output schema, the description is nearly complete. It explains the scope and the action. The only minor gap is that it doesn't explicitly state the expected behavior of the toggle beyond the boolean, but that is covered in the schema's fullWidth description. The annotations cover safety, so overall it is 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 coverage is only 33% (only fullWidth has a description). The description does not explicitly describe parameters, but it does explain the Collective-wide nature, which implies the necessity of collectiveId and pageId. This partially compensates for the low coverage, but it does not fully clarify the semantics of each parameter. The parameter names are self-explanatory, so a 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 ('Toggle') and resource ('a page's full-width layout'), and adds a distinguishing detail that it is a Collective-wide property, not per-user. This differentiates it from per-user settings tools like set_user_settings. It clearly conveys the tool's purpose.

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 clarifies that this is a Collective-wide display property, not a per-user preference, which hints at when to use it versus per-user settings tools. However, it does not name specific alternative tools or explicitly state when not to use it, so it falls short of full guidance.

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

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

Annotations already indicate the tool is idempotent, non-destructive, and not read-only. The description adds valuable context about scope ('applies to every member') and clarifies that it affects all members, which is beyond annotation coverage. No contradictions with annotations.

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

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

The description is two sentences with no fluff. The core purpose is front-loaded, and the differentiation from set_user_settings is placed at the end for clarity. 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 setter with two parameters and no output schema, the description is sufficient. It explains what the tool does, its scope, and distinguishes from related tools. It doesn't mention prerequisites or error cases, but these are not critical for this simple operation.

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

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

Schema coverage is 50%: only 'mode' has a description, while 'collectiveId' lacks one. The description adds minimal parameter-specific meaning—it repeats the view/edit enum but does not clarify the collectiveId semantics or any parameter formatting. It fails to compensate for the missing schema description.

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 ('Set the default page mode'), the resource ('a Collective'), and the specific behavior ('whether pages open in view or edit mode'). It also distinguishes from a sibling tool (set_user_settings) by noting the scope difference, making the purpose 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?

The description explicitly contrasts with set_user_settings, indicating when to use this tool (collective-wide) versus the alternative (per-user). This gives clear usage guidance and differentiation among siblings.

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?

The description notes that tags must already exist and implies replacement, but it does not explicitly say that existing tags not in the list will be removed. The destructiveHint annotation covers this, but the description itself is somewhat implicit.

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. Every word adds 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 mutation tool, it covers the required action and a prerequisite (tags exist). It does not specify return values, but with no output schema that is acceptable. It could mention error behavior, but that is not essential.

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?

Only tagIds has an explicit description; collectiveId and pageId are not described in the schema. However, the tool name and context 'Tags must already exist in the Collective' make their roles inferable, leaving partial ambiguity.

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 ('Replace the tags on a page') and adds the requirement that tags must already exist, with a pointer to list_tags. This distinguishes it from other page-related 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?

It provides a practical usage hint (use list_tags to look up tags) but does not explicitly contrast with alternatives. However, since there is no direct alternative for setting tags, the hint suffices.

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?

The description adds substantial context beyond annotations, including validation rules (duplicates rejected), the effect of an empty array (fallback to Collective sort), and a conditionality note (only for users with 'byOrder' page order). These details are not fully captured by the annotations alone.

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 compact and well-structured, consisting of three sentences that each convey a distinct piece of essential information without redundancy. It is easy to parse and directly relevant to invoking the tool.

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

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

Given the simple parameter set (three integers/array) and no output schema, the description covers all necessary operational aspects: the action, constraints, and side effects. It provides sufficient context for an agent to use the tool correctly without requiring additional details.

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

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

The description clarifies the semantics of subpageOrder by specifying that ids must be direct children and that an empty array resets to default. However, collectiveId is not explicitly explained, despite being required; the schema only provides descriptions for two of three parameters, so the tool description adds value but leaves collectiveId implicit.

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 specific verb 'Set' and precisely identifies the resource as 'explicit left-to-right ordering of a page's immediate child pages'. It clearly differentiates from sibling tools like move_page or update_page by focusing solely on ordering subpages.

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 when to use the tool (to set explicit ordering) and provides key behavioral constraints: every id must be a direct child, duplicates are rejected, empty array clears manual order, and the effect is conditional on user's 'byOrder' setting. This gives clear guidance without ambiguity.

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

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

Annotations already indicate idempotent and non-destructive behavior; the description adds no hidden side effects, failure modes, or additional behavioral context beyond the basic mutation.

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

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

The description is a single clear sentence with no superfluous information, making it easy to parse and action.

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

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

For a simple idempotent mutation with no output schema, the description is sufficiently complete, especially with the schema clarifying that an empty string clears the emoji.

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 low (only emoji is described), and the description does not clarify collectiveId or templateId. Since coverage is below 50%, the description should compensate but does not.

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

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

The description clearly states a specific verb ('Set or clear') and resource ('emoji icon on a page template'), distinguishing it from the sibling set_page_emoji which targets pages rather than templates.

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 resource type 'page template' gives clear context for when to use this tool versus page-oriented alternatives, though it does not explicitly name alternatives 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?

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: changes are scoped to the authenticated user, do not affect other members, and omitted fields are preserved.

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 concise and front-loaded, with three focused sentences. No redundant wording or unnecessary technical detail.

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

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

Given the simple parameter set and no output schema, the description provides enough context to call the tool correctly, including the update semantics and the relationship to the sibling set_page_mode 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 descriptions cover 75% of parameters, including booleans and the pageOrder enum. The required collectiveId lacks a direct schema description, but the tool description clarifies the target is 'one Collective', partially compensating for that gap.

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

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

States a specific verb ('Update') and a clear object ('authenticated user's own display preferences for one Collective'), and enumerates the exact fields. It also distinguishes this tool from set_page_mode by noting the collective-wide alternative.

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 explains when to use it (per-user display preferences) and when not to (use set_page_mode for Collective-wide settings). It also tells callers to provide at least one field and that omitted fields are left unchanged.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds specific behavioral detail: it updates the modification timestamp and last editor, and explicitly states it does not change content. This goes beyond the annotations and helps the agent understand the exact effect, though it does not mention side effects like permissions or rate limits.

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 extraneous words. The core action is stated first, followed by the use case. Every sentence contributes value, and the structure is efficient.

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

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

For a simple mutation tool with two integer parameters, no output schema, and clear annotations, the description covers the essential aspects: what it does, what it doesn't do, and when to use it. It does not mention prerequisites or error conditions, but these are minor for this simple operation. Overall, the description is sufficiently complete for the tool's complexity.

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 provides only parameter names (pageId, collectiveId) with no descriptions, and schema description coverage is 0%. The tool description does not explain these parameters at all, leaving the agent to infer meaning from the names alone. This is a significant gap, as the description does not compensate for the lack of schema documentation.

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 tool's action ('Bump a page's modification timestamp and record the authenticated user as its last editor'), the resource (a page), and explicitly notes it does not change content. This distinguishes it from update_page and other page operations. The use case 'marking a page as reviewed' further clarifies intent.

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 a clear usage context ('Useful for marking a page as reviewed') and implies when to use it (when you want to update metadata without altering content). It does not explicitly name alternative tools or exclusion criteria, but the phrasing strongly suggests when this is appropriate.

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?

The annotations provide useful behavioral hints: readOnlyHint=false indicates mutation, idempotentHint=true suggests repeated calls are safe, and destructiveHint=false implies non-destructive removal. The description itself does not mention side effects, but the annotations compensate.

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 unnecessary words. It is properly structured and immediately understandable.

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

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

There is no output schema and no parameter documentation, leaving some uncertainty about return values and error behavior. However, the action is simple, and the description covers the core semantics adequately.

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?

Parameter names (collectiveId, pageId) are self-explanatory, but the schema provides no descriptions or contextual details. Coverage is 0%, yet the names are clear enough for basic usage.

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 ('Remove') and the target ('page from the authenticated user's favorites'), making the tool's purpose unambiguous. It is naturally distinguished from the sibling favorite_page tool.

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 does not explicitly state when to use this tool versus alternatives, but the action is so specific that no alternative is needed. It is implied to be the inverse of favorite_page, though not stated.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds the specific limitation about renaming, which is extra context beyond the annotations. It does not mention any other side effects, but for a simple update operation this is adequate.

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 concise, with no redundant information. It uses a clear imperative structure and includes a helpful caveat about renaming in a single sentence.

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 description covers the core functionality and the unsupported rename case. Since there is no output schema, return values are not required. It is sufficiently complete for an update operation on a simple resource.

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 descriptions cover id and emoji but not editPermissionLevel or sharePermissionLevel (50% coverage). The description mentions they are for adjusting permission levels but provides no details on valid values or meaning. This leaves some ambiguity for those parameters.

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

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

The description clearly states the tool's action: changing a Collective's emoji or adjusting edit/share permission levels. It also explicitly notes that renaming is not supported, which distinguishes it from potential rename operations and provides precise scope.

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 instructs the user to provide the id and any fields to change, which is a clear usage pattern. The note about renaming not being supported serves as a negative guideline, but it does not explicitly mention when to prefer this over other update tools (though context with sibling tools makes this implicit).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's mention of replace/append/prepend adds the mode behavior, which is useful. However, it doesn't disclose side effects like versioning, that replace mode overwrites the entire body, or that the page must exist. It adds some value beyond annotations but not much.

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 that front-loads the core action ('Replace, append to, or prepend to a page's markdown body') and then notes the mode default. There is no wasted text or unnecessary elaboration.

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 tool has no output schema, and the description does not explain return values, error conditions, or that the page must exist. It also omits that replace mode fully overwrites the body, which is critical for a destructive operation. For a mutation tool with annotations carrying the destructive hint, more contextual detail is expected.

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 0%, and the description only adds meaning to the mode parameter (defaulting to 'replace'). It does not explain body, pageId, or collectiveId beyond what the schema names imply. With low coverage, the description should compensate but fails to clarify body format or required fields, so it only marginally helps.

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 action — replace, append, or prepend — on a specific resource (a page's markdown body). It distinguishes from sibling tools like rename_page, move_page, or set_page_mode by focusing on content modification, so an agent can select it without confusion.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It doesn't say 'use this to edit page content' or compare with other page-modifying tools. The only hint is the mode default, which is a behavioral detail, not usage selection guidance.

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

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

Annotations only provide hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description carries the burden of behavioral disclosure. It does so by revealing that editable is silently applied if omitted, and that passing an empty password removes an existing one. This adds meaningful context beyond the annotations.

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

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

The description is three sentences long, dense with actionable information, and front-loads the critical editable warning. It could be slightly more structured, but each sentence earns its place and the key warning is placed first.

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

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

For an update tool with no output schema, the description covers the essential parameters, their behavior, and edge cases. It doesn't mention return values, but that's typically not critical for an update operation. The 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 80% (4 of 5 params described), so baseline is 3. The description goes further by explaining the semantic nuance of editable (required, always applied), the conditional use of pageId, and the password removal convention. This enriches the meaning beyond the schema's brief descriptions.

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 'Update an existing share link' with a specific verb and resource, and it differentiates from create/delete share tools by focusing on existing links. This unambiguously tells an agent what the tool does and how it differs from 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?

The description provides explicit when-to-use guidance: it explains that editable is always applied and must be set explicitly, how to handle page vs Collective-wide shares via pageId, and how to remove a password. While it doesn't name alternatives like create_collective_share, the context makes the intended usage 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?

Beyond the annotations, the description reveals that both name and color are always applied (no partial updates) and that omitting a field is unsupported. These are crucial behavioral details not captured by metadata.

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, direct and without unnecessary words. It efficiently communicates the full-update requirement and the prerequisite read step.

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 description covers the essential usage caveats and prerequisite. It does not mention consequences on associated data, but for a simple tag update this is likely sufficient, especially with no output schema defined.

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 documents color and tagId, and the description clarifies that name and color are the updated fields. However, collectiveId is not explained in either the schema or description, leaving some ambiguity, though it is likely inferable from context.

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 ('Update a tag') and identifies the resource. It also clarifies the full-update behavior, making the tool's purpose 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?

It provides explicit guidance: pass existing values for unchanged fields and read current values with list_tags first. This tells the agent exactly how to use the tool safely.

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?

The description indicates a rename operation, which implies only the title changes and content is unaffected. However, it does not disclose any side effects, permissions needed, or idempotency details beyond what the annotations already indicate (readOnly=false, destructive=false, idempotent=true).

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 clear sentence with no redundant words or extraneous detail. It is maximally concise while still conveying the core operation.

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

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

For a simple rename operation, the description is adequate. However, it lacks context about the template lifecycle, relationship to content updates, or how it differs from other template-related tools, which would help an agent choose confidently among sibling operations.

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 parameter names (collectiveId, templateId, title) are self-explanatory, but the description adds no additional meaning or examples. It does not clarify relationships or constraints, leaving the schema to carry all parameter understanding.

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 (rename) and the target resource (page template). It is more specific than the generic tool name 'update_template', though it does not elaborate on scope or context.

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 like 'update_template_content', 'create_template', or 'delete_template'. It does not mention that renaming is different from editing content or that other operations exist.

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?

The description explicitly discloses destructive behavior (clearing the template with an empty body) and concurrency protection for append/prepend, aligning with the destructiveHint=true and readOnlyHint=false annotations.

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

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

The description is concise, using two sentences to convey the primary purpose and important behavioral nuances without unnecessary detail.

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

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

The description adequately covers the tool's side effects and failure modes, which is sufficient for an update operation with no output schema, though it could mention the absence of a return value or error conditions.

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 describes only 3 of 4 parameters; the description adds context for body (clearing) and mode (concurrency protection) but does not mention collectiveId, leaving a gap in understanding its purpose.

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 specific action (writing the markdown body of a page template) and its role in create_page, distinguishing it from the related update_template tool that handles other template properties.

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 explains when to use the tool (to set template content), describes edge cases (empty body clears the template) and concurrency behavior for append/prepend, though it does not explicitly mention when not to use it or contrast with update_template.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds useful context about directory creation and the return format (a ready-to-paste markdown path), which goes beyond the annotations. It does not mention potential overwrite or other destructive side effects that might align with destructiveHint, but given the annotations, the description need not repeat that. It adds value without contradicting.

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

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

Two sentences with zero redundancy. The main action is stated first, then the directory side-effect, then the return format with a concrete example. Every sentence carries information essential to using the tool correctly, and the structure is 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 6-parameter mutation tool with no output schema, the description is quite complete: it explains the core action, a side effect (directory creation), the encoding default behavior, and the exact return value format, which is crucial for the agent to know how to use the result. It lacks explicit error handling or size limits, but those are not typically required. The description, combined with the schema and annotations, covers what an agent needs to invoke it correctly.

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

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

The input schema already describes content, encoding, filename, and contentType with useful defaults and inference rules. The description adds nothing new about these parameters beyond what the schema states, but it also does not compensate for the undocumented pageId and collectiveId parameters (which lack schema descriptions). With 67% schema coverage, the description falls short of explaining the required IDs, though the markdown example hints at pageId's role. It provides marginal added value but does not fill all 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 opens with a specific verb and resource: 'Upload an attachment to a page.' It also explains the side-effect of directory creation and the return format (percent-encoded relativePath), which clearly distinguishes it from sibling operations like list_attachments, delete_attachment, or get_attachment. An agent can immediately recognize this is the upload action among a set of attachment-related 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 makes the tool's role self-evident among siblings; it is the only upload operation, while others handle listing, deletion, retrieval, renaming, and restoration. However, it does not explicitly state when to use it versus alternatives (e.g., 'use this to add a new attachment, not to modify existing ones'). The distinction is implicit but strong enough for an agent to infer the correct selection.

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