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

Beyond the annotations, the description discloses the precise state changes (status, percent, timestamp) and the important edge case that completing a repeating task is refused to avoid ending the series. This adds meaningful behavioral context that the annotations do not provide, and nothing contradicts 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?

Two tight sentences: the first front-loads the core action and resulting values, and the second handles the crucial repeating-task exception with a clear explanation. There is no filler or redundant restatement of the tool name or 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 mutation tool with strong annotations and fully documented parameters, the description covers the essential effect and the main refusal case. The absence of an output schema is acceptable, though a brief note on what is returned after completion would make it fully complete.

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

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

The input schema already documents all three parameters with 100% coverage, including the conditional-write meaning of etag and the list identifier. The description adds no parameter-specific meaning, but it does not need to since the schema carries the burden.

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 ('Mark a task done') and specifies the exact resulting state: status COMPLETED, 100 percent, and current timestamp. It also clearly distinguishes behavior from related tools by stating that repeating tasks are refused, so there is no ambiguity about what this tool does.

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 gives clear usage context for ordinary single-occurrence tasks and explicitly excludes repeating tasks with a rationale. It does not name an alternative tool such as update_task or uncomplete_task, but the refusal condition is concrete enough for an agent to decide when not to call it.

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

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

With no output schema, the description usefully states that the tool 'Returns the task as stored, including its new uid,' which an agent would otherwise not know. It also discloses the list-resolution behavior. Annotations already indicate this is not read-only, so the description adds value beyond them 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?

Two sentences, no filler. The core action is front-loaded, followed by the most important optionality rule and the return behavior. Every clause 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 16-parameter tool with no output schema, the description plus the fully documented schema gives an agent everything needed to call it correctly. It covers the required input, the one conditional rule, and the return value.

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 100% parameter description coverage, so baseline is 3. The description goes further by explaining when the list field can be omitted, a detail not derivable from the schema alone, making it genuinely additive.

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 the specific verb and resource: 'Create a task.' It also adds creation-specific details (optional list, returned uid), which clearly differentiate it from update_task, complete_task, and delete_task among the siblings.

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

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

It gives an explicit condition for when the list parameter may be omitted: when the account has one task list or NEXTCLOUD_DEFAULT_TASK_LIST is set. This is genuinely useful routing/context for invoking the tool, though it does not discuss alternatives since creation is unambiguous.

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

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

Annotations already indicate destructiveHint=true, but the description adds critical detail about subtasks being left orphaned, which is beyond the annotation. This informs the agent about the side effects, which is valuable for decision-making.

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, two sentences, with the key behavioral trait (subtask handling) front-loaded. It is efficient, though it could be slightly more structured with an explicit note on idempotency, but it is not verbose.

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 (delete operation with side effects), the description covers the essential behavior, and the schema covers parameters. However, it does not state what happens when the task has dependencies or if the etag is required for conditional deletes, but these are covered by the schema. The output is not specified, but since there is no output schema, it might be beneficial to mention the return value, but it's not critical.

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

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

Schema coverage is 100%, so each parameter (uid, etag, list) has a description. The tool description does not add additional parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a task permanently, with a specific verb and resource. It also distinguishes itself from update_task and complete_task by emphasizing permanence and the specific behavior regarding subtasks.

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

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

The description implies when to use this tool (when you want permanent deletion), but does not explicitly state when not to use it or mention alternatives like update_task for soft deletion. The sibling list provides context, but the description could explicitly warn against using it for reversible actions.

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 and non-destructive behavior. The description adds meaningful behavioral context by noting the returned task includes its etag and that specifying the list avoids multiple requests. This goes beyond the structured annotations without contradicting them.

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

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

Two concise sentences: the first states the core purpose, the second gives a practical optimization tip. No wasted words and the most important information is front-loaded.

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

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

For a simple read-only tool with full parameter documentation and safe annotations, the description is adequate. It conveys the return includes the etag, which is useful given there is no output schema. It does not cover error cases, but the simplicity of the operation makes that a minor 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?

The schema covers both parameters with descriptions, so the baseline is 3. The description adds extra value by explaining why the optional 'list' parameter matters, tying it to request efficiency rather than just re-listing the schema.

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

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

The description clearly states the operation ('Read one task by uid') and the resource, and highlights the etag. It naturally distinguishes this tool from list_tasks and other siblings by focusing on a single task lookup by identifier.

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: naming the list optimizes the request to one call instead of one per list. It does not explicitly state when not to use the tool or name alternatives, but the context is sufficient for an agent to choose 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: the returned data includes counts and 'completed ones included' are not excluded, which goes beyond what the annotations state.

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

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

Two sentences with no redundancy. The core behavior is front-loaded, and the second sentence provides a practical usage hint without 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 simple read-only tool with one optional parameter and full schema coverage, this is almost complete. It states what is returned, that completed tasks are included, and when to use it. A bit more detail about the output structure would be nice, but the absence of an output schema doesn't create a serious gap here.

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 single optional parameter is fully documented in the schema (100% coverage), so the schema already carries the meaning. The description does not add new semantics about the list parameter, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource ('List the tags in use') and adds precise details: it returns a per-tag task count and includes completed tasks. This clearly distinguishes it from sibling tools like list_tasks and list_task_lists.

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 gives an explicit use case: finding the exact spelling of a tag before filtering list_tasks. While it doesn't enumerate exclusions or compare against sibling tools like list_task_lists, the context is clear enough for an agent to know when this tool is the right choice.

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 that already declare this as read-only, idempotent, and non-destructive, the description adds valuable behavioral context: the returned URI is stable, while display names change on rename and are not unique. This identity semantics is important for correct downstream use and is not expressed in 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?

Two sentences with no wasted words. The primary action is front-loaded, and the follow-up sentence delivers a crucial caveat about URI stability and display names. 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 zero-parameter, read-only listing tool with no output schema, the description covers the essential information: what the tool returns (task lists), the scope (this account), and the key identity caveat (URI stable, display name not unique). Nothing critical is missing for an agent to invoke and use it correctly.

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

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

The tool takes no parameters, so the parameter documentation burden is minimal. The description does not need to explain any inputs, and it even adds value by explaining what the returned URI represents, which supports later parameter usage in other tools.

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: "List the task lists in this account." It clearly identifies what is being listed and scopes it to the account, distinguishing it from sibling tools like list_tasks and list_tags without needing to open the schema.

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

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

The description provides clear context for how the tool's output should be used: "Use the returned 'uri' wherever a tool takes a list." It does not explicitly name exclusions or alternatives, but the guidance about stable URIs versus non-unique display names gives the agent actionable selection and follow-up information.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses non-obvious defaults: completed/cancelled tasks are excluded unless includeCompleted=true, and results are sorted by due date, then priority, then title. It also clarifies that every task list is searched unless one is named. 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 first sentence front-loads the purpose, and subsequent sentences add scope and defaults. There is a minor redundancy: 'earliest deadline first' is repeated as 'sorted by due date' in the final sentence, but the description remains compact and organized.

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 11-parameter tool with no output schema, the description covers the core query behavior, defaults, and sorting. It does not describe the response shape, which would be helpful given no output schema exists, but all essential usage details are present.

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

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

The input schema already documents every parameter (100% coverage), so the baseline is 3. The description adds the default sort order and the 'search every list unless named' scope, but these are minor; it does not go into parameter-specific interactions (e.g., dueAfter/dueBefore semantics 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?

The description opens with a specific action and resource ('List tasks'), names the default scope ('Searches every task list unless one is named'), and states the ordering. This clearly distinguishes it from siblings like list_task_lists (which enumerates task lists) and get_task (a single task).

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 on when to call it: to retrieve tasks, optionally scoped to a named list, with filtering defaults. It does not explicitly mention alternatives like get_task for single-task lookups or list_task_lists for enumerating lists, so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond the annotations: uid and properties are preserved, subtasks are not moved, and parent links only resolve within one list. These are non-obvious consequences that materially affect how an AI agent should plan a move.

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

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

Two sentences with no filler. The core action is first, followed by the critical hierarchy caveat. Every sentence earns its place and the structure is easy to parse.

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

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

Given the simple parameter set, existing annotations, and no output schema, the description covers the important context an agent needs: what is preserved, what is not moved, and how to preserve hierarchy. The return format is not described, but this is minor for a move operation and not necessary 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 100%, so the schema already documents all three parameters. The description's mention of 'another task list' aligns with toList, but it adds no syntax, format, or default details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Move') and resource ('a task to another task list'), and adds a key constraint: the move preserves the task's uid and properties. It is clear and distinct from siblings like update_task or delete_task, though it does not explicitly name alternatives.

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

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

The description provides actionable guidance on how to use the tool correctly: move a parent and its subtasks together to preserve hierarchy, because subtasks are not moved automatically. It does not explicitly state when not to use this tool or name an alternative, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by disclosing what the tool returns: the configured server, user, calendar home, and task lists found. This goes beyond the annotations and helps the agent understand the tool's behavior.

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

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

The description is a single, information-dense sentence. It front-loads the primary purpose (verify connectivity and credentials) and then lists the return contents. 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 zero-parameter connectivity check tool, the description is complete. It explains what the tool does and what it returns. The only minor gap is that it doesn't explicitly state that this is a safe, non-mutating operation, but the annotations cover that. It also doesn't mention potential failure modes (e.g., what happens if credentials are invalid), but that's not essential for a ping tool.

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

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

The tool has zero parameters, so the schema is trivially complete. The description doesn't need to explain parameters. The baseline for 0 params is 4, and the description appropriately focuses on the return value instead.

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

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

The description clearly states the tool's purpose: verify connectivity and credentials against Nextcloud CalDAV. It specifies the resource (Nextcloud CalDAV) and the action (verify), and distinguishes it from sibling tools that list or manipulate tasks. The title 'Check connection' reinforces this.

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

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

The description implies this is a connectivity/credential check tool, which is distinct from the task-management siblings. It doesn't explicitly state when to use it vs alternatives, but the context is clear: use it to verify setup before performing task operations. It could be improved by explicitly saying 'use this to test connectivity before other calls'.

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

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

Annotations already convey mutation, idempotency, and non-destructiveness. The description adds valuable behavioral detail by specifying the exact state transition, including removal of the completion timestamp. It does not cover edge-case behavior, but the annotations reduce the burden.

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

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

The description is a single front-loaded sentence that efficiently conveys the action and its two key effects. There is no filler or redundant content.

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 mutating tool, the description combined with the schema and annotations is complete: required uid, conditional etag, list disambiguation, and exact state effects are all covered. No output schema exists, so return-value details are not required.

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

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

Schema description coverage is 100% and the schema already provides meaningful descriptions for uid, etag, and list. The tool description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Reopen') and resource ('a completed task'), and states the concrete outcome: status NEEDS-ACTION and completion timestamp removed. This clearly distinguishes it from sibling tools like complete_task.

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

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

The intended use is clear: reactivate a task that was previously completed. However, it does not explicitly name alternatives such as update_task or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuinely useful behavior beyond these: only the provided fields are modified, all other fields—including CalDAV-client-written properties—are preserved, null clears a field, and an etag makes the write conditional. This gives an agent a precise mental model of a non-destructive partial update.

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

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

Three sentences with no fluff: the first states the core action, the second explains the partial-update and null-clearing model, and the third covers concurrency. Each sentence earns its place and the most important information is front-loaded.

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

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

For an 18-parameter mutating tool with no output schema, the description covers the critical invocation semantics: partial update, preservation of unknown fields, null clearing, and etag-based concurrency. The main gap is the response shape or error payloads, though the etag sentence already signals the primary failure mode, so the tool remains safely callable.

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?

All 18 parameters have full schema descriptions, so the baseline is 3. The description raises that by adding cross-cutting semantics: partial updates preserve unspecified fields, null is the universal 'clear this field' convention, and etag changes the write semantics from unconditional to conditional. These meanings apply across many parameters and are not obvious from individual schema entries alone.

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 concrete verb, 'Change fields', and a specific resource, 'an existing task', which immediately distinguishes this from create_task, delete_task, and get_task. The second sentence narrows the behavior to partial updates, making the tool's role unmistakable.

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

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

The description clearly frames when this tool is appropriate: updating existing tasks and touching only the fields supplied. It also explains the etag conditional-write behavior, which guides the agent on safe update patterns. It does not explicitly name sibling alternatives like create_task or complete_task or give exclusion criteria, so it stops short of a perfect 5.

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