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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description reinforces and enriches this by explaining the idempotency in concrete terms and disclosing a real side effect — a previously declined/left group share is restored before acceptance because Nextcloud otherwise refuses. It does not cover authorization/permission requirements, so not a 5.

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

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

Purpose and idempotency behavior are front-loaded in the first two paragraphs, with Args/Returns kept tight. The docstring-style formatting adds a little overhead but every sentence contributes information; nothing is padding.

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 two-parameter mutation with an output schema and full annotation coverage, the description supplies everything an agent needs: what it does, how it differs from decline_share, where the id comes from, the federated distinction, and the idempotency guarantee. Returns are correctly left to the output schema.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: share_id is defined as the pending share's id from list_pending_shares along with the reason it may be a string (long federated ids exceed JSON number range), and federated is defined with its true/false condition and the separate numbering caveat.

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 first sentence gives a specific verb and resource ('Accept a share ... adding it to their files') and immediately scopes it to the current user. It is clearly distinguishable from sibling tools like decline_share, list_pending_shares, and create_share without opening any 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?

It names the upstream tool (list_pending_shares) as the source of the share_id and explains when to set federated=true, including the non-obvious fact that local and federated shares are numbered separately. It stops short of stating explicit exclusions or prerequisites (e.g. permission needed to accept), so it falls just short of a 5.

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

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

Beyond the annotations, the description discloses the permission requirement, the side effect of adding a member, the return value shape, and the conditional behavior where status becomes 'Invited' when the circle has the INVITE config flag. This gives the agent important behavioral expectations that annotations alone do not provide.

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 front-loaded with the core purpose and then organized into concise Args and Returns sections. Every sentence adds necessary information; there is no filler or redundant expansion beyond the schema.

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 operation, permission, parameters, and return behavior comprehensively. The only notable gap is that member_type includes 'contact' but the user_id interpretation for that type is not explained, unlike user, group, mail, and circle.

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 provides no parameter descriptions (0% coverage), so the description carries full responsibility. It explains circle_id, how user_id is interpreted for each member_type value, the default of 'user', and the full enum of member_type options. This is exemplary 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 the action: adding a user, group, email, or nested circle as a member, which is distinct from sibling operations like remove_circle_member, list_circle_members, and update_circle_member_level. It also names the permission requirement, making the tool's role 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 a useful prerequisite ('Requires moderator+') but does not explicitly explain when to choose this tool over alternatives such as join_circle (self-joining) or update_circle_member_level (changing an existing member's role). The usage context is implied rather than 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?

Description discloses that a new comment is created, that @username mentions are supported, that the message is length-capped at 1000 characters, and that a confirmation with the new comment ID is returned. Annotations only indicate it is not read-only, idempotent, or destructive, so this adds genuinely useful 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?

Tightly structured with intro, constraint notes, Args, and Returns. The only minor redundancy is restating @username and max length in both the intro and the message arg, but it is small and keeps each section self-contained.

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 two-parameter mutation with an output schema, the description covers both parameters, the mention feature, the length limit, and the return value. No critical information appears missing for an agent to invoke 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 is the only source of parameter meaning. It defines file_id as the numeric file ID to comment on and message as the comment text with max length and @username syntax, fully compensating for the schema's lack of 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?

States the exact action and object: 'Add a comment to a file.' This clearly distinguishes it from sibling comment tools like list_comments, edit_comment, and delete_comment by naming the creation action and the target resource.

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

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

Provides actionable constraints: use @username to mention users and maximum message length of 1000 characters. However, it does not explicitly say when to choose this tool over edit_comment, delete_comment, or list_comments; usage context is implied rather than directly 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 idempotentHint=true, and the description reinforces this by stating 'Tagging a message that already has the tag changes nothing.' This adds behavioral context beyond the annotation. It also clarifies the operation is non-destructive (destructiveHint=false) and readOnlyHint=false, which is consistent. The description could mention side effects like notification triggers, but the idempotency disclosure is valuable.

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 front-loaded with the core action and idempotency note. The Args section is structured and each parameter gets a clear explanation. The Returns section is brief. 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 two-parameter mutation tool with an output schema and annotations covering idempotency and safety, the description covers the essential context: how to find both parameters, what the operation does, and what it returns. It doesn't mention error cases or permission requirements, but those are not critical for this simple 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%, so the description carries the full burden. It explains message_id as 'The message database ID' and how to find it, and imap_label as 'The tag's IMAP label' with concrete examples of built-in tags. This adds significant meaning beyond the bare schema properties. It doesn't explain the return value in detail, but the output schema exists.

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: 'Tag a message' with an IMAP label. It clearly distinguishes from siblings like remove_mail_message_tag and create_mail_tag. However, it doesn't explicitly name the sibling alternatives, so it doesn't fully earn a 5.

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 how to find message_id via list_mail_messages and how to obtain imap_label via create_mail_tag or list_mail_messages, including built-in tag examples. It doesn't explicitly state when not to use it or contrast with remove_mail_message_tag, but the context is clear enough for an agent to select it 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 idempotentHint=true and destructiveHint=false; the description reinforces idempotency and adds genuinely new behavioral context: the moderator-rights requirement and the constraint that one-to-one and note-to-self conversations take no participants. This is useful auth and edge-case disclosure beyond the structured hints.

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?

Front-loaded one-line summary, then structured Args/Returns blocks. Given three undocumented parameters and five source modes, every sentence earns its place; there is 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?

Covers prerequisites, idempotency, per-source semantics, and conversation-type exclusions; output schema exists but the description still points to get_participants for attendee IDs. Nothing needed to invoke this mutation correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does it well: it explains token, enumerates every participant format, and documents all five source values including default and side effects ('groups' adds every member, 'emails' invites a guest). This substantially exceeds what the bare schema provides.

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

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

States a specific verb and resource ('Add someone to a conversation') that is clearly distinct from neighboring tools like add_circle_member, remove_participant, and set_participant_role. An agent can identify the target operation without opening the schema.

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

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

Gives real preconditions ('Needs moderator rights') and an operational caveat ('adding someone twice changes nothing'), plus per-source guidance on which source value to pick. It stops short of naming alternatives or when-not-to-use cases (only the one-to-one/note-to-self limitation is 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 idempotentHint=true, so the line about reacting twice changing nothing largely restates structured data. The description does add value by describing the payload shape ("mapping each reaction on the message to who used it") and implying mutation via "React," but adds no auth requirements, error behavior, or rate-limit 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?

One-sentence purpose plus tightly scoped Args and Returns blocks, front-loaded and free of filler. The Args entries are slightly terse but each earns its place.

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

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

For a single-mutation tool with an output schema present, the definition covers purpose, all parameters, and idempotent behavior. Auth/permission requirements and failure modes are the only meaningful omissions.

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 carries the full burden and does so: it documents all three parameters, clarifies token is a conversation token and message_id the target, and gives a concrete example ("👍") for the reaction format. Only the integer type/range of message_id and token sourcing remain unstated.

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

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

States a specific verb + resource ("React to a chat message with an emoji"), which is unambiguous and easily separable from siblings like get_reactions or remove_reaction. It stops short of explicitly naming the inverse/related tools, so it is clear but not sibling-differentiating at the top level.

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 versus get_reactions (read) or remove_reaction (undo), nor any prerequisite/auth context. The only usage-adjacent statement, "Reacting twice with the same one changes nothing," is a behavioral note rather than a when-to-use rule.

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 signal a non-readonly, idempotent, non-destructive operation, and the description aligns with them. It adds a concrete behavioral detail: 'Assigning an already-assigned tag has no effect,' which prevents agents from treating duplicate assignments as errors.

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 about six short lines, front-loads the core purpose, and includes only high-value additions: ID lookup, idempotency, args, and return. There is no filler or redundant restatement of the schema.

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 two-integer-parameter mutation with an output schema, the description covers purpose, argument resolution, idempotency, and return value. Nothing material is missing for an agent to call this 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?

The input schema has 0% description coverage, so the Args section carries the burden, and it defines both parameters. More valuably, it tells the agent how to obtain valid values via list_tags and list_directory; the individual definitions are terse but sufficient.

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 'Assign a system tag to a file,' a specific verb and resource statement. It clearly distinguishes assign_tag from siblings like unassign_tag and 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 explicitly directs the agent to use list_tags and list_directory to resolve valid IDs, which is practical usage context. It does not explicitly name the inverse alternative unassign_tag or state when not to use it, but the 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?

The description adds meaningful behavioral context beyond the annotations: it specifies the mutation scope (custom status message and icon), the non-effect on online status, and the confirmation return. Annotations already mark it as idempotent and non-destructive, and the description does not contradict 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 compact and front-loaded with the primary action, followed by a valuable clarification and a return note. Every sentence earns its place with no filler or repetition.

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

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

This is a low-complexity, zero-parameter, idempotent operation with annotations and an output schema already present. The description fully covers the action, scope, key exclusion, and return value, so nothing an agent needs is missing.

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

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

There are zero parameters, so the baseline is 4 and there is no ambiguity to resolve. The description's inclusion of 'current user' clarifies the implicit scope of the operation, which is the only semantic context needed.

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

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

The description uses a specific verb and resource: it clears the current user's status message and icon. It also distinguishes itself from related status tools by clarifying that it does NOT change the online status type, so an agent can tell exactly what operation 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 description gives clear context for when to use the tool: when you want to remove the custom status message and icon. It also provides a when-not signal by explicitly stating it does not affect online status type, although it does not name set_user_status or get_user_status as 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?

Beyond the destructiveHint and idempotentHint annotations, the description explains irreversibility, that voting stops, that results become visible regardless of result_mode, and the required authorization. No contradiction with annotations exists.

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 tightly organized: one-sentence purpose, behavioral consequences, permission/irreversibility warning, then args and return. Every sentence adds relevant information 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 two-parameter mutating tool, the description covers authorization, side effects, irreversibility, and return shape. The output schema signal reduces the need to document return values further, and nothing critical is missing.

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

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

Although schema description coverage is 0%, the Args section adds plain-language meaning: token is the conversation token and poll_id is the poll to close. It does not go into lookup/origin details, but it compensates for the bare schema titles.

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 ('Close a poll in a Talk conversation') and distinguishes this from sibling poll operations like create_poll and vote_poll. It also explains the consequences of closing, making the tool's role 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 clearly communicates when to use it (to end a poll and reveal results) and adds a permission constraint (creator/moderator only). It does not explicitly name alternatives or say 'use X instead', but the context is sufficiently 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 idempotentHint=true and destructiveHint=false, so the description's mention of no-op behavior aligns but doesn't add much beyond that. It does add the detail of specific field updates (percent-complete, timestamp), which is useful context. However, there is no note on permissions or side effects 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 concise with a clear first sentence stating the primary action, followed by specific behavioral details and parameter explanations. Each sentence serves a purpose without redundancy.

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

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

For a tool with only 3 simple parameters and an output schema (though not detailed here), the description covers the core behavior, idempotency, and locking. It could benefit from noting required permissions or that the task must exist, but these are minor given the simple scope.

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 0%, but the description explicitly explains each parameter: list_id is the list identifier, task_uid is the task's UID (with a pointer to get_tasks), and etag is for optimistic locking. This adds meaning beyond parameter names, but it's basic and doesn't elaborate on syntax or edge cases.

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 it marks a task as completed, with specific state changes (status to COMPLETED, percent-complete to 100, timestamp). It distinguishes itself from sibling tools like update_task or create_task by focusing solely on completion.

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 idempotent no-op behavior when already completed and mentions optimistic locking via etag. It does not explicitly contrast with update_task, but the completion-specific action is clear enough for an agent to select it appropriately.

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 annotation idempotentHint is true, but the description says 'Fails if the destination already exists.' This contradicts idempotency: calling twice with the same arguments will fail the second time. Therefore the description contradicts the annotations, so the score is 1.

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, front-loaded, and efficiently structured. It covers behavior, failure condition, parameters with examples, and return type without any 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?

For a simple 2-parameter tool, the description provides everything an agent needs: what it does, failure condition, parameter semantics with examples, and the return type. No additional information is needed to call it correctly.

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

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

The schema has no descriptions (0% coverage), so the description must compensate. It provides clear semantic meaning for both source and destination, including concrete examples. This adds value beyond the raw schema, though it does not specify path formats relative to a root.

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 (copy) and the resource (file or directory in Nextcloud). It distinguishes from siblings like move_file by explicitly saying 'source remains unchanged', making the semantic distinction 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 explains the copy operation but does not explicitly mention when to use this tool versus alternatives like move_file or delete_file. The purpose is clear from context, but no explicit guidance or exclusions are given.

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 indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false – they don't specify side effects. The description adds that it posts to the Announcement Center, optionally triggers activities, notifications, and emails, and requires admin privileges. This is valuable behavioral context beyond what annotations provide.

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 well-structured: a summary sentence, an effect explanation, an Args block, and a Returns line. It is slightly longer than necessary but every sentence adds value, and the core purpose is front-loaded. The parameter list is formatted for quick scanning.

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 8-parameter tool, the description covers every parameter with explanations, states the admin requirement, and outlines side effects. The output schema exists, so a high-level 'Returns: JSON object' is sufficient. Nothing essential is missing for an agent to call this 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 carries full responsibility for parameter meaning. It explains all 8 parameters: subject, message, plain_message, groups, activities, notifications, emails, and comments – each with purpose, defaults, and in some cases formats (e.g., Markdown, group ID list). This far exceeds the schema's bare types and defaults.

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

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

States a specific verb and resource: 'Create a new announcement in Nextcloud.' This clearly distinguishes it from siblings like list_announcements and delete_announcement. The scope 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 indicates when to use it (to create an announcement) and includes a prerequisite ('Requires admin privileges'). It does not explicitly mention alternatives or when not to use it, but the purpose is so clear that usage is effectively implied. A slightly stronger explicit contrast with list/delete would make it 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 cover only the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds substantial behavioral context beyond that: the caller is auto-added as owner at level=9, team_folder requires Nextcloud 35 with the Team folders app, the folder name gets a numeric suffix on collision, and deleting the team later deletes the folder and its files. That last point is exactly the kind of destructive side-effect an agent needs.

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

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

The purpose is front-loaded in one line, then Args and Returns sections keep the detail scannable. It runs long, but nearly every sentence carries prerequisite or side-effect information that isn't repeated elsewhere; only minor trimming is possible.

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 4-parameter creation tool with prerequisites and cascading effects, the description covers ownership, version/app requirements, naming collisions, the returned shape, and the team_folder/team_folder_note result fields. Nothing an agent needs to call it correctly is missing, and the output schema handles the rest.

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 carries the full burden and meets it: each of the four parameters gets meaning, defaults, and edge conditions (name need not be unique, personal limits visibility to the owner, local suppresses federation even when global scope is enabled, team_folder has a version/app prerequisite and a cascading delete).

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+resource: 'Create a new circle (team).' The parenthetical disambiguates the Nextcloud notion of a circle/team, and the sibling set includes other creation tools (create_collective, create_group, create_conversation) that an agent can distinguish by the resource named here.

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

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

Usage is implied by the tool name and the per-parameter semantics (personal for private groups, local for non-federated), but there is no explicit 'use this when...' guidance or comparison against sibling creation tools like create_collective or create_group. An agent can infer the context but must supply the routing decision itself.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), yet the description adds real side-effect disclosure beyond them: an automatic landing page, an auto-created team/circle of the same name, and a team folder on Nextcloud 35+ with the Team folders app. It omits permission requirements and what happens on name collision besides 'must be unique'.

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?

Front-loads the purpose, then the concept, then side effects, then args/returns. The prose paragraph is justified because the side effects are non-obvious, though the Returns block partly restates what an output schema already provides.

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

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

For a create tool with annotations and an output schema, the description covers purpose, side effects, and both parameters, which is enough to invoke it correctly. The main gap is the absence of permission/authorization context and duplicate-name 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?

Schema description coverage is 0%, so the description carries the full parameter burden and does so: it marks name as required and unique, and explains emoji as an optional icon with a concrete example. It could still note name length limits or formatting rules.

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

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

States a specific verb and resource ('Create a new collective'), and immediately defines what a collective is (shared wiki-like knowledge base), which draws a clear line against siblings like list_collectives, trash_collective, delete_collective, and the page-level 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?

Usage is implied by the verb and by the 'must be unique' constraint, but the description never states when to create a collective versus other options (e.g. joining an existing one via join_circle, or whether trashing is recoverable later). No explicit when-not or alternative routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is known. The description adds the structural parent requirement and notes the return type, but does not mention auth/permission needs or side effects beyond what annotations 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?

Front-loaded with the core action, then structured with Args and Returns sections. Efficient overall, though the 'Returns' line partly duplicates the output schema and could be trimmed.

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 4-param creation tool with an output schema present, the description covers the action, the structural constraint, and each parameter. It is largely self-sufficient, missing only permission/error expectations, which the output schema and annotations partially offset.

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?

With 0% schema description coverage, the description carries the burden and does so: it documents collective_id (numeric collective ID), parent_id (with the non-obvious landing-page-ID rule), title (required), and content (optional Markdown). Only omission is that the underlying types/defaults are left to the schema.

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

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

States a specific verb+resource ('Create a new page in a collective') and adds a useful conceptual model (Markdown documents in a tree structure). It is clearly distinguishable from sibling read/mutation tools like update_collective_page and get_collective_pages, though it does not name them explicitly.

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

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

Gives a concrete usage rule: every page must have a parent, and top-level pages should use the landing page ID from get_collective_pages. This routes the agent usefully, but it offers no explicit when-not or alternative-tool guidance (e.g., vs update/move).

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=false, covering the safety/idempotency profile. The description adds the return shape, but says nothing about required permissions, whether duplicate tag names are rejected, or side effects on existing pages. With annotations doing the heavy lifting, this is adequate but not rich.

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

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

Purpose is front-loaded in the first sentence, followed by compact Args and Returns sections. No filler, though the structured boilerplate is slightly heavier than a single tight paragraph would be.

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 an output schema present, return values need not be explained, yet the description still summarizes them. Params are covered and annotations give the safety profile, leaving only usage routing and permission behavior as gaps. Complete enough for a straightforward create 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%, so the description must carry the meaning, and it does: collective_id is 'numeric collective ID', name is the tag's name, and color is specified as six hex digits with or without '#' plus the default '0082C9'. The color format/default detail is genuinely additive and not present in the schema.

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

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

States a specific verb and resource ('Create a page tag') and scopes it to 'in a collective', which distinguishes it from siblings like create_conversation_tag, create_mail_tag, and create_tag. It does not explicitly name those siblings, so it stops short of a 5.

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

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

No guidance on when to use this versus the many other tag-creation tools (create_tag, create_conversation_tag, create_mail_tag) or when a tag is warranted. The scope is implied by the name only; an agent gets no explicit when-to-use or exclusion 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?

The description discloses key behaviors beyond the annotations: single email/phone is added with TYPE=WORK/CELL, multiple emails/phones override the single parameters, and the return format is a JSON contact object. These details help the agent predict outcomes, especially since annotations only say readOnlyHint=false and 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?

The description is well-structured: a one-line summary, then requirements, parameter details, and return info. It is front-loaded with the core purpose, and each sentence adds necessary information—no fluff. The length is justified given the 11 parameters and their interactions.

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 complexity (many optional parameters, mutually exclusive sets, nested objects), the description covers all required information: field requirements, parameter semantics, examples, and return value. An agent has everything needed to call it correctly without consulting the output schema or further documentation.

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?

With 0% schema description coverage, the description fully compensates by explaining every parameter, including the nested structure for emails/phones with an example. It also clarifies the precedence (emails overrides email) and the default for book_id. This adds substantial meaning beyond the bare schema.

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

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

The description states a clear verb and resource: 'Create a new contact in an address book.' It also specifies the minimum required fields (full_name or given_name/family_name), which distinguishes it from sibling tools like update_contact and delete_contact. 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?

It provides explicit usage instructions: the minimum required fields, how to specify single vs. multiple emails/phones, and a warning not to provide both forms. It also clarifies the default for book_id. These guidelines tell an agent exactly when and how to use the tool, including constraints that prevent errors.

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 establish the write/non-idempotent/non-destructive profile. Beyond that, the description adds genuinely useful behavior: the 1:1 dedup-and-return-existing rule, the fact that preset settings are applied and that an explicit room_type overrides the preset, and that the response carries a token. This is meaningful context that the annotations cannot express.

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 purpose leads and the Args/Returns structure is easy to scan; each clause carries information. It is somewhat long, but the length is justified by five undocumented parameters and non-obvious behaviors, so nothing is wasted.

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 an output schema present, the description need not detail return fields, yet it still notes the response includes the conversation token. Combined with full parameter documentation and the preset/room_type precedence rule, an agent has everything needed 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 description coverage is 0%, so the description carries the full parameter burden and does it well: room_type is enumerated with meanings (1=one-to-one, 2=group, 3=public), invite is marked required for one-to-one and optional for group, name is noted as ignored for one-to-one, and description/preset scopes are stated.

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

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

States a specific verb and resource ('Create a new Talk conversation'), which is unambiguous. It does not, however, differentiate itself from the many other create_* siblings (create_group, create_circle, create_collective, create_flow), so an agent gets a clear purpose but no routing help.

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 the conditional scenarios that matter: group conversations are invite-only, public ones are joinable via link, and a one-to-one with an existing partner returns the existing conversation. It gives clear context but never names an alternative tool or states explicit when-not-to-use 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds concrete business constraints not in any structured field: a 100-tag personal limit and a 250-character distinct-name requirement. This is real behavioral value beyond 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 purpose is front-loaded in the first sentence, and the constraint sentence is compact. The Args/Returns sections are slightly redundant given the output schema exists, but nothing is bloated.

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?

An output schema is present, so the Returns block is redundant rather than harmful. For a simple one-parameter creation tool the constraints and return shape are covered, but the absence of routing guidance against the many sibling tag tools leaves a practical 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% for the single parameter, and "name: The tag's name" is essentially a tautology. However, the description's "distinct names of up to 250 characters" does add a real constraint and format limit for the name parameter, partially compensating for the coverage 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+resource ("Create a personal conversation tag"), and the qualifier "personal conversation" distinguishes it from create_collective_tag, create_mail_tag, and create_tag. It does not explicitly name those siblings, so differentiation relies on the agent inferring scope from the qualifier.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer from the sibling list that other tag-creation tools (create_collective_tag, create_mail_tag, create_tag) exist, without the description telling it which to pick.

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 negative hints (not read-only, not idempotent, not destructive), so the description carries the behavioral burden. It discloses that an empty payed_for list raises ValueError and explains server-side behavior on create vs update, documents date/timestamp defaulting and precedence, and specifies the return value as JSON {"bill_id": <int>}. 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?

The purpose and permission are front-loaded, and the Args section is dense but purposeful given the 14-parameter surface. Every parameter gets a meaningful explanation, default, or constraint, with no filler or redundant prose.

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 write operation with 14 parameters, no schema descriptions, and sparse annotations, the description is complete. It covers prerequisites, edge cases, defaults, output shape, and client/server behavior, leaving no critical information missing 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?

Schema description coverage is 0%, and the description compensates fully by documenting all 14 parameters. It provides formats for date and timestamp, enumerates repeat values, explains defaults, and clarifies cross-parameter constraints such as date/timestamp precedence and payed_for non-emptiness.

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: 'Create a bill (expense) in a Cospend project.' It also states the required access level, which immediately distinguishes this from sibling tools like get_cospend_bill, update_cospend_bill, and delete_cospend_bill.

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 establishes clear context by stating the create action and the PARTICIPANT access requirement. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough that an agent can identify when to use this tool versus update or delete 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 only carry basic mutation flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds substantial behavioral context: the MAINTAINER permission requirement, the soft-disabled creation mode and why it's rare, the side effect of linking a user_id (member sees the project in their UI), and the exact return shape. This goes well beyond what annotations reveal.

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 organized with clear sections (access, Args, Returns) and each parameter line earns its place by adding semantic meaning absent from the schema. It is longer than needed because defaults are restated from the schema, but that duplication is forgivable given the schema's zero 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?

The description covers permissions, all six parameters with defaults and edge cases, the return-value semantics, and cross-references to other tools (update_cospend_member, memberId for other tools). An agent has everything needed to invoke this 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 carries the full burden — and it delivers. Every parameter is explained: project_id and name, the optional user_id with its visibility effect, weight with the concrete 'counts double in even splits' example, active with the soft-disable caveat, and color with hex format guidance and server-pick fallback.

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: 'Add a member to a Cospend project.' This clearly distinguishes it from siblings like update_cospend_member or list_cospend_members, and the scope (create, not modify) 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 states the required access level ('Requires MAINTAINER access') and gives an explicit alternative routing for a specific case: 'usually create active and disable later via update_cospend_member.' It doesn't broadly contrast with all siblings, but the key decision points are covered.

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 not idempotent or destructive. The description adds valuable context: the caller becomes ADMIN, the server may modify the provided project_id for uniqueness, and the return payload includes default categories/payment modes. These details go beyond the structured annotations without contradiction.

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, with an intro line, an Args block, and a Returns block. Every sentence contributes value, and the key behavior (id uniqueness) is highlighted. It is slightly longer than the absolute minimum but remains 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?

Given the 0% schema coverage and the presence of an output schema, the description covers the essential behavior: what the tool does, how the id resolves, and what the return contains (including reference to get_cospend_project). It does not cover edge cases like error handling, but for a create operation with clear return semantics, this 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 0%, so the description must carry the full weight for parameters. It does: it explains that project_id is a desired slug that may be altered with a digit, and that name is a non-unique display name. This is meaningful semantic information not present in the schema.

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

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

The description states a specific action ('Create a new Cospend project') and a clear resource, distinguishing it from siblings like update_cospend_project and delete_cospend_project. It also adds the role implication (caller becomes ADMIN), which further clarifies 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 purpose is evident, but there is no explicit guidance on when to use this tool versus alternatives (e.g., checking for existing projects with list_cospend_projects). The context implies use for new projects, but it does not state exclusions or prerequisites, so an agent must infer the appropriate scenario.

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 idempotency and non-destructiveness. The description adds only the operation and a confirmation-message return, but does not disclose behavior if the directory already exists, whether nested parents are created, or required 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 compact and well-structured: a one-line purpose, an Args section with an example, and a Returns section. There is no unnecessary filler or repetition.

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 one-parameter tool with an output schema and safety annotations, this is minimally adequate. However, it omits important operational details such as existing-directory behavior, nested path creation, and whether the path is relative to a specific root.

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 the parameter name 'path' with 0% description coverage, so the description carries the burden. It clarifies the parameter as 'Directory path to create' and gives a concrete example, which is meaningful. It stops short of explaining path rooting or parent-directory 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 states a specific action and target: 'Create a new directory in Nextcloud.' This is clear and distinct from sibling file-related tools, though it does not explicitly call out an 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?

The description gives no guidance on when to use this tool versus related operations like list_directory, move_file, or upload_file. There are no conditions, exclusions, or alternative tool mentions.

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 are minimal (all false), so the description carries most of the behavioral burden. It goes beyond the schema by explaining default end time behavior, all-day date handling, status default, and RRULE examples. It does not explicitly warn about non-idempotency, but creation side effects are strongly implied by 'Create'.

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 uses a clean, front-loaded summary followed by a structured Args/Returns layout. Each parameter entry adds necessary detail without fluff, making the longer length justified by the tool's 10-parameter complexity.

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

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

Given the high parameter count and missing schema descriptions, the description covers every parameter, their defaults, and the return shape. An agent can invoke the tool correctly with only the information provided here, and the output schema makes the return details even clearer.

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 fully compensates. Every parameter is explained with format expectations, defaults, and concrete examples (e.g., ISO 8601 formats, RRULE examples, all-day restrictions). This is far more useful than the bare input schema.

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

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

The description opens with a specific verb and resource: 'Create a new calendar event.' It clearly identifies the tool's function and is easily distinguished from siblings like get_event, update_event, and delete_event.

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 'Create a new calendar event' clearly establishes the intended use case of creating rather than reading, updating, or deleting an event. However, it does not explicitly name alternative tools or state when-not-to-use this tool, so it falls short of the highest bar.

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 flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it warns that a global access-control rule with over-broad checks can lock every user (including the server) out of their files, notes the destructive permission requirement, and documents the command-execution refusal policy. This is substantive operational and safety context not available in 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?

Front-loaded with purpose and safety warnings, then an Args block and a short Returns line; the ordering is logical and each section maps to a real agent need. It is long, but the length is largely justified by 0% schema coverage, with only minor repetition around get_flow_options.

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?

An output schema exists and the description briefly notes what is returned ('JSON with the created flow, as list_flows shows it'), so it does not need to enumerate the response. Combined with full parameter documentation and destructive-behavior warnings, an agent has everything required 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 0%, so the description must carry the whole load, and it does: every one of the seven parameters is documented with type, default behavior (scope 'user' default, entity default class, events required-unless-fixed), plus concrete examples for operation_config and the check object shape. The nested format of checks is spelled out with a realistic value.

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

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

The opening sentence gives a precise verb+resource ('Create a Nextcloud Flow rule') plus the trigger/action model ('when an event happens and all checks match, run an operation'). It cleanly distinguishes this from the sibling read/update/delete flow tools (list_flows, update_flow, delete_flow, get_flow_options).

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 routes the agent to get_flow_options for class names, states that an unknown class name causes a server error, distinguishes user vs global scope ('global (admin only)'), and names the permission level global flows require. It also states what is refused (operations that run a command or command-line arguments), so the agent knows the boundaries before calling.

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 readOnly/idempotent/destructive hints, so the description carries the behavioral burden. It discloses return behavior, the default empty title, and the important clone boundary that submissions and shares are not copied. It does not mention permissions or error behavior, but the core side effects are 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 compact and well-structured: a one-sentence summary, an Args section, a Returns section, and a brief workflow. No fluff, and every sentence adds either behavior or routing 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 one-parameter create tool with an output schema, the description covers what the tool does, what it returns, how the optional parameter behaves, and what to do next. Nothing essential is missing 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?

Schema description coverage is 0%, so the description must fully document from_id. It does: optional id of an existing form to clone, copying questions and options, but not submissions or shares. This adds meaningful semantic detail far beyond the bare integer-or-null schema.

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

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

The description uses a specific verb and resource ('Create a new form') and adds concrete details about the generated id and default empty title. It also clearly differentiates this tool from nearby siblings by explicitly pointing to update_form and create_question as follow-up steps.

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 an explicit workflow: use update_form to set title/description, then create_question to add questions. It also explains the cloning use case via from_id. It does not give formal 'when not to use' guidance, but the context is clear enough for an agent to select this tool 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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds meaningful behavioral context by specifying the default permissions (['submit']) and the return value (JSON of the new share with its id). It does not fully disclose side effects like whether existing shares are replaced or whether link shares require special handling, but it goes 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 compact and well-structured: a one-sentence summary followed by a concise Args list. Every line adds necessary information, and the most important usage detail (share_type codes) is front-loaded. No filler or repetition.

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 parameters, defaults, and return value, which is sufficient for an agent to invoke the tool correctly. It does not mention edge cases like whether permissions are validated against the form's existing settings or whether public link shares require a different permission set, but the output schema and annotations cover the rest. A small gap remains around error conditions or prerequisites.

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 carries the full burden of explaining parameters. It explains form_id, share_type (with numeric codes), share_with (with the omit-for-link rule), and permissions (with the allowed string values and default). This fully compensates for the schema's lack of 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 opens with a specific verb and resource: 'Share a form with a user, group, circle, or via public link.' It clearly enumerates the share types and distinguishes this from sibling tools like update_form_share and delete_form_share. 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 explains the share_type values and when to omit share_with (for link shares), which gives clear context for using the tool. It does not explicitly name alternatives or state when not to use this tool, but the sibling list and the detailed share_type semantics make 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?

Annotations confirm a non-read-only, non-idempotent, non-destructive write. The description adds valuable traits beyond them: the admin-permission requirement, the immutability of group_id, and the display_name default. It does not discuss idempotency behavior or error modes, but the added context is meaningful.

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?

Front-loaded purpose, then permissions, then workflow, then structured Args. Dense with no filler sentences, and each line 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?

An output schema already exists, so the brief 'Returns: Confirmation message' is sufficient. Combined with permissions, parameter semantics, and the follow-up path, an agent has everything needed to call this 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 carry the load, and it does: group_id is explained as the persistent reference key that cannot change, and display_name as the UI name defaulting to the ID. Both parameters receive semantics beyond the bare schema types.

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

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

States a specific verb and resource ('Create a new group') and distinguishes itself from siblings like list_groups, delete_group, and list_group_members without ambiguity. The follow-up note pointing to update_user adds scope 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?

Gives a clear precondition ('Requires admin rights (or delegated user administration)') and a concrete follow-up workflow (add users via update_user's groups field). It does not explicitly contrast against alternative creation paths, but the when-to-use context is solid.

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

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

The description goes well beyond the idempotentHint annotation by detailing that an existing tag is 'returned unchanged, including its color,' and explains how IMAP labels are derived from display names. It also warns about built-in labels $label1 to $label5. These specifics enrich the agent's understanding of side effects and return 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 front-loaded with the core purpose, then provides necessary behavioral context, parameter details, and return usage. Every sentence adds value, and the Args/Returns structure makes it easy to scan. Nothing is redundant.

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

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

Given the tool's moderate complexity and the presence of output schema and annotations, the description is complete: it covers behavior, parameter constraints, built-in label handling, return fields, and downstream usage with sibling tools. An agent has everything needed 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 0%, so the description carries full responsibility for parameter documentation. It explains display_name with a 128-character limit and forbidden characters, and color with a concrete hex format example. This fully compensates for the bare 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 first sentence states a specific verb and resource: 'Create a mail tag, or get the existing tag with the same IMAP label.' It clearly distinguishes this from generic tag tools by focusing on mail tags and IMAP labels, and explains the get-or-create behavior. The built-in tag warning further clarifies the tool's specific role.

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

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

The description provides clear context: tags belong to the current user, labels are derived from display names, and built-in tags should be referenced by their standard labels instead of creating duplicates. It also tells the caller to pass the returned imap_label to add_mail_message_tag and remove_mail_message_tag. It does not explicitly contrast this tool with create_tag, but the mail-specific scope is evident.

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, idempotentHint=false, destructiveHint=false). The description adds valuable behavioral context: options on non-choice questions are accepted but have no effect, and options are created in order. It also discloses the return value (JSON array of created options with ids and order), which goes 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 compact and well-structured, with a clear summary line followed by parameter explanations and return value. Every sentence earns its place, and the key behavioral caveat (options on other types have no effect) is included without bloat.

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 moderate complexity (3 required params, no nested objects) and the presence of an output schema, the description is largely complete. It covers the purpose, parameter semantics, and return value. The only minor gap is that it doesn't explicitly state error conditions or prerequisites (e.g., whether the question must exist), but this is not critical for an agent to invoke 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. It explains each parameter: form_id is a numeric form id, question_id is a numeric question id intended for choice-type questions, and option_texts is an array of labels creating separate options in order. This adds meaning beyond the bare schema types, though it could be more explicit about the format of option_texts (e.g., strings).

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 ('Add one or more answer options') and the resource ('choice question'), and distinguishes it from sibling tools like update_option and reorder_options by focusing on creation. It also specifies the intended question types, which helps an agent understand the tool's 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 provides clear context for when to use this tool: when adding options to choice-type questions. It also notes that options on other question types are accepted but have no effect, which is an implicit exclusion. However, it doesn't explicitly name alternatives like update_option or reorder_options for modifying existing options, so it falls short of full when/when-not 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?

The description discloses the automatic chat message, the conversation-type restriction, and result visibility behavior for result_mode. These go well beyond the minimal annotations, covering side effects and constraints.

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?

Structured with Args and Returns sections, every sentence adds essential detail. The front-loaded purpose and constraints precede parameter details, keeping it both complete and readable.

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 creation tool with 5 params, an output schema claim, and no annotation coverage, the description covers purpose, constraints, side effects, parameter semantics, and return shape. There are no obvious gaps an agent needs 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?

With 0% schema description coverage, the description fully documents all five parameters: token (how to find), question (max length), options (min 2 + example), result_mode (values and meaning), max_votes (0 = unlimited). It also includes defaults.

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 'Create a poll in a Talk conversation' – a specific verb and resource. It adds constraints (group/public only) and a side effect (auto chat message), making it distinct from siblings like vote_poll/close_poll.

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 clear context: polls can only be created in group/public conversations, not one-to-one, and it points to list_conversations for finding tokens. It doesn't explicitly reference alternative creation tools, but the context is sufficient for selection.

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 mark the operation as non-readonly and non-idempotent, so mutation is expected. The description adds useful behavioral context: creating a question returns a JSON object with assigned id and order, clone behavior via from_id, default-empty text, the grid-only subtype requirement, and the Nextcloud-specific datetime rejection. This goes well beyond what the annotations and schema alone communicate.

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 well-organized into Args and Returns sections. Every sentence adds substantive information: parameter semantics, constraints, edge cases, and follow-up actions. There is no fluff or repetition despite the length, and the most important usage caveat (datetime rejection) is clearly highlighted.

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 creation tool with a non-trivial parameter set and no schema descriptions, the description is complete. It covers all parameters, required context for question types, the clone option, return behavior, and related downstream tooling (create_options). The output schema exists, so the description wisely summarizes the result without over-explaining the response structure.

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 carries the full burden—and it delivers. It explains every parameter: form_id as numeric, question_type with all valid values and human-readable meanings, the datetime exception, text default and later update path, subtype scoped to grid with its valid cell types, and from_id as an optional clone source. This is far richer than the bare 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?

Description opens with a specific verb and resource: 'Add a question to a form.' It goes beyond a simple label by clarifying the return value ('JSON of the new question'), the clone behavior via from_id, and explicitly distinguishes the tool from create_options by directing choice-type setup to that sibling.

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 contextual guidance: it notes that text defaults to empty and can be set later via update_question, tells users to use create_options for choice types, and warns that datetime is rejected in favor of separate date/time questions. It lacks an explicit general 'use this instead of X' statement for update_question/reorder_questions, but the key alternatives are named.

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, destructiveHint=false, idempotentHint=false). The description adds valuable behavioral context: default permissions vary by share type, file shares automatically strip create/delete flags, and the return value includes id, url, and token. This goes beyond what annotations provide, though it doesn't cover every edge case like error conditions 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 well-structured with clear sections for each parameter and a returns section. It's longer than average, but the density of useful information justifies the length. The front-loaded purpose statement and organized parameter list make it scannable. Minor deduction for the length, but 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 9-parameter tool with 0% schema coverage, this description is remarkably complete. It explains all parameters, provides examples, documents defaults, notes behavioral nuances (file shares stripping flags), and describes the return value. The output schema exists, so return details are supplementary. Nothing critical is missing for an agent to invoke this 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 carries the full burden of explaining parameters. It does this excellently: each parameter gets a clear explanation, with examples for path, enumerated values for share_type, recipient format per share type, bitwise permission flags with common values, and defaults. This is far beyond what the bare schema provides.

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

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

The description opens with a clear verb+resource statement: 'Create a new share for a file or folder.' It distinguishes itself from siblings like update_share, delete_share, and list_shares by focusing on creation. The detailed parameter breakdown further clarifies the exact scope of the operation.

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

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

The description provides clear context on when to use this tool: when creating a new share for a file or folder. It implicitly distinguishes from update_share (modifying existing shares) and delete_share (removing shares). However, it doesn't explicitly state 'use this instead of X when...' or mention alternatives, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description doesn't need to restate those. The description adds the admin privilege requirement and notes that user_visible and user_assignable default to true, which is useful behavioral context. However, it doesn't disclose what happens if a non-admin tries to create a non-visible tag, or whether the operation is reversible.

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 front-loaded with the core action. The parameter explanations are brief and useful. The Returns line is a minor addition but not wasteful. It earns a 4 because it's efficient without being terse.

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 an output schema, so return values are covered. The description covers the main parameters and the admin privilege caveat. However, it doesn't mention potential errors, idempotency implications, or how this tag creation relates to the broader tag lifecycle (e.g., assign_tag). For a simple create operation, this is adequate but not comprehensive.

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. It does explain each parameter: name, user_visible, and user_assignable, including defaults. This adds meaning beyond the raw schema, which only lists types and defaults. However, it doesn't elaborate on edge cases or format constraints for the name parameter.

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 and resource: 'Create a new system tag.' It also distinguishes the tool from siblings like list_tags, assign_tag, unassign_tag, and delete_tag by specifying creation. However, it doesn't explicitly differentiate from create_mail_tag, which is a sibling that also creates a tag, though the 'system tag' wording helps.

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 mentions a prerequisite: 'Requires admin privileges for non-visible/non-assignable tags.' This gives some context on when the tool is appropriate. However, it doesn't explicitly state when to use this tool versus alternatives like create_mail_tag or assign_tag, nor does it provide exclusions or alternative routing.

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

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

Annotations already indicate this is a mutating, non-idempotent operation, and the description does not contradict that. It adds useful output context (the created task's uid and summary) and default behavior, but it does not disclose permissions, duplicate-creation consequences, or failure modes.

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 front-loaded with the core purpose, then uses a clean Args/Returns structure with one line per parameter. It contains no filler or redundant prose, and its length is appropriate for nine parameters.

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