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

Annotations already signal that this is a non-read-only, non-destructive operation, and the description merely restates the mutation without adding behavioral context. It does not disclose duplicate handling, whether the client must exist, response behavior, or side effects, so it adds no transparency beyond the annotations.

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

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

The description is six words, front-loaded, and contains no filler. Every word contributes to the core action, though its brevity borders on under-specification, which is already penalized in other dimensions.

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

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

For a mutation with five parameters, no output schema, and minimal annotation detail, the description is too thin to be fully actionable. It omits required-field context, expected behavior, and any relationship to client or contact lookup tools, leaving the agent to infer too much.

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 needed to compensate for the five undocumented parameters. 'Add a contact' only loosely maps to the name/role/email/phone properties and 'client' to client_id; it does not explain required fields, formats, or relationships. The added meaning beyond the property names is minimal.

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: 'Add a contact to a client.' The object of the action and the target are clear, and no sibling tool appears to perform exactly this create operation. It stops short of a 5 because it does not explicitly differentiate itself from related tools like clokio_get_project_contacts or clokio_get_client.

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 offers no guidance about when to use this tool versus alternatives. Sibling tools include read-oriented contact/client lookups, but the description does not mention exclusions, prerequisites, or conditions that would determine when this mutation is appropriate.

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

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

Beyond the annotations, the description discloses valuable behavioral details: omitting author_employee_code attributes the comment to the API key owner as 'External System,' and markdown tables are not rendered. These are not inferable from the schema or annotations and help set expectations.

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 deliver the core action, an important default behavior, and formatting guidance with no filler. The essential purpose is front-loaded, and every clause adds value.

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

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

The description covers the action, required parameters, optional attribution, and formatting limitations. It does not describe the return value, but for a simple add-comment mutation this is a minor omission given the tool's simplicity and lack of an 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?

With 0% schema description coverage, the description compensates by explaining author_employee_code's default behavior and body formatting constraints. The id parameter is not explicitly described, but its role as the task identifier is strongly implied by the tool name and required status.

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: 'Add a comment to a task.' This clearly states what the tool does and differentiates it from sibling tools like list_task_comments or update_task without ambiguity.

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

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

The intended use case is clear from the opening phrase 'Add a comment to a task.' It also provides practical guidance on author attribution and body formatting, giving context for correct usage. It does not explicitly name alternatives or exclusions, but none are needed for this straightforward action.

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

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

Annotations already indicate this is a mutating but non-destructive operation. The description adds one useful behavioral fact—that circular dependencies are rejected—but does not disclose other side effects, idempotency, or failure 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 two short sentences with no filler. The core operation is front-loaded, and the caveat about circular dependencies 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?

With three parameters, no output schema, and low schema description coverage, the description leaves important semantics unresolved—particularly the directionality of the dependency and the optional 'type' field. An agent could guess the intent but may not reliably construct a correct call in all cases.

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

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

Schema description coverage is only 33%, with only 'id' described. The tool description does not clarify the meaning of 'depends_on_task_id' or the 'type' enum, especially the difference between 'blocks' and 'waiting_on' or what happens when 'type' is omitted.

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: 'Add a dependency between two tasks.' This makes the tool's purpose immediately clear and distinguishes it from sibling tools such as list_task_dependencies or create_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 provides no guidance on when to use this tool versus alternatives, and it does not mention any related sibling tools. 'Circular dependencies are rejected' is a validation constraint, not a usage guideline.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful default-date behavior, but does not disclose what the returned attendance data contains or whether it covers all employees; with no output schema, some behavioral detail is missing.

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

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

A single 10-word sentence that front-loads the resource and scope, states the format, and adds the default. 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?

The tool is simple and read-only, and the optional date plus default is fully described. However, with no output schema, the description does not clarify the shape or scope of the returned attendance data, and the presence of attendance_for_employee/range/summary siblings makes this ambiguity more noticeable.

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

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

The schema already documents the single parameter's type and format, and the description reinforces the YYYY-MM-DD format while adding the default-to-today behavior. This goes beyond the schema, so the parameter semantics are well supported.

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 states the resource (attendance) and scope (single date) with format and default. It is clear enough to identify the tool as a daily attendance read, but lacks an explicit verb such as 'get' or 'list' and does not name sibling tools to differentiate, 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?

The phrase 'single date' implies it is for one-day attendance queries, and the default-to-today gives a concrete use case. However, it does not explicitly direct the agent to attendance_range for multiple dates or to attendance_for_employee for employee-specific data, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral hint that results can be scoped to a date range, but it does not disclose the return shape, pagination, or what an unscoped query returns.

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

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

The description is extremely concise and front-loaded: the core subject comes first and the optional modifier second. Every word earns its place with 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?

Given a crowded set of attendance sibling tools and no output schema, this description is too sparse. It does not explain what 'attendance' contains, how it differs from attendance_range/daily/summary, or what an agent should expect when no date range is provided.

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

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

Schema coverage is 67% and the schema already documents the date format for start_date and end_date. The description adds that the dates form an optional range and that the target is a single employee, but it does not clarify pairing requirements, inclusivity, or constraints on employee_code beyond the schema pattern.

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 identifies the resource (one employee's attendance) and the optional date-range scoping, so an agent understands the basic purpose. It lacks an explicit verb and does not distinguish this tool from sibling attendance tools, but it is not merely a tautology because it adds the date-range option.

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

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

No guidance is provided about when to use this tool versus alternatives like clokio_attendance_daily, clokio_attendance_range, or clokio_attendance_summary. The only usable context is the phrase 'One employee's attendance', which hints at scope but offers no exclusions or decision rules.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the 31-day range limit as useful behavioral context, but it does not disclose what the returned attendance data contains or whether any additional access constraints exist.

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, compact sentence that front-loads the core purpose and immediately follows it with the critical 31-day limit. There is no filler, repetition, or irrelevant detail.

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

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

For a simple read-only tool with two required date parameters, no nested objects, and annotations covering safety, this is mostly sufficient. The main gaps are the absence of an output description and the lack of explicit routing among the attendance-related sibling tools.

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?

Both parameters are already documented in the schema with YYYY-MM-DD format, so the schema contributes the baseline. The description adds meaningful semantic information by imposing a maximum span of 31 days between start_date and end_date, which is 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 clearly identifies the resource ('Attendance') and its scope ('date range') with an explicit 31-day cap, so an agent can tell this is an attendance-range query. However, it lacks a direct verb like 'get/list' and does not explicitly distinguish itself from siblings such as clokio_attendance_daily or clokio_attendance_summary.

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 'max 31 days' constraint gives a clear boundary for valid usage, but it does not state when to choose this tool over alternatives like clokio_attendance_daily, clokio_attendance_summary, or clokio_attendance_for_employee. The intended use is implied by the date-range phrasing rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds little behavioral detail beyond restating the resource. It does not disclose what the summary contains, whether the month is required or defaults to the current month, or how the data is aggregated.

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 has no filler, but it is so terse that it under-specifies the tool. A few more words could materially improve clarity without adding 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?

With no output schemahol and sibling tools covering daily, range, and per-employee attendance, the description should clarify what kind of summary is returned and for whom. It does not, so an agent would still have to guess at invocation behavior.

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

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

The schema has 100% description coverage for the only parameter, month, with format YYYY-MM. The description merely aligns with 'monthly' and does not add any detail about optionality or default behavior, so it earns the baseline score.

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

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

The description is a noun phrase, 'Monthly attendance summary,' which indicates the resource and time granularity but lacks a verb and an explicit scope. It distinguishes from attendance_daily and attendance_range via 'monthly,' but does not clarify whether it summarizes all employees or a single employee, leaving ambiguity against attendance_for_employee.

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

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

No guidance is given about when to choose this tool over its siblings. The word 'monthly' only implies a time period; there are no explicit when-to-use conditions, exclusions, or alternative recommendations.

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

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

The annotations already indicate this is a mutating but non-destructive operation. The description adds no behavioral context beyond restating the state transition, such as whether an active break is required, what happens if none exists, or what the response indicates.

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

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

The description is a single, front-loaded sentence with no filler or redundant phrasing. It is efficient for what it conveys, but that efficiency comes at the cost of meaningful guidance.

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

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

With no output schema, no parameter documentation, and no usage context, the description is too thin to support confident invocation. An agent is left to assume prerequisites, the meaning of pin, and the success/failure behavior on its own.

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

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

Schema description coverage is 0%, and the description does not compensate for it. 'End a break for an employee' weakly implies that employee_code identifies the employee, but the optional pin parameter is completely unexplained, leaving its role ambiguous.

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 ('End') and identifies the resource ('a break for an employee'), so the core action is unambiguous. It clearly contrasts with the sibling clokio_break_start, though it does not explicitly name or differentiate itself from 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?

There is no guidance on when to use this tool versus clokio_break_start or clokio_clock_out, and no conditions such as 'employee must currently be on an active break.' The only implied usage is that a break must already have been started, which is not stated.

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

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

Annotations already indicate a non-read, non-destructive operation. The description adds no behavioral detail beyond the tautological 'start' – it does not mention side effects like creating a time entry, requirements like an active shift, or failure conditions if a break is already running.

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

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

A single concise sentence that states the action directly with no filler. The core verb and object are front-loaded, which makes it 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?

The description is insufficient for an agent to invoke this tool correctly. It does not explain the relationship to clokio_clock_in or clokio_break_end, does not specify whether pin is required for all calls, and provides no information about expected return values or failure modes. Given the 0% schema coverage and no output schema, the description needed to carry much more context.

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

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

Schema description coverage is 0% for both 'pin' and 'employee_code'. The description only mentions 'employee', which loosely maps to employee_code, but leaves 'pin' completely unexplained. Since the schema provides no descriptions, the tool description was required to compensate and does not.

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

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

The description 'Start a break for an employee' uses a specific verb and resource, clearly distinguishing this from sibling tools like clokio_break_end ('end') and clock_in/clock_out. An agent can immediately recognize the action and target.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., employee must be clocked in), and no note about pairing with clokio_break_end. The lone sentence states the action but gives no selection criteria or timing context.

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

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

Annotations only state readOnlyHint=false, confirming a mutation, but the description adds two important behavioral constraints: PIN may be required depending on org configuration, and timestamps are clamped to ±10 minutes of server time. These go beyond the annotations and help the agent predict system behavior, though return values and side effects are not disclosed.

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

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

The description is two concise sentences with no fluff. The primary action is front-loaded, and the secondary constraints (PIN and timestamp clamping) follow immediately. Every clause contributes meaning, demonstrating exemplary economy.

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

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

The tool is simple with three parameters and no output schema. The description covers the PIN condition and timestamp clamping, but omits any explanation of what a successful clock-in returns and does not address location_id. For a mutation tool with minimal annotations, this is a moderate level of completeness – usable but with clear gaps that an agent might need to infer.

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

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

Schema description coverage is 0%, so the description must compensate by explaining each parameter. It clarifies that pin may be required, which is useful, but it says nothing about location_id or the expected format of employee_code. The description only partially addresses the parameter semantics, leaving significant gaps.

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

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

The description states a specific verb and resource – 'Clock an employee in' – which clearly distinguishes it from sibling actions like clokio_clock_out and clokio_break_start. The action is unambiguous and the resource is explicit, leaving no room for misinterpretation.

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 implies when to use this tool (clocking an employee in) and notes a precondition (PIN may be required), but does not explicitly list alternatives or exclusions. The context is clear enough that an agent can route correctly without confusion, though explicit alternatives would be stronger.

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 restates the basic mutation already implied by readOnlyHint=false and adds no behavioral context such as what time is recorded, whether the employee must have an open shift, or what failure cases exist. It does not contradict the annotations, but it also does not go beyond 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 a single sentence with no filler, front-loading the core action immediately. It is concise and easy to parse, though it sacrifices useful details that could make it more helpful.

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

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

With no output schema and no parameter discussion, the description does not explain how pin is used, what preconditions apply, or what the tool returns. It is enough to identify the tool's purpose but not enough to invoke it correctly and confidently.

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

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

Schema description coverage is 0%, and the description never mentions employee_code or pin. The word 'employee' maps loosely to employee_code, but the optional pin remains unexplained, leaving its role and necessity ambiguous.

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 phrase 'Clock an employee out' identifies a specific action and target, clearly distinguishing it from sibling tools like clokio_clock_in, clokio_break_start, and clokio_break_end. It is direct and unambiguous, though it does not add scope or return details.

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

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

No guidance is given for when to use this tool versus alternatives. It does not mention that the employee should currently be clocked in, nor does it contrast with clock_in or break_end, leaving the agent to infer usage context.

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

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

Discloses behavioral nuances beyond the annotations: reactivation preserves the existing password, pins are 4-6 digits and org-unique, and the pin is only returned at creation time. Given that annotations only provide readOnlyHint=false and destructiveHint=false, the description adds meaningful safety-relevant 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?

Two dense, front-loaded sentences with no filler or redundancy. Every sentence earns its place, and the most important behavioral caveats come early.

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?

Captures the critical reactivation edge case and pin lifecycle, which are essential for correct invocation. However, with no output schema, it does not describe what the response contains beyond the pin, and it leaves unclear what happens if an active employee with the same name or email already exists.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It explains the pin parameter well (format, uniqueness, auto-generation) but says nothing about name, email, phone, or location_id, leaving most parameters underspecified.

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 specific verbs 'create (or reactivate)' and a clear resource, 'an employee.' The reactivation framing distinguishes it from sibling employee-focused tools like clokio_set_employee_status and clokio_lookup_employee.

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 clear context that the tool can be used both for new employees and for reactivating inactive employees, with the important caveat that reactivation does not reset passwords. It does not explicitly name alternatives or say when not to use the tool, but the usage context is clear.

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

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

Annotations provide only readOnlyHint=false and destructiveHint=false, so the description carries most of the behavioral burden. It discloses one genuinely useful behavioral trait: without creator_employee_code, the task defaults to the API key owner. This adds value beyond the annotations. However, it doesn't disclose mutation consequences, required permissions, or what happens on failure, leaving a thin behavioral picture for a mutating tool.

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 purpose is front-loaded, and the critical employee_code gotcha follows immediately. It earns its length and is easy to scan.

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 9 parameters, 33% schema coverage, and no output schema, the description should fill more gaps. It addresses the attribution gotcha but says nothing about the response/return value, other parameter semantics, or expected behavior for a create operation. For a tool of this complexity with no output schema, the description leaves significant context 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 only 33% (3 of 9 params documented), so the description must compensate. It adds critical meaning for creator_employee_code and assignee_employee_codes by specifying the employee_code format (e.g., '00080') and that internal IDs are not used. This is important, but it leaves the other undocumented parameters (label_names, project_id semantics, status slug format) unaddressed, so compensation is only partial.

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: 'Create a task in a project.' This is clear and distinguishes it from siblings like clokio_update_task and clokio_delete_task by the create verb. However, it doesn't explicitly name a sibling it is not, though the action itself makes the 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 gives usage guidance on how to correctly attribute the task: use employee_code format for assignees/creator, and set creator_employee_code to attribute to a person rather than the API key owner. This is valuable 'how-to' context. But it provides no when-to-use vs. alternatives guidance (e.g., when to use clokio_update_task or clokio_set_task_assignees), and no exclusions.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds 'This is irreversible,' which meaningfully warns the agent that the action cannot be undone. This goes beyond the annotation's generic destructive flag, though it does not detail possible cascading effects on related resources.

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

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

Two short sentences with zero waste. The core action is front-loaded, and the irreversible consequence earns the second sentence.

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

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

For a one-parameter destructive tool with no output schema, the description and annotations together provide everything the agent needs: what to call, what to pass, and the key consequence. 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?

Schema description coverage is 0%, but the description says 'by id,' clarifying that the single required integer parameter is the target task's identifier. With only one simple parameter, this is sufficient compensation for the missing schema 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 states a specific verb ('Delete'), a resource ('task'), and the selection method ('by id'). It clearly distinguishes this tool from sibling tools like clokio_create_task, clokio_update_task, and clokio_get_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 use case is implied: call this when a task must be removed. However, there is no explicit guidance about when not to use it or which sibling to prefer instead, such as using update_task for modifications or get_task for reads.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no behavioral context beyond stating the resource; it does not mention filtering behavior, output shape, or any special semantics around balances.

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

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

The description is extremely short and front-loaded, but it is under-specified rather than efficiently concise. It reads like a fragment or label, not a tool description that earns its place by clarifying behavior.

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

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

For a tool with no output schema and an undocumented parameter, the description is not complete enough. It leaves the meaning of employee_code, the scope of returned data, and the relationship to sibling tools unresolved.

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 never mentions employee_code. The single parameter is left completely unexplained, forcing the agent to guess whether it is an identifier, a filter, or something else entirely.

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 identifies a clear resource—leave and hour balances—and the 'get_' prefix supplies the verb, so an agent can tell this is a read operation for balances. It does not explicitly distinguish itself from sibling tools like attendance summaries, but the resource is specific enough for basic selection.

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 instead of related tools such as clokio_attendance_summary or clokio_get_employee_task_stats. It also does not explain whether the optional employee_code is needed for a specific employee or what happens when it is omitted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds no behavioral context beyond the operation itself, but it also does not contradict the annotations, which keeps this at an acceptable baseline.

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 short sentence with no filler. It front-loads the verb and resource and every word contributes to the meaning.

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

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

For a one-parameter read-only lookup with a self-explanatory id parameter, the description is sufficient to select and invoke the tool. A return-value or not-found note would have been useful, but the absence of an output schema and the simplicity of the operation keep this from being a real 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%, and the description only says 'by id' without identifying or elaborating on the client_id parameter. The schema already names client_id as an integer, so the description adds essentially no meaning beyond the structured data.

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

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

The description uses a specific verb 'Get' with the resource 'client' and the access path 'by id'. This is unambiguous and distinguishes the operation from sibling list/create tools such as clokio_add_client_contact and clokio_list_projects.

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: call this when you need a single client record and already have its client_id. There are no sibling get-client alternatives to exclude, so the lack of an explicit alternative comparison is not a significant gap.

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 declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely useful behavior beyond that: the stale_days threshold with default and range, and the multi-assignee double-counting rule. 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?

Three short sentences, front-loaded with the tool's result, with no filler. The counting caveat is a compact one-liner and every sentence adds value.

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

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

For a two-parameter, read-only stats tool, the description covers the returned count categories, the stale threshold behavior, and a potentially surprising counting rule. It is slightly thin on defining 'past_due' and the exact output shape, but sufficient 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 compensate. It fully explains stale_days (default 7, range 1-365) and the single-employee scope, though it does not explicitly define employee_code as the employee identifier; the required field name makes that inferable.

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?

Opens with a precise noun phrase: 'One employee's open / delayed_from_open / past_due task counts,' specifying both the entity and the exact metrics returned. This clearly distinguishes it from sibling tools like clokio_list_tasks (raw task records) and clokio_attendance_for_employee (attendance data).

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 single-employee, aggregate-count usage but never states when to prefer this over list_tasks, get_task, or attendance siblings, nor does it give exclusions. An agent must infer that this is for task-status statistics rather than raw task details.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds no behavioral context beyond that. It does not mention whether it returns a list, the shape of the contacts, or behavior for invalid or missing projects, so no extra transparency is provided.

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 short sentence that front-loads the core resource with no filler. It earns its place but is slightly under-specified, reading more like a fragment than a full instruction.

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 required parameter, the description gives the essential resource and the relevant project link. However, with no output schema, it leaves the return shape and usage context implicit, making it minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only implies that project_id identifies a project. It does not explicitly state that project_id is the project whose client's contacts should be fetched, nor does it explain where valid project IDs come from.

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 the resource ('contacts for a project's client') and pairs with the verb 'get' in the tool name, making the core action clear. It is distinguishable from siblings like clokio_get_client and clokio_add_client_contact, though it does not explicitly say 'list' or 'retrieve'.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention that one should use this when needing client contacts via a project, or point to a sibling like clokio_get_client for client details.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: results are ordered by sort order, and an API key sees only PUBLIC fields. This visibility restriction is a genuinely important operational caveat. No contradiction with annotations.

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

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

Two short sentences carry all the essential information with no filler. The sort-order behavior is front-loaded, and the visibility restriction is stated separately and clearly. 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 simple read-only tool with one required integer parameter, the description and annotations are sufficient for an agent to invoke it correctly: it knows the resource, the sorting behavior, the visibility restriction, and that the operation is non-destructive. No output schema exists, but the description does not need to enumerate return fields for a basic getter.

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

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

Schema description coverage is 0%, and the description does not compensate by explaining the project_id parameter's meaning, format, or constraints. The parameter name is self-explanatory, but the description itself adds no parameter-level semantics beyond implying that the fields belong to a project.

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 identifies the resource as 'a project's custom-field definitions' and adds the useful detail that they are returned 'in sort order.' It does not state an explicit verb like 'retrieves,' but the tool name supplies 'get,' and the phrasing is specific enough to distinguish this from sibling tools such as get_project_statuses and get_project_contacts.

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

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

No guidance is given for when to use this tool versus alternatives. The description does not mention sibling tools, exclusions, or conditions under which a different tool would be more appropriate, leaving the agent to infer usage solely from the resource name.

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

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

The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that the result is an ordered set of statuses a task may become, which is helpful given no output schema, but it does not explain what 'resolved' means, how ordering is determined, or any error/auth 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, tightly worded sentence with the core meaning front-loaded and a useful parenthetical clarification. Every word earns its place and there is no redundant filler.

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

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

For a simple read-only tool with one required parameter and no output schema, the description gives enough context to understand what will be returned: an ordered, project-specific set of statuses. It could be more explicit about what 'resolved' means and how statuses are represented, but the combination of annotations, schema, and description is largely 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?

The only parameter, project_id, is self-explanatory from its name and integer type, and the description's 'A project's...' wording ties it to the parameter. However, schema description coverage is 0% and the description adds no format, constraints, or examples beyond the schema, so it provides no additional parameter semantics.

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 identifies a project-scoped, ordered set of possible task statuses, and the parenthetical explains what the set represents. It distinguishes this from the global clokio_list_task_statuses sibling by emphasizing 'project's' and 'in this project'. However, it lacks an explicit verb like 'returns' and uses the somewhat jargon-y term 'resolved', 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?

The project-scoped wording implies this tool is for statuses specific to a project rather than a global status list, which is a useful signal next to clokio_list_task_statuses. But the description never explicitly names an alternative or states when not to use this tool, so the usage guidance is only implied.

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 mark it readOnly and non-destructive, so the description does not need to restate safety. It adds some context by listing the returned detail fields, but it does not disclose behavior for missing/invalid IDs, response envelope, or error handling.

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, front-loaded with the action and resource, and the parenthetical list of returned fields is compact. 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?

For a simple one-parameter read operation with readOnly/destructive annotations, the description is mostly sufficient: it names the resource, the lookup key, and the returned fields. It could be more complete with a note on not-found behavior, but nothing essential to invoking the tool 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?

The only parameter, id, is documented by schema as a required integer, but schema description coverage is 0%. The description adds little beyond the word 'by id'; it does not explain the ID's source, format, or how to obtain it.

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

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

The description uses a specific verb ('Get'), a clear resource ('one task'), and a selection criterion ('by id'), and it enumerates the returned detail fields. This makes it easy to distinguish from sibling tools like clokio_list_tasks, clokio_create_task, and clokio_update_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 implies the tool is for retrieving a single task by ID but does not state when to choose it over alternatives (e.g., clokio_list_tasks for multiple tasks or clokio_get_task_activity for activity). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description simply restates that this is a read operation and adds no further behavioral context such as return format, ordering, or what events the audit trail includes. It does not contradict the annotations but also does not enrich 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?

One clean sentence with no filler, front-loading the operation and target. It is immediately scannable and appropriately sized for the tool's simplicity.

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, single-parameter tool, the description is minimally adequate. However, with no output schema, it does not describe what the activity log response contains, and it stops short of explicitly binding id to the task. The low complexity lowers the bar, but a sentence about the returned audit entries would improve completeness.

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

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

The schema has a single 'id' integer with 0% description coverage. The description refers to 'a task' but never explicitly states that the id parameter is the task ID or any constraints. While this is strongly implied in a one-parameter tool, the description does not compensate for the missing schema documentation.

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

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

The description states a specific verb ('Get') and resource ('activity log (audit trail)') with a clear target ('for a task'). This distinguishes it from sibling tools like clokio_get_task, which retrieves task details rather than the audit trail.

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

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

No guidance is given on when to use this tool versus alternatives such as clokio_get_task or clokio_list_task_comments. The purpose is implied by the description, but there are no explicit exclusion criteria or alternative selection rules.

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 mark the call read-only, and the description adds meaningful behavioral context: it returns only non-PII fields by default and only includes email when the employees:pii scope is held. This clarifies data-minimization behavior beyond the readOnlyHint and destructiveHint flags.

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

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

Three concise sentences front-load the action and then provide the most decision-relevant details: returned fields, stable ID semantics, and the PII scope requirement. There is no filler or repetition of schema 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 read-only list operation with no output schema, the description covers the return format and access prerequisites well. It does not describe pagination behavior or defaults even though a page parameter exists, and 'non-PII fields' stays vague, leaving minor ambiguity.

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 search parameter is already described in the schema as 'Name filter', but the page parameter has no description in either the schema or the tool description. The tool description adds no parameter-level meaning and only partially compensates for the schema 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?

The description opens with a specific verb and resource ('List employees') and adds valuable detail about the returned identifier (employee_code) and its role as the stable ID for other operations. It is clear, though it does not explicitly contrast itself with clokio_lookup_employee or other employee-related 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 implies when to use the tool (to obtain a list of employees and stable employee codes, e.g. for assignees), but it never states when to prefer clokio_lookup_employee or when not to use this tool. The email scope caveat provides useful access context but not tool-selection guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral detail—it merely restates the operation ('List') without mentioning any specifics such as whether the response is paginated, includes all locations, or any other traits. With annotations present, this description contributes no extra transparency beyond what is already declared.

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

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

The description is a single, concise sentence with no extraneous words. It front-loads the action and resource, making it instantly scannable. Every word earns its place.

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

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

For a tool with no parameters, no output schema, and a simple list operation, the description fully covers what an agent needs to know. There is no missing information that would prevent correct invocation. The tool is as simple as it gets, and the description is complete for its complexity level.

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

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

The tool has zero parameters, so the description does not need to explain any. According to the rules, a zero-parameter tool receives a baseline of 4 for this dimension. The description is consistent and does not omit any parameter information.

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

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

The description clearly states a specific verb ('List') and a distinct resource ('locations'). It is unambiguous and easily differentiated from sibling list tools like list_projects or list_employees, which target different entities. The purpose is immediately obvious.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. Usage is implied—one would call it to get the organisation's locations—but there is no mention of alternative tools or conditions that might call for a different approach. It is adequate but relies on inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds the useful behavioral detail that the search term applies to name or client, but it does not disclose pagination, ordering, or output shape beyond what the name implies.

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

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

A single sentence that is front-loaded with the core action and includes the optional filter behavior. There is no wasted wording or redundant restatement of the tool name.

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

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

For a read-only, zero-required-parameter list tool, the description covers the essential calling semantics: list all projects or filter by name/client. It does not explain return fields or pagination, but the low complexity and clear name make the description adequate 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 compensate for the single 'search' parameter. It does so by clarifying that the term matches project name or client, which adds real meaning beyond the bare schema type 'string'.

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 projects," and adds the key behavior of optional filtering by name/client. This clearly distinguishes it from sibling list tools like clokio_list_tasks and clokio_list_employees.

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

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

No guidance is given about when to use this tool versus alternatives or any exclusions. The filter semantics are stated, but there is no mention of when another tool should be preferred, such as get_project_statuses or get_project_custom_fields.

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

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

The annotations already disclose readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that, such as ordering, pagination, or response details.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. Every word contributes meaning.

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

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

For a simple, read-only, single-parameter list operation, the description combined with annotations is adequate for an agent to invoke the tool correctly. It does not describe the return shape, but the absence of an output schema makes that a minor gap rather than a blocking one.

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 an integer 'id' with no description, but the tool description clarifies that this id refers to the task whose comments are listed. For a single-parameter tool, this is sufficient semantic grounding.

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 ('List') and a clear resource ('comments on a task'). It is semantically distinct from sibling tools like clokio_add_task_comment, clokio_get_task, and clokio_get_task_activity.

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

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

The description implies when to use the tool: when the agent needs comments belonging to a task. However, it provides no explicit guidance on when not to use it or which sibling alternative might be better for related needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds the dependency-direction context 'blocks / waiting-on', but it does not disclose return shape, pagination, or whether dependencies are incoming, outgoing, or both.

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

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

The description is one short sentence with no filler, and the clarifying parenthetical earns its place. It is fully front-loaded.

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

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

For a simple read-only list operation with one required integer parameter, the description plus annotations are largely sufficient to select and invoke the tool. It would be slightly more complete if it stated the output shape or dependency direction explicitly, but nothing blocks a correct call.

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

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

Schema coverage is 0%, and the single parameter 'id' has no description in the schema. The phrase 'a task's dependencies' implies that id identifies a task, but the description never explicitly states that the integer id is the task ID, leaving some inference required.

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 ('List') and resource ('a task's dependencies'), with the parenthetical '(blocks / waiting-on)' clarifying the dependency types. This distinguishes it from siblings like clokio_get_task, clokio_add_task_dependency, and clokio_list_task_comments.

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

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

The description provides no guidance on when to prefer this over alternatives, no exclusions, and no mention of the sibling clokio_add_task_dependency or clokio_get_task. Usage must be inferred entirely from the tool name.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds return-content detail (names and colors) but discloses no additional behavioral traits such as pagination, auth requirements, or scope. It is consistent with annotations, not contradictory.

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

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

A single sentence that front-loads the verb and resource, with no filler. Every word earns its place.

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

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

For a parameterless read-only list, the description covers the core need: it states the resource and the returned data (names and colors). Without an output schema, a bit more detail—such as whether labels are project-scoped or include archived labels—would make it fully complete, but it is adequate as-is.

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 zero parameters and 100% schema description coverage, so there is nothing for the description to add. Per the baseline for parameterless tools, a 4 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?

Description starts with a specific verb 'List' and a specific resource 'available task labels (tags)', and adds the returned fields 'names and colors'. This clearly separates it from sibling tools like clokio_list_task_statuses and clokio_list_projects, even without naming them.

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 choose this tool over the many sibling list tools, such as clokio_list_task_statuses or clokio_list_projects. The intended context is implied by the resource name, but there is no explicit when/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=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: pagination mechanisms (page vs cursor), timezone handling for date filters, and the fact that each task carries a task_url. This gives the agent a decent sense of what to expect when invoking the tool.

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

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

The description is three sentences with no wasted words. It front-loads the core action ('List tasks'), immediately lists filters, then covers pagination and return attributes. Every sentence earns its place, and the structure is easy to scan.

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 optional-filter list tool with no output schema, the description is reasonably complete: it names all filter dimensions, gives formats and semantics for non-obvious ones, and explains pagination. It does not mention whether filters combine with AND/OR, default page size, or full response shape beyond task_url, but those gaps are not critical given annotations cover safety and the tool is a straightforward read-only list.

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

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

Schema description coverage is only 45%, with descriptions on five of eleven parameters. The description compensates well by clarifying key semantics: status is a slug, assignee is an employee_code, open means 'only open tasks', and date filters use YYYY-MM-DD in org timezone. It also explains page vs cursor pagination. Some parameters (search, label, priority, project_id) are only named, but the description significantly adds meaning over 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 specific verb and resource ('List tasks') and enumerates the supported filters, making the tool's purpose immediately clear. It does not explicitly name a sibling alternative (e.g., clokio_get_task for a single task), but the plural 'tasks' and filter list clearly differentiate it from singular get/update/delete tasks tools.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It simply lists filters and pagination mechanics, leaving the agent to infer that this is the right choice for listing multiple tasks. There is no mention of when not to use it or which sibling tool to prefer for specific needs (e.g., a single task, comments, or activity).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by specifying that the tool returns status slugs with an is_open flag and that the vocabulary is organisation-wide including project-specific slugs, which goes beyond the annotation-only signal.

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 first sentence states the resource and data shape, and the second provides the intended usage context. It is front-loaded and every word earns its place.

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

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

For a zero-parameter read-only lookup, the description is largely complete: it states what data is returned (status slugs with is_open, including project-specific slugs) and why it should be used. It does not define is_open semantics or enumerate slugs, but the low complexity does not demand more.

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 reinforces that the tool is a lookup with no inputs and explains what the returned vocabulary contains, which is enough for a parameterless tool.

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 resource (the organisation-wide task-status vocabulary) and a precise use (discovering valid status slugs before creating/updating a task). It also clarifies scope by noting it includes project-specific slugs, which helps distinguish it from a per-project status tool.

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

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

The description explicitly tells the agent when to use the tool: before creating or updating a task, to discover valid status slugs. It does not explicitly name alternatives or state when not to use it, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the filtering capability, but this is already captured in the schema. There is no additional behavioral context like pagination, response format, or default limits. Since annotations cover safety, a 3 is appropriate – the description adds minimal value beyond the annotations.

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

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

The description is a single, concise sentence with no filler words. It communicates the core purpose and key parameters immediately. Every word earns its place, and the filtering capability is front-loaded after the main action. This is an excellent example of brevity.

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

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

For a simple read-only list tool with all parameters optional and no output schema, the description is adequate. It conveys the action, the resource, and the available filters. The absence of details like default date range behavior or return format is a minor gap, but given the low complexity and the annotations covering safety, the description is largely complete. A 4 is appropriate.

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

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

Schema description coverage is 67% (two of three parameters have descriptions). The description explicitly mentions 'employee_code and date range,' which maps to the start_date and end_date parameters, giving some semantic context. However, it does not add detail beyond the schema, and the employee_code parameter lacks a schema description but is named in the tool description. With coverage above 50%, the baseline of 3 is correct; the description partially compensates for the missing employee_code schema description.

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

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

The description states a specific verb and resource: 'List time-tracking entries.' It clearly identifies the operation and the entity. It does not explicitly differentiate itself from sibling list tools, but the resource type is distinct enough that it stands on its own. A 4 is appropriate because it lacks explicit distinction from other list-type tools.

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

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

The description implies usage context through the mention of filtering by employee_code and date range, but it gives no explicit guidance on when to use this tool versus alternatives like attendance tools or project list tools. There are no exclusions or alternative recommendations. The usage is clear from the resource type, but not explicitly stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that it 'resolves their employee_code', which is useful. It does not mention edge cases (e.g., what if no match or multiple matches), but given the annotations cover safety, this is acceptable. A slightly richer description of behavior would earn a 4.

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 waste. The first sentence states the action and outcome, the second gives usage context. No repetition or filler. The key 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?

The tool has a simple purpose with no output schema. The description clarifies it returns the employee_code, which is the core need. It doesn't cover error handling or multiple results, but for a lookup tool this is not critical. Given the simplicity and annotations, it is nearly complete; a 5 would require explicit return structure or error semantics.

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 clarifies that the parameters are 'by name or email' – meaning either can be used as a search key. However, it does not specify whether both are allowed simultaneously, which takes precedence, or any format requirements. This gives a baseline of 3 for adding some meaning beyond the schema.

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

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

The description clearly states a specific verb ('Look up'), resource ('an employee'), and outcome ('resolve their employee_code'). It distinguishes itself from siblings like clokio_list_employees and clokio_attendance_for_employee by specifying the purpose is to resolve a code from a name/email, not to list or fetch attendance.

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 explicit guidance: 'Use this before assigning a task when you only know the person's name.' This clearly states when to use it. It does not explicitly mention alternatives or when not to use, but the scenario is specific enough. Could be improved by naming a sibling like clokio_list_employees as an alternative for other cases.

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 record that this is a mutating but non-destructive operation, and the description adds no behavioral context beyond that. It does not mention side effects (e.g., whether 'resign' is permanent, whether status changes affect attendance or time entry), required permissions, or response 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?

A single sentence with the action and key values front-loaded; no filler or repetition. It is appropriately sized for a two-parameter tool.

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

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

The schema is sufficient for constructing a valid call, but the tool lacks output schema and behavioral/side-effect context, and the description gives no hint about how the status change is reflected. Combined with missing usage guidance, it is minimally viable rather than 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?

With 0% schema description coverage, the description needed to explain the parameters, but it only restates the status enum and gives no extra meaning for employee_code (pattern, source, format). The enum values are already present in the input schema, so the description adds little beyond 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 action ('Set') and resource (

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

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

No guidance on when to use this tool versus alternatives, no prerequisites such as obtaining employee_code via lookup_employee/list_employees, and no exclusions. The intended use is only implied by the name and phrasing.

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 mark this as a non-read-only, non-destructive operation, and the description adds valuable behavioral detail beyond that: 'add' appends, 'replace' overwrites, 'remove' removes, and assignees are employee codes. This clarifies the exact mutating behavior and the format of the values, which the 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 two sentences with no filler. The primary purpose is front-loaded, followed immediately by compact mode semantics and an example format for employee codes. Every sentence earns its place.

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

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

For a simple setter with three parameters and no output schema, the description covers the core behavior, mode differences, and value format. It does not discuss error handling or authorization, but those are not critical for this tool's straightforward usage, and the schema covers required parameters and the mode default.

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

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

Schema description coverage is only 33%, so the description must compensate. It does explain the meaning of 'mode' and the format of 'employee_codes', but it does not directly describe the 'id' parameter beyond the implicit 'a task's assignees' context. The mode semantics mirror the enum values, adding some clarification but not full 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 uses a specific verb and resource: 'Set a task's assignees,' combined with mode semantics (add/replace/remove) that clearly convey the operation. It does not explicitly differentiate from sibling tools like clokio_update_task, but the purpose is unambiguous from the wording.

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

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

The description implies when to use the tool—whenever a task's assignees need to be modified—and explains the three modes. It does not explicitly mention alternatives or exclusions, but the mode definitions provide enough contextual guidance 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?

Annotations already mark the tool as non-read-only and non-destructive, so the description does not need to restate that. It adds useful behavior about API-key visibility and field_key identification, but it does not disclose overwrite/append semantics for array values or error behavior.

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

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

Two sentences with no filler; the core action is front-loaded and the critical caveats are delivered immediately after. Every sentence adds value.

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

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

For a simple three-parameter setter with annotation-covered safety and schema-typed parameters, the description gives enough to call it correctly. It lacks explicit return/error details, but no output schema exists and those are not essential for 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?

With 0% schema description coverage, the description must compensate, and it partially does by clarifying that field_key is the identifier and API keys see only public fields. However, it does not explicitly state that id is the task ID or explain how value should be interpreted.

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 ('Set one custom field value on a task') with a clear resource and scope. The distinction 'identified by field_key (never field_id)' and the API-key visibility caveat separate it from broader task update tools and give an exact purpose.

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

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

It advises that API keys see only PUBLIC fields, which tells an agent whether this tool is usable for the intended field, and it explicitly says to use field_key rather than field_id. It does not name sibling alternatives or give a when-not-to-use statement, 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 indicate this is a mutating operation (readOnlyHint=false, destructiveHint=false). The description adds value by clarifying patch behavior rather than full replacement. Still, it does not disclose response behavior, error handling, or any authorization/validation requirements beyond the schema.

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

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

Two sentences with no wasted words. The core action is front-loaded, followed immediately by the most important behavioral nuance (patch semantics) and a compact list of supported fields.

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 straightforward update tool, the description covers the essential behavior and field scope. The id requirement is clear from the schema, and no output schema exists so return-value documentation is not expected. A brief note about which siblings handle unsupported fields would make it fully complete, but nothing critical is missing for a correct call.

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

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

Schema description coverage is only 33%, so the description must compensate for undocumented parameters. It merely repeats the field names (status/priority/title/description/due_date) without adding meaning; the useful partial-update note is parameter-level but does not clarify individual parameter formats or allowed values beyond what the schema already provides for due_date and priority.

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

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

The description uses a specific verb and resource ('Update a task') and enumerates exactly which fields are supported (status, priority, title, description, due_date), which clearly differentiates it from siblings like create_task, delete_task, and the more specialized set_task_assignees/set_task_custom_field.

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

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

The description conveys partial-update semantics ('Only the fields you pass are changed') and lists supported fields, which implies assignees and custom fields are handled elsewhere. However, it never explicitly directs the agent to alternatives such as set_task_assignees or set_task_custom_field, or states when this tool should be avoided.

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