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

The annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds no additional behavioral context. It does not explain what happens if the user is already in the group, whether workspace_id is required, or any side effects. The description does not contradict annotations but adds minimal value 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 extremely short, but it is under-specified rather than concise. It lacks structure and fails to convey any useful information beyond the title. Every sentence should earn its place, but this single vague sentence does not.

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

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

There is no output schema, and the description does not mention return values or expected behavior. Given the existence of sibling tools, the description should clarify its specific role, but it does not. The tool is simple, yet the description leaves out essential context for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter having a description. The tool description itself adds no semantic meaning beyond the schema, but since the schema already documents all parameters, the baseline of 3 is appropriate. No additional parameter relationships or constraints are explained.

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

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

The description 'Puts someone into a team' is vague and informal. It does not explicitly state that it adds a user to a group, uses the term 'team' instead of 'group', and fails to distinguish from sibling tools like remove_user_from_group or update_user_group. The title is clearer than the description.

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 on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context such as requiring existing user and group IDs. The description is purely a vague action without any 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the meaningful behavioral constraint that the tool respects read-only mode and the workspace lock. This tells the agent that mutation attempts may be blocked even though the schema allows POST/PUT/DELETE. It does not disclose auth, rate limits, or response format, but these are less critical given the read-only annotation.

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

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

The description is three short sentences, front-loaded with purpose, and contains no filler. Each sentence contributes either scope, routing guidance, or a constraint, making it easy to parse quickly.

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

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

For a deliberately generic raw API tool, the description covers purpose, usage conditions, path conventions, host selection, and behavioral constraints. It does not describe expected response format, but no output schema is present and the raw request nature makes it somewhat inferable; a bit more detail on return handling would have made it fully complete.

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

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

Schema coverage is 100%, and the schema already thoroughly describes all five parameters, including path examples and the meaning of the surface enum. The description's path and surface clarifications largely restate schema information, so it adds no significant parameter-level meaning beyond what is already structured.

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 this as a catch-all for any Clockify endpoint that lacks a dedicated tool, which distinguishes it from the extensive list of sibling tools. It also gives concrete framing around API-relative paths and host surfaces, making the tool's scope and resource type unambiguous.

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

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

The phrase 'any Clockify endpoint that has no dedicated tool' is an explicit when-to-use instruction, directly steering the agent away from sibling tools that cover specific endpoints. It also adds routing guidance for choosing the reports or time-off surface, which is actionable 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?

The annotation readOnlyHint=false already indicates a mutation, and the description is consistent with that. It adds the workspace scope, but does not disclose any additional behavioral traits such as uniqueness constraints, permissions, or side effects. Since annotations cover the basic safety profile, this is acceptable but not enriched.

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 no filler. It is appropriately concise for a simple create operation and does not waste tokens or introduce unnecessary detail.

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

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

For a simple 4-parameter create tool, the description is minimally viable: it clearly states the action and resource. However, it lacks usage guidance, parameter elaboration for half the parameters, and any mention of return value or potential errors. The schema and annotations fill some gaps, but the description remains thin.

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

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

The schema describes only 'name' and 'workspace_id' (50% coverage), and the description does not compensate for the undocumented 'note' and 'address' parameters. The agent receives no semantic guidance for two of four parameters, and the description adds nothing beyond what the schema already provides.

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

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

The description 'Adds a client to the workspace' uses a specific verb (adds) and clearly identifies the resource (client) and scope (workspace). It distinguishes this tool from sibling tools like create_project or create_task, and adds workspace context not present in the tool name or title.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_client, delete_client, or list_clients. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write operation is expected. The description confirms this with 'Records an expense' and adds the paid plan constraint, which is additional behavioral context. However, it does not disclose return behavior, error conditions, or other operational 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 compact and front-loaded with the action. 'Needs a paid plan' is a valuable, non-redundant addition. The first sentence 'Records an expense' is somewhat redundant with the title but still clear and acceptable.

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

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

For a create operation with 7 parameters and no output schema, this description is too minimal. It does not explain what the created expense represents, what a successful response includes, or any required setup beyond the paid plan. It also lacks guidance on how this tool relates to other Clockify expense features.

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

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

The schema already describes 5 of 7 parameters (date, amount, project_id, category_id, workspace_id) with 71% coverage. The description adds no parameter-specific information. Since the schema covers most fields and the two undocumented ones (notes, billable) are self-explanatory, the description does not need to compensate significantly.

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 'Records an expense' with a specific verb and resource, clearly distinguishing it from other Clockify tools such as list_expenses or log_time. The tool's name and title reinforce the same action, making the purpose unambiguous.

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

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

The description implies usage (recording an expense) and adds a prerequisite ('Needs a paid plan'), but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The paid plan requirement is useful context but not a full 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 signal that this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds little beyond restating the action; it does not disclose side effects, permissions, idempotency, or other behavioral traits that would enhance transparency.

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 zero unnecessary words. It conveys the essential purpose efficiently.

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

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

Given the tool's 7 parameters, the schema thoroughly documents each one, mitigating the need for a verbose description. However, the description lacks context on how optional targeting parameters interact (e.g., everyone vs user_ids), which prevents a perfect score. Overall, it is sufficient given the schema richness.

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

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

All 7 parameters have schema descriptions (100% coverage), so the schema carries the semantic load. The description itself adds no parameter-specific details, which aligns with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the verb 'Adds' and the resource 'holiday to the workspace calendar', making the tool's function unmistakable. It also distinguishes itself from sibling tools like clockify_list_holidays and clockify_delete_holiday through its specific create action.

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 when-to-use guidance or mention alternatives. Usage is only implied by the tool's name and the sibling context, which is enough for an obvious create operation but lacks any explicit recommendations or exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description is consistent with a create operation. It adds a small contextual detail ('to the workspace') but does not disclose additional behavioral traits such as permission requirements, duplicate handling, or response format. With annotations covering the basic safety profile, a middle score is appropriate.

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

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

The description is a single, concise sentence that front-loads the core purpose. Every word earns its place, and there is no redundancy. This is an example of efficient writing.

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

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

Given the tool's relative simplicity and the rich schema, the minimal description is acceptable but not complete. It lacks usage guidance, expected return value, and explanation of optional parameters' interplay (e.g., client_id vs client_name). The absence of an output schema increases the need for description detail, so the tool gets a 3 rather than higher.

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

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

The input schema covers 78% of parameters with descriptions, which is reasonably high. The description itself adds no parameter semantics, but the schema already documents fields like name, color, and workspace_id with helpful details. Therefore, the description does not need to compensate, and a baseline score of 3 is fitting.

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 'Adds a project to the workspace' clearly states the action (adds) and resource (project) and scope (workspace). It is specific enough to distinguish from update/delete, though it does not explicitly name alternatives. It earns a 4 for clarity but lacks the extra differentiating detail seen in top-tier descriptions.

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 on when to use this tool versus alternatives like update_project or delete_project. The description does not mention prerequisites, fallback behavior, or when not to use it. This leaves the agent without clear direction.

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-only, non-destructive operation (readOnlyHint=false, destructiveHint=false), and the description adds the workspace scope. However, it does not disclose other behavioral traits such as whether duplicate names are accepted, error handling, or permission requirements. No contradiction with annotations.

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

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

The description is a single, concise sentence that immediately conveys the action and scope. Every word earns its place, with no redundancy or filler.

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

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

For a simple two-parameter create tool with no output schema, the description combined with the schema is largely sufficient. The only minor gap is the lack of information about the return value or any side effects beyond adding a tag.

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 fully documents both parameters with clear descriptions, including the fallback behavior for workspace_id. The tool description itself adds no additional parameter meaning, so a baseline score of 3 is appropriate given the high schema coverage.

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

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

The description uses the specific verb 'adds' and identifies both the resource ('tag') and the scope ('workspace'), making the tool's purpose immediately clear. This distinguishes it from sibling tools like update_tag and delete_tag, which perform different operations on tags.

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 should be used when creating a new tag in the workspace, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives. For a simple create tool, the context is decent but not explicitly differentiated from siblings.

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

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

The description is consistent with the annotations (readOnlyHint: false, destructiveHint: false) and adds the context that the task is created within a project. However, it does not disclose additional behavioral details like response format, required permissions, or side effects, relying mostly on schema and 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 that conveys the essential purpose without unnecessary words 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?

Given the 8-parameter schema and no output schema, the description is minimal but not insufficient. It does not explain optional project_id/project_name relationships or workspace fallback, but the schema provides that. It lacks broader usage context, though annotations help clarify safety.

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 75%, with descriptions for most parameters. The description itself adds no parameter-specific details, so the schema carries the burden. This aligns with the baseline for high schema coverage.

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

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

The description 'Adds a task to a project' clearly identifies the action (adds), the resource (task), and the scope (to a project). It distinguishes this from sibling tools like create_project or create_tag, which target different resources.

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 on when to use this tool versus alternatives such as clockify_update_task or clockify_create_project. There are no explicit conditions, prerequisites, or exclusions.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate that this is a write operation. The phrase 'Adds a team to the workspace' adds minimal context about scope, but it doesn't disclose potential error behavior, idempotency, or permission requirements. The description adds limited 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 sentence with no fluff or repetition. It is front-loaded and efficient, but the use of 'team' instead of 'user group' slightly detracts from precision. Overall, it is concise without being under-specified to the point of uselessness.

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 create tool with two well-documented parameters and no output schema, the description is minimally adequate. It communicates the core action and workspace scope, but it leaves gaps such as what happens if a group with the same name exists, whether admin rights are needed, and how success is reported. Given the tool's simplicity, this is acceptable but not exceptional.

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

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

Schema description coverage is 100% for both parameters ('Group name' and 'Workspace id' with fallback details), so the schema already explains them fully. The description does not add any additional meaning or context for the parameters, resulting in 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 states a specific action ('Adds a team') and target ('workspace'), which aligns with the create_user_group function. However, it uses 'team' instead of 'user group', which could cause slight ambiguity when compared to the tool name and title, though the intent is still clear.

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 like clockify_update_user_group or clockify_add_user_to_group. There is no mention of prerequisites, use cases, or exclusions, leaving the agent without clear direction.

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

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

The description adds context beyond the readOnlyHint and destructiveHint annotations by revealing that it returns nothing when no timer is running. This is a meaningful behavioral detail not present in the annotations. However, it does not mention other potential behaviors like authentication or response structure, which are less critical given the annotations.

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

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

The description is a single, concise sentence that delivers the core purpose and the key edge case (stopped clock) without any filler. Information is front-loaded and every phrase 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 two optional parameters and no output schema, the description covers the necessary information: what it returns (the running timer and elapsed time) and the empty case. Contextual signals (annotations, schema) fill in the rest, making the description complete for an agent to select and invoke correctly.

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

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

The input schema provides complete descriptions for both parameters (user_id and workspace_id), including default behaviors. The tool description adds no additional parameter information, but given 100% schema coverage, the description does not need to compensate. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as returning the currently running timer and its elapsed duration, distinguishing it from sibling tools like clockify_start_timer and clockify_stop_timer. The phrase 'The timer running right now' with 'how long it has been going' is a specific and unambiguous retrieval action.

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

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

Usage is implied but not explicitly stated. The description notes 'Returns nothing when the clock is stopped,' which gives a conditional behavior, but it does not explicitly state when to use this tool over alternatives like clockify_list_time_entries or clockify_get_time_entry. No exclusions or alternative comparisons are 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no extra behavioral context, such as irreversibility, cascading effects, or failure conditions.

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, complete sentence with zero waste. It is front-loaded and immediately readable, exemplifying maximal conciseness.

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 destructive, but the annotation covers that. The schema fully documents all three parameters, including the confirm const. However, the description itself adds no additional context about consequences or required confirmation, making it minimally viable but not enriched.

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

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

Schema coverage is 100%, with clear descriptions for client_id, confirm, and workspace_id. The description does not add any meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description uses the specific verb 'removes' with the resource 'client', clearly stating what the tool does. It distinguishes from sibling tools because it uniquely targets the client entity, not projects, tasks, or tags.

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 like update_client or create_client, nor any exclusions or prerequisites. It is just a bare statement of action with no decision-making 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?

The description simply restates the destructive nature already captured by the annotations (destructiveHint=true). It adds no new behavioral context such as permanence, confirmation requirements, or effects on related data. Given the annotation, the agent knows it's destructive, but the description doesn't enrich that understanding.

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 does not add value beyond the title; it essentially paraphrases 'Delete a holiday.' While concise, it lacks substance and doesn't earn its place, though it is not as bad as a pure tautology.

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 three-parameter delete tool with two required parameters and a confirmation flag, the description is quite sparse. It doesn't mention the need for confirm=true or the optional workspace_id, though these are covered in the schema. The absence of an output schema and any return-value notes leaves the agent guessing, but the tool's simplicity mitigates the gap.

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

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

The input schema has full descriptions for all three parameters, including the confirm requirement and workspace fallback. The description adds no parameter-specific information, so it does not improve on the schema. Baseline of 3 is appropriate since coverage is 100%.

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

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

The description 'Removes a holiday' clearly states the action and resource, making it easy to identify as a delete operation. It distinguishes from sibling tools like clockify_list_holidays and clockify_create_holiday, so the purpose is unambiguous. However, it doesn't mention workspace-specific behavior, which is a minor gap.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as listing holidays first or handling confirmation. There is no mention of prerequisites like needing the holiday_id from list_holidays or that this is the only delete holiday endpoint. The usage is implied by the tool name 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 mark this as destructive, and the description adds the key behavioral constraint that deletion only works on archived projects. It doesn't contradict the destructiveHint, and the note about archiving first provides context that annotations don't cover.

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, front-loaded with the main action, and the second sentence adds essential prerequisite context. No wasted words.

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

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

For a simple delete operation with no output schema, the description covers the essential context: the action, the prerequisite, and the destructive nature is already in annotations. The confirm parameter description in the schema adds the detail about removing time entries, so the overall tool definition is reasonably complete.

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

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

Schema description coverage is 100%, with clear parameter descriptions for project_id, confirm, and workspace_id. The description itself doesn't add extra meaning to the parameters, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Deletes a project' with a specific verb and resource, distinguishing it from sibling project tools like update or create. It also adds the prerequisite that the project must be archived first, which clarifies the intended operation.

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

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

The description provides clear context: 'Clockify only allows this once the project is archived, so archive it first.' This tells the user when the tool can be used, though it doesn't explicitly name alternative tools for archiving. The guidance is implicit but 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 destructiveHint=true and readOnlyHint=false, which covers the safety profile. The description itself adds no behavioral context beyond the bare statement 'Removes a tag.' It does not contradict annotations, but also does not enrich them with additional details like irreversibility or potential side effects.

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 with one short sentence that front-loads the core purpose. There is no redundant wording, but it is arguably under-specified rather than appropriately concise, missing opportunities to add usage context. Still, it is well-structured for a simple deletion 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 tool is low complexity, with a clear schema and annotations covering destructive behavior. However, the description alone does not fully convey the need for confirmation or any consequences. Given that the schema and annotations fill in many gaps, the description is minimally viable but not comprehensive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-specific information, but the schema already explains tag_id, confirm, and workspace_id. The confirm parameter's const true is a safety mechanism that the description does not elaborate on, but the schema covers 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 'Removes a tag' uses a specific verb and resource, clearly distinguishing it from sibling tools like clockify_create_tag and clockify_update_tag. It is unambiguous about the action performed.

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. It does not mention that deletion is permanent, that confirmation is required, or when one might prefer updating instead. No contextual or exclusionary information is given.

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

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

Annotations already signal destructiveHint=true, so the description does not need to repeat that. However, it adds no new behavioral information such as irreversibility, need for confirmation, or cascading effects on time entries or other data. The phrase 'from a project' is a scope qualifier, not a behavioral disclosure. This is consistent with annotations but adds minimal value 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, direct sentence with no filler or redundancy. It is concise and front-loaded, stating the core action immediately. 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 simple destructive operation with full schema coverage and annotations, the description is adequate but not rich. It lacks usage guidelines and behavioral details, but the schema and destructiveHint cover the essential safety and parameter context. It is a minimum viable description with clear gaps.

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

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

All five parameters have descriptions in the input schema, so coverage is 100%. The description does not add any additional meaning to the parameters; it relies entirely on the schema. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the action ('Removes'), the resource ('a task'), and the scope ('from a project'). This distinguishes it from sibling tools like delete_project or delete_time_entry. The title 'Delete a task' reinforces the intent.

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

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

The description gives no guidance on when to use this tool versus alternatives such as update_task or delete_project. No exclusions, prerequisites, or alternative suggestions are provided, leaving the agent to infer usage solely from the name and schema.

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 destructiveHint: true and readOnlyHint: false. The description adds context about permanence and the confirmation requirement, which are useful for understanding the irreversible nature. It does not contradict annotations.

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

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

The description is two short sentences, front-loaded with the core action. No fluff. 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 destructive delete tool with good annotations and full schema coverage, the description covers the essential action and irreversibility. It doesn't mention return values or error handling, but with no output schema that may be acceptable. It could offer more context about workspace fallback behavior, but that is already in the schema.

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

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

Schema covers all parameters with descriptions (100%). The description's mention of confirm: true is redundant with the schema's const/true constraint and description. No new semantic meaning is added beyond the schema.

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

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

The description clearly states the tool's function ('Removes a time entry permanently'), using a specific verb and resource. It distinguishes itself from sibling tools like update_time_entry and get_time_entry.

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 use for permanent deletion but does not explicitly contrast with alternatives or state when not to use it. The 'permanently' wording conveys irreversibility, but no explicit exclusions or alternative tool references are given.

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

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

Annotations already declare destructiveHint=true, and the description repeats this by saying 'Removes.' It adds no additional behavioral context such as irreversibility, effects on related resources, or authentication requirements. The description is essentially a restatement of the title and 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 sentence with no wasted words, and it front-loads the verb 'Removes.' While it is minimal, it is appropriately concise for the simple action, though it could include more detail without losing conciseness.

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 destructive delete operation, the description is incomplete. It does not mention that deletion is permanent, that confirmation is required, or any side effects. The schema and annotations provide some context, but the description itself does not help the agent understand the full impact or prerequisites.

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

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

The input schema provides full descriptions for all three parameters: group_id, confirm (const true), and workspace_id (with fallback logic). The tool description adds no additional parameter meaning, so baseline 3 is appropriate.

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

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

The description states 'Removes a team.' which clearly identifies the action (removes) and the resource (a team, synonymous with user group in Clockify). It distinguishes from sibling tools like create_user_group or update_user_group by focusing on removal, though it doesn't explicitly mention the 'user group' term.

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, any prerequisites, or alternatives. It does not warn about the destructive nature or mention that confirmation is required, leaving the agent without context for appropriate invocation.

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 it is a safe read. The description adds useful context about workspace-wide scope and the paid-plan requirement. However, it omits pagination behavior and potential errors when the plan is not paid, which would be valuable 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?

Two short sentences: the first states the core behavior, the second gives a key constraint. Every word earns its place, and the most important information is front-loaded.

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

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

With 11 parameters, nested objects, pagination, and no output schema, the description is minimal. It captures the essential purpose and paid-plan requirement, but does not mention pagination handling or that filter parameters modify the 'every entry' statement. The schema covers parameter details, making this adequate for basic use but not comprehensive.

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

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

Schema description coverage is 100%, so each parameter has a clear description. The tool description adds the concept of a 'range' (mapping to from/to) and 'across the workspace', but this is minor. Per the rubric, baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool returns every time entry in a date range across the workspace, one row each. This conveys a specific verb and resource and distinguishes it from summary reports by emphasizing row-per-entry granularity. However, it does not explicitly differentiate from the similar sibling clockify_list_time_entries.

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 when-to-use or alternative guidance. 'Needs a paid plan' is a prerequisite, not a usage guideline. It implies a detailed export use case but does not say when to choose this over list_time_entries or summary_report.

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, but the description adds valuable behavior by noting it returns 'candidates' (multiple possible matches) with their ids, implying the need for disambiguation. This goes beyond the annotations and helps the agent anticipate a fuzzy-match result.

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

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

A single sentence that front-loads the purpose and includes the key value proposition. No wasted words, perfectly sized for a simple lookup tool.

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

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

Given the low complexity (3 params, all well-documented), the presence of safety annotations, and the lack of an output schema, the description sufficiently explains the tool's function and result (candidates with ids). It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with detailed explanations for all three parameters (case-insensitive partial match, fallback behavior for workspace_id, include_archived). The description itself adds no further parameter detail, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Looks a project up by name and returns the candidates with their ids.' It also explicitly frames the tool as the 'quickest way from what a person calls a project to what the API needs,' distinguishing it from listing or fetching by ID.

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

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

The description gives clear context for when to use this tool: whenever you need to resolve a human-readable project name into an API id. However, it does not explicitly name alternative tools (e.g., clockify_list_projects, clockify_get_project) or state when not to use it, so it falls short of full explicit guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds behavioral context about resolving to an id and gives an example, but does not disclose behavior for ambiguous matches or no matches. This meets the baseline without exceeding it.

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

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

The description is a single, front-loaded sentence that clearly communicates purpose and use case without extraneous words. It is appropriately sized and structured.

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

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

The tool is simple (2 params, no output schema), and the description effectively explains the core purpose and utility. While return value details and edge-case behavior are not explicitly stated, the description is sufficiently complete for a lookup tool with strong annotations and schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add per-parameter details beyond the schema, but the schema already documents both parameters well. No degradation is needed.

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

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

The description states a specific verb ('resolves') and resource ('person to their Clockify id'), and clarifies the input ('name or an email fragment'). It distinguishes the tool from siblings like clockify_find_project by focusing on person resolution and includes a concrete use-case example.

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

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

The description provides clear context for when to use the tool: when a name or email fragment needs to be mapped to an id, such as for querying time entries. It does not explicitly mention alternatives or exclusions, but the intended usage is evident.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful content context by listing what 'full' includes, but does not disclose other behaviors such as error handling, pagination, or authorization requirements. No contradiction with annotations.

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

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

The description is a single, front-loaded line that conveys the essential purpose and payload. No filler or redundancy; every word adds value.

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

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

For a simple read-only get-by-ID tool with two well-documented parameters, the description sufficiently communicates the expected response scope. It does not mention error cases, but given the simplicity and lack of an output schema, it is complete enough.

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

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

Schema coverage is 100% for both project_id and workspace_id, with descriptions provided. The description adds no extra meaning to the parameters themselves; it only lists what the response contains, which is not parameter-specific. Baseline 3 applies.

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

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

The description clearly identifies the tool as returning a single project with specific components (client, estimates, memberships, hourly rate). It distinguishes from list/find siblings by emphasizing 'one project in full', though it lacks an explicit verb in the description itself; the title provides the verb.

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

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

No explicit guidance on when to use this tool versus alternatives like list_projects or find_project. The phrase 'in full' implies a need for complete project details, but there is no direct comparison or mention of alternate tools.

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

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

Annotations declare a read-only, non-destructive operation. The description only adds the vague 'in full' claim and does not disclose the return structure, error behavior, or any other 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?

Description is a single short phrase with no filler or redundancy. It is front-loaded and immediately states the tool's core behavior, though it may be slightly too terse to be fully informative.

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 minimal description, the agent cannot anticipate what fields a 'full' task includes, how missing IDs are handled, or why optional project identifiers matter. Although the tool is simple, the description leaves important context unstated.

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 describes all four parameters with 100% coverage, so the description doesn't need to restate them. It also adds no extra meaning beyond the schema, keeping the baseline score of 3.

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

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

Title and description identify a single task resource; 'in full' indicates a complete object rather than a list membership. This distinguishes it from list_tasks, though it doesn't explicitly state the lookup key (task_id).

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 list_tasks or other task operations. No prerequisites or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by stating that the response includes resolved project, task, and tags, which goes beyond the annotation information.

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

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

The description is a single concise sentence that effectively communicates the tool's purpose and key behavior. Every word contributes meaning, and it is front-loaded with the core idea.

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 get operation with strong annotations and full schema coverage, the description is complete. It explains the returned content (full entry with resolved project, task, and tags) sufficiently, and no output schema is needed.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description does not add any extra meaning about parameters beyond what the schema already provides.

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

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

The description clearly states that this tool returns a single time entry with full details, including resolved project, task, and tags. This distinguishes it from list_time_entries (which returns multiple entries) and other time-entry operations like update or delete.

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

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

The intended usage is implied: use this when you need one specific time entry with its relationships resolved. However, there is no explicit guidance on when to use this versus alternatives, nor any mention of exclusions or prerequisites.

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 useful content scope (settings, features, currencies, membership) but does not disclose additional behavioral traits such as response format or fallback behavior beyond what the schema provides.

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 11 words, front-loaded with 'Full workspace record' and no filler. Every word contributes meaning, making it highly concise and well-structured.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides a reasonable summary of the return contents. It covers the high-level fields but could be more explicit about fallback behavior or what 'full' includes; however, it is sufficient for basic understanding.

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

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

Schema coverage is 100% and the parameter description in the schema already explains the fallback chain for workspace_id. The tool description adds no additional parameter context, so the baseline score of 3 applies.

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

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

The description clearly states the tool returns a full workspace record including settings, features, currencies, and membership. It distinguishes itself from listing tools by implying a single workspace retrieval, and the title 'Get workspace' reinforces the specific verb 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?

The description implies use when you need a complete workspace record, but it does not explicitly contrast with sibling tools like list_workspaces or provide when-not/alternative guidance. The intended use case is understandable 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 indicate readOnlyHint=false and destructiveHint=false. The description adds value by disclosing that admin rights and a free seat are required, which is crucial behavioral context. It does not detail side effects or response format, but for a simple invite operation this is sufficient.

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

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

Two concise sentences, front-loaded with the action, followed by prerequisites. Every word adds value with no redundancy or clutter.

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

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

For a simple two-parameter mutation with no output schema, the description covers purpose and prerequisites adequately. It omits details about the response or potential errors, but these are not critical for correct invocation. Slightly more detail on what happens after the invitation 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?

Schema description coverage is 100%: both 'email' and 'workspace_id' have descriptive text, including the fallback behavior for workspace_id. The description adds no extra parameter information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Sends' and a clear resource 'workspace invitation', immediately distinguishing it from other user-management tools like clockify_remove_user or clockify_set_user_status. It also mentions the workspace context, making it unambiguous.

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

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

Provides clear context for when to use by stating prerequisites: 'Needs admin rights and a free seat.' This tells the agent whether it can invoke the tool. However, it does not explicitly compare with alternatives or state when not to use, so it falls short of a 5.

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

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

Annotations already mark the operation as read-only and non-destructive. The description adds the paid-plan requirement, which is valuable context, but it does not disclose pagination behavior or the fact that default status may not be limited to pending requests (despite the 'awaiting approval' phrasing). These are minor gaps, but no contradiction exists.

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

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

The description is very short and front-loaded, but the first sentence is a noun phrase that largely restates the title. The second sentence is important and earns its place. Overall, it's efficient but could be slightly more actionable.

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 listing tool with rich parameter schemas, the description is adequate but not complete. It lacks context about the return payload, status values, and when to use all_pages. However, the schema and annotations compensate for most information needs.

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

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

Schema coverage is 83%, so most parameters are described there. The description adds no parameter semantics beyond the schema; it introduces the paid-plan requirement, which is not a parameter. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as listing submitted timesheets awaiting approval, which is specific and distinguishes it from sibling tools like `clockify_submit_approval`. However, it doesn't fully capture that the status parameter allows filtering by approved/rejected statuses, so it slightly understates scope.

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

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

The description provides a prerequisite ('Needs a paid plan') but no guidance on when to use this tool versus alternatives. No similar listing tools are mentioned, and no exclusions are 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?

The annotations already declare readOnlyHint=true, so the safety profile is known. However, the description adds no behavioral context such as pagination behavior, filtering options, or what data is returned, which is a significant gap for a read-only list operation.

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

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

The description is extremely short, but it is under-specified rather than concise. A fragment like 'Clients in the workspace.' does not earn its place because it provides minimal useful information.

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

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

With no output schema and seven optional parameters, the description is inadequate. It does not explain what is returned (e.g., client objects, pagination) or any behavioral details, leaving the agent without essential 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 86%, so most parameters are already explained. The description itself does not add any parameter-level detail, but the baseline of 3 applies because the schema handles the bulk of the semantic load.

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 'Clients in the workspace.' is a noun phrase that restates the resource without specifying an action. It does not clearly state that the tool lists clients, and it fails to distinguish it from sibling list tools like clockify_list_projects or clockify_list_tags.

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 on when to use this tool versus alternatives. The description does not mention any use cases, prerequisites, or exclusions, leaving the agent without context for selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the paid-plan requirement and workspace scope, but does not describe pagination, response shape, or other behavioral details; this is acceptable given the read-only annotation, though not rich.

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

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

Two short sentences, front-loaded with the resource and scope, with no filler. Each sentence adds distinct value: the first defines what the tool returns, and the second provides a crucial prerequisite.

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 comprehensive schema and annotations, the description provides the essential definition and prerequisite. It lacks an explicit return-value description, but the title and tool family make the output obvious; no output schema leaves only a minor gap.

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

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

The input schema is fully self-descriptive with 100% coverage, documenting all five optional parameters and their defaults/limits. The description adds no parameter semantics, but since the schema carries the burden, the baseline score of 3 is appropriate.

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

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

The title 'List custom fields' and description 'Custom fields defined on the workspace' clearly identify the resource (custom fields) and scope (workspace), distinguishing it from sibling list tools. However, the description uses a noun phrase rather than an explicit verb, relying on the name/title for the action.

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

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

The description states the workspace scope and adds a concrete prerequisite ('Needs a paid plan'), which tells the agent when the tool is available. It does not name alternatives, but none of the sibling tools are directly comparable for listing custom fields, so the guidance is sufficient.

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

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

The description adds the paid plan requirement, which is useful behavioral context beyond the annotations. Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, no other behaviors (e.g., pagination, filtering, response format) are 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 very short with two fragments, but it is under-specified rather than effectively concise. The first sentence is a noun phrase that could be clearer, and the second is a note. It is easy to read but fails to provide necessary substance.

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

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

Given the tool has no output schema and six optional parameters, the description is too minimal. It does not explain what the response looks like, mention pagination or filtering capabilities (which are in the schema), or provide any use-case context. The description is incomplete for a moderately complex list tool.

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

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

All six parameters have descriptions in the schema, providing 100% coverage. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description lacks a verb, using only a noun phrase 'Expenses recorded in the workspace.' It does not explicitly state that the tool lists expenses, relying on the title for the action. It also does not distinguish this tool from other list tools like list_time_entries or 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?

There is no guidance on when to use this tool versus alternatives. The only extra information is the paid plan requirement, which is a prerequisite rather than usage context. No exclusions or alternative tools are mentioned.

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

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

Annotations already declare this a safe read-only operation. The description adds that both public and company holidays are included, but it does not disclose behavior such as date-range filtering, pagination, workspace fallback, or response format. This minimal addition does little to enhance transparency beyond the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It communicates the essential content (holiday types and workspace scope), though it is perhaps too terse to fully inform the user.

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

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

Given the tool has 7 parameters and no output schema, the description is adequate but minimal. The schema covers parameter details, and the annotations cover safety, but the description does not mention return values or filtering capabilities, making it incomplete for a tool with this complexity.

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

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

Schema description coverage is 100%, with all 7 parameters documented (to, from, page, limit, all_pages, page_size, workspace_id). The description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description states what the tool returns: public and company holidays in the workspace. Although it lacks an explicit verb, the title 'List holidays' clarifies the action, and the description distinguishes this from sibling create/delete holiday tools by mentioning workspace configuration.

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 explicit guidance on when to use this tool versus alternatives. No mention of typical use cases (e.g., viewing upcoming holidays) or exclusions (e.g., use create_holiday for adding). The context is only implied by the tool's purpose.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the paid-plan requirement, which is useful, but does not disclose pagination behavior or defaults beyond what the schema already states. This is acceptable but minimal.

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, using only two fragments. It is concise, though the first fragment is nearly redundant with the title, containing only 'workspace' as added scope. It earns a 4 for efficiency, not a 5 because it lacks substantive 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 tool with six parameters, including pagination and workspace resolution logic, and no output schema, this two-fragment description is severely under-specified. It does not explain return format, pagination behavior, or the meaning of all_pages/status beyond what the schema already documents. The high-level context is insufficient for an agent to fully understand the tool's capabilities.

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

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

Schema description coverage is 100%, so all six parameters have meaningful descriptions in the input schema. The tool description itself does not add any parameter-specific context, meeting the baseline but not exceeding 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 'Invoices in the workspace' identifies the resource and workspace scope but lacks an explicit verb; it relies on the title 'List invoices' to convey the action. It does not differentiate from sibling list tools like clockify_list_projects or clockify_list_clients.

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 only usage-related information is 'Needs a paid plan,' which is a prerequisite, not guidance on when to use this tool over alternatives. No exclusions or alternative tool recommendations are provided, leaving the agent to infer usage 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the return fields (ids, clients, archived state) but does not disclose pagination behavior or any other side effects. This matches a baseline level of added context.

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

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

The description is a single concise phrase, 'Projects in the workspace, with their ids, clients and archived state,' with no superfluous words. It is front-loaded and easily scanned.

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 list tool with a rich schema (10 parameters, all documented) and annotations indicating read-only safety, the description is adequate. It states the primary output fields and workspace scope. The absence of an output schema is mitigated by the explicit mention of returned fields, though pagination edge cases are left to schema parameters.

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

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

The input schema provides descriptions for all 10 parameters (100% coverage), so the description does not need to elaborate on parameter details. It mentions 'clients' but that is a return field, not a parameter. Baseline of 3 applies because schema does the heavy lifting.

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

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

The title 'List projects' provides the verb, and the description 'Projects in the workspace, with their ids, clients and archived state' clearly states the resource and scope. It distinguishes from siblings like find_project or get_project by indicating a workspace-level listing of all projects, though the description itself lacks an explicit verb.

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 clockify_find_project or clockify_get_project. The description only implies workspace-level listing, but does not specify exclusions or recommend alternatives for filtered single-project lookups.

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

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

The description adds minimal behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false). It hints at workspace-level scope but does not disclose pagination behavior, return format, or any special conditions, providing little added value.

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, but this reads as underspecification rather than effective conciseness. It lacks a complete sentence or actionable phrasing, similar to low-quality under-specified examples.

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 7 optional parameters and no output schema, the description is far too minimal to provide adequate context. It does not state what the tool returns, how pagination works, or the resource's purpose beyond a noun phrase, leaving significant gaps.

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

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

Schema description coverage is 86%, so most parameters already have descriptions. The tool description itself adds no extra parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description 'Tags defined in the workspace' is a noun phrase without an explicit verb. It largely restates the tool title 'List tags' and fails to clearly communicate that this tool retrieves tags, making it vague and nearly tautological.

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 like clockify_create_tag, clockify_update_tag, or other list tools. The description lacks any context, exclusions, or alternative references.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that results include ids and status, which is mild behavioral context. It does not contradict annotations and does not need to disclose destructive effects. It also doesn't mention pagination behavior, but the schema descriptions cover pagination parameters, so this is acceptable.

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

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

The description is a single, efficient phrase: 'Tasks of a project, with their ids and status.' It is front-loaded with the core purpose and contains no filler words. Every word earns its place.

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

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

The description is adequate for a simple list operation but leaves some ambiguity. It doesn't clarify whether a project filter is required (the parameters are optional), and the return payload is only partially described as 'ids and status.' However, the schema covers parameters, and annotations cover safety, so the description is not critically deficient.

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

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

Schema description coverage is 100%, so every parameter already has a meaningful description. The tool description's mention of 'project' aligns with project_id and project_name parameters but adds no new semantic detail about parameter values, defaults, or relationships. It does not need to repeat schema content.

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 indicates that the tool provides tasks of a project and includes ids and status. It effectively communicates the resource and scope, and the title 'List tasks' supplies the verb. However, it does not explicitly distinguish between listing multiple tasks versus fetching a single task (get_task), though the plural 'Tasks' weakly implies that.

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 explicit guidance on when to use this tool versus alternatives. The phrase 'of a project' implies a project-based use case, but it does not mention exclusions, prerequisites, or alternatives like get_task or list_projects. There is no 'when to use / when not to use' clarity.

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 readOnlyHint and destructiveHint annotations, the description adds behavioral details: newest-first ordering, inclusion of a total, and defaulting to today when no date arguments are provided. This provides useful expectations without any contradictions.

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

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

Two concise sentences front-load the core purpose and key behavioral details. No wasted words, and the structure is clear and scannable.

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 essential context: scope, date range, ordering, default behavior, and the total. With 13 parameters and no output schema, it could elaborate on return shape, but the provided information is sufficient for a list tool.

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

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

Schema coverage is 100%, so all 13 parameters are described in the schema. The description adds minimal parameter-related meaning, only implying date-range and per-user filtering, which aligns with existing schema descriptions. This meets the baseline for full schema coverage.

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

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

The description states a specific verb+resource+scope: 'Time entries for a person over a day or a range, newest first, with a total.' This clearly distinguishes it from siblings like clockify_get_time_entry (single entry) and clockify_time_summary (aggregate).

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

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

The description gives clear usage context: it filters by person and date range, defaults to today, and returns newest first. However, it does not explicitly mention when to prefer this over alternatives, so it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds the functional detail that the output includes IDs for requests, but no further behavioral characteristics like pagination or filtering are disclosed. This matches the baseline for annotated tools.

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 redundant words, efficiently conveying the resource and the relevance of IDs. It could be slightly more complete grammatically, but conciseness is excellent.

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

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

For a simple list operation with two optional parameters and full schema coverage, the description, title, and annotations together provide adequate context. The absence of an output schema is compensated by the mention that IDs are returned. No critical information 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?

Both parameters (status, workspace_id) have complete descriptions in the schema (100% coverage). The description does not add any parameter-specific guidance, so the baseline score of 3 applies.

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

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

The description names the resource (time-off policies) and its scope (vacation, sick leave, other) and notes that the returned IDs are needed for requests. However, it lacks an explicit verb like 'list', relying on the title for the action. It distinguishes from sibling list_time_off_requests by focusing on policies rather than requests.

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 'with the ids a request needs' implies this tool should be used when retrieving policy IDs before creating a time-off request. It provides clear context but does not explicitly name alternatives or when not to use it, aligning with a score of 4.

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 description only needs to add context. It does add that requests are scoped to the workspace and that pending is a focus, but it doesn't disclose behaviors like pagination, ordering, or how the status filter interacts with the response.

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 conveys the core purpose and a use case. It is front-loaded and free of fluff.

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

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

For a simple list operation with no required parameters and no output schema, the description plus annotations and schema provide enough context. It could mention the return format or that it lists all requests filtered by status, but the essential behavior is clear.

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

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

Schema description coverage is 100%, so the schema fully documents the status and workspace_id parameters. The description adds no additional semantics beyond what's already present, so the baseline of 3 applies.

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

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

The title says 'List time-off requests' and the description 'Requests in the workspace' clearly identifies the resource and action, though it relies on the title for the verb. The note about pending requests being what an approver looks for adds context and helps differentiate from related list 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 this tool is for viewing time-off requests, particularly pending ones for approvers, but it doesn't explicitly state when to use this over alternatives like clockify_list_approval_requests. The usage context is hinted but not fully specified.

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 that results include member IDs and are workspace-scoped, but it does not disclose pagination behavior, default values, or the exact response structure. This is acceptable but not rich.

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

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

The description is a single short sentence that front-loads the key information (resource and one notable attribute). It is efficient and free of fluff, though it is slightly fragmentary and could benefit from a verb.

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 six optional parameters including pagination controls, the description gives only minimal context about return content ('member ids'). It does not explain that it returns a full list of teams, pagination semantics, or what other fields are present, leaving some gaps for a list operation.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema already provides, matching the baseline 3.

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

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

The description identifies the resource (teams/user groups in the workspace) and notes they include member IDs, which is specific enough to distinguish from other list tools. However, it lacks an explicit verb (the title supplies 'List') and does not directly state that it returns a list, so it falls just 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 description implies through its resource name and content that this tool lists user groups, providing clear context for when to use it. However, it does not explicitly state alternatives or situations to avoid, such as using workspace_users for user-level data, so 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context: the requirement for a paid plan and the workspace-level scope. This goes beyond the annotations without contradicting them, earning 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?

The description is two short sentences, front-loaded with the purpose and followed by a key prerequisite. Every word earns its place, with no redundancy or 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 list tool with one optional parameter, the description covers the core purpose and an important constraint (paid plan). The readOnly annotation covers safety, and the schema covers parameter details. It does not mention pagination or return format, but given the tool's simplicity, this is not a significant gap.

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

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

The input schema has 100% coverage; workspace_id is fully described with its fallback behavior. The description does not add any information about parameters beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource (webhooks) and its scope (workspace), which distinguishes it from sibling tools. It lacks an explicit verb like 'list' or 'retrieve,' but the title provides that, and the noun phrase 'Webhooks registered on the workspace' is unambiguous.

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

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

The description includes a prerequisite ('Needs a paid plan') which is useful for deciding when the tool can be used, but it does not explicitly state when to use it over alternatives or provide exclusion criteria. Given there is no sibling webhook tool, usage is implied by uniqueness, but the absence of explicit guidance keeps this at a 3.

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 readOnlyHint/destructiveHint annotations, the description adds useful context: workspaces are scoped to the API key's access, and the call may be refused when the server is locked to a single workspace. This exposes an edge-case behavior not captured in 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 concise sentences deliver the core purpose and a key behavioral caveat without repetition or filler. The main action is front-loaded in the first 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 parameterless read-only list tool, the description is adequate: it explains what is listed and a failure condition. Return format is not described, but with no output schema and a simple resource (workspaces), this is not a significant gap.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics. The description adds no parameter details, but none are needed. Baseline 4 applies.

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

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

The description clearly states the tool lists all workspaces visible to the API key. It distinguishes itself from sibling tools like clockify_get_workspace by explicitly covering the full set rather than a single workspace.

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 scope is implied ('Every workspace the API key can see'), showing when to use it to enumerate available workspaces. However, it does not explicitly mention alternatives or exclusion criteria, so guidance is only implicit.

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

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

Discloses a key behavioral trait beyond annotations: 'Each entry reports its own result, so one bad line does not lose the rest' which clarifies partial-failure handling. The annotations (readOnlyHint=false) align with the mutating nature of 'Writes'. More could be said about auth or prerequisites, but this added context is valuable.

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

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

Two concise, front-loaded sentences. The first states the action and purpose, the second adds behavioral nuance. No wasted words.

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

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

Given the moderate complexity of batch logging, the description covers the core intent and the per-entry reporting behavior. The lack of an output schema is mitigated by the mention that each entry reports its own result. It could mention response shape or prerequisites, but overall it is sufficiently complete.

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

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

The input schema already covers 100% of parameters with descriptions, so the description does not need to add parameter details. It does not go beyond the schema, leaving the baseline of 3 appropriate.

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

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

The description states a specific action ('Writes several finished entries in one call') with a clear resource scope ('a full workday reconstructed from notes or commits'). It naturally distinguishes itself from the sibling tool clockify_log_time by emphasizing batch writing.

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 a clear use case (bulk logging of a full workday) but does not explicitly mention when not to use it or name alternatives like clockify_log_time for single entries. It provides clear context without explicit exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds value by explaining timezone behavior: times are local to the account's zone and natural language like 'yesterday 09:00 for 2h30m' lands correctly. This provides useful behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and the timezone example adds valuable context without unnecessary verbosity. Every word earns its place, making it highly concise and well-structured.

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

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

Despite 14 parameters, the schema covers them thoroughly, so the description only needs to convey global behavior. It does so effectively, but it misses a brief distinction from related tools like log_many and does not mention what the API returns on success. Still, for a simple create operation, this is sufficiently complete.

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

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

Schema coverage is 100% per context signals, and each parameter already has a clear description (e.g., start, end, date, duration). The timezone note in the description reinforces but does not add new parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description 'Writes a completed time entry' uses a specific verb ('writes') and resource ('completed time entry'), clearly distinguishing it from siblings like start_timer (active tracking), update_time_entry (modifying), and log_many (multiple entries). The scope is precise and unambiguous.

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

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

The description implies usage for logging finished work ('completed time entry'), but it does not explicitly mention alternatives or exclusion criteria. There is no reference to when to use this versus log_many or start_timer, leaving the agent to infer from sibling names and 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?

The description adds the valuable detail that time entries are retained, which goes beyond the destructiveHint annotation. It does not mention reversibility, permissions, or other data impacts, but the annotation already signals destructive intent.

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 that are front-loaded and contain 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 simple destructive action, the description covers the core effect and a key exception. It does not mention the optional workspace_id fallback or the confirm requirement, but these are documented in the schema. With annotations and schema, the description is sufficiently complete.

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

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

All three parameters have descriptions in the schema (100% coverage), so the description does not need to explain them. It adds no additional parameter semantics beyond the schema.

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

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

The description clearly states the action ('Removes someone from the workspace') and adds a key consequence ('Their time entries stay.'), making it distinct from sibling tools like set_user_status or invite_user.

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

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

No explicit usage guidance or alternatives are provided. The use case is implied by the verb 'removes', but there is no discussion of when to prefer this over deactivating a user or when not to use it.

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

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

The description adds no behavioral context beyond what the annotations already convey. It does not explain what happens to the user's group memberships, whether the operation is reversible, or if any side effects occur. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description's 'takes out' aligns with a mutation, but 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 extremely concise (one sentence) and free of fluff, which is good, but it is under-specified and uses vague wording ('someone', 'a team') that could confuse. It sacrifices clarity for brevity, so it earns a mid-range score.

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

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

Given the tool is a mutation with no output schema, the description should at least clarify the scope (e.g., user group vs. team) and any relevant side effects. The description is too vague for an agent to fully understand when and how to use this tool, especially with sibling tools like clockify_add_user_to_group and clockify_remove_user nearby.

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

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

The input schema covers all three parameters with descriptions, including the workspace_id fallback behavior. The tool description adds no additional parameter meaning; the schema does the heavy lifting, so a baseline of 3 is appropriate.

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

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

The description states the action ('Takes someone out') and the resource ('a team'), but uses informal language and 'team' instead of the more precise 'group' found in the tool name and title. It does not differentiate from closely related sibling tools such as clockify_remove_user or clockify_add_user_to_group.

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 like clockify_remove_user (workspace removal) or clockify_delete_user_group (group deletion). The description provides no context on prerequisites, such as requiring a group_id and user_id, or scenarios where this operation is appropriate.

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

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

The annotations already indicate a non-read-only, non-destructive operation, and the description adds the context that the request is filed against a policy. However, it does not disclose any additional behavioral aspects such as approval workflow or potential side effects.

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, directly states the action, and contains no unnecessary words.

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

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

Given the tool has seven parameters and no output schema, the one-sentence description is minimal but adequate for a straightforward mutation. It does not describe the response format or post-submission process, which would be useful for an agent to know.

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

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

The input schema provides 100% coverage with descriptions for all seven parameters, so the description's mention of 'policy' adds little semantic value beyond the schema. The baseline score of 3 applies.

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

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

The description uses the specific verb 'Files' and identifies the resource 'time-off request' with the qualifier 'against a policy', which clearly distinguishes it from sibling tools like listing or approving requests.

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

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

The description implies the use case of creating a time-off request but does not explicitly state when to use this tool versus alternatives such as clockify_list_time_off_requests or clockify_submit_approval. No exclusions or alternative references are 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 indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral context by confirming history is preserved. It does not mention permissions, reversibility, or side effects on seat allocation, but the non-destructive nature is clearly disclosed, exceeding what annotations alone 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 a single, front-loaded sentence that conveys the essential purpose and key differentiator. There is no redundant or unnecessary text, making it highly concise.

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 status-change tool with 3 parameters and no output schema, the description covers the critical nuance (history preservation) without being overly verbose. Annotations clarify the mutation/destructive profile, and the schema covers parameter details, so the description completes the picture sufficiently. A brief note on permissions or reactivation would push it to 5, but it's 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?

Schema description coverage is 100% with all three parameters documented, including the important detail that INACTIVE frees the seat but keeps data. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Changes') and resource ('a member's status'), and adds the key distinction 'without deleting their history', which clearly differentiates it from sibling tools like clockify_remove_user. The title 'Activate or deactivate a user' reinforces the purpose.

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

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

The description implies when to use this tool (when you need to change a user's status without deleting history) but does not explicitly state alternative tools or exclusion criteria. Sibling tools like clockify_remove_user exist but are not referenced, leaving the guidance implicit.

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

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

The description discloses a critical behavioral trait: it stops an already running timer first. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) and is essential for the agent to anticipate side effects. This is a significant and well-communicated 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 concise sentences. It front-loads the main action ('Starts the clock') and immediately adds the critical constraint. Every word earns its place with no redundancy.

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

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

Given the 10 optional parameters and no output schema, the description covers the most important behavioral context (auto-stop). It doesn't describe return values, but the tool is simple enough that this is acceptable. The schema handles parameter documentation, so the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any parameter-level detail beyond what the schema already provides, but it doesn't need to since each parameter is well-described.

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

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

The description clearly states the tool's action with 'Starts the clock' and specifies the resource (a timer). It distinguishes from siblings by noting the one-running-timer-per-user constraint and the auto-stop behavior, making its purpose unambiguous.

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

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

The description provides clear context: it's for starting a timer, and it warns about the single-timer-per-user limitation. It doesn't explicitly mention alternatives like clockify_stop_timer or clockify_log_time, but the context is sufficient for most use 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 indicate this is a mutating action (readOnlyHint=false). The description adds that it returns the finished entry with its duration, but does not disclose behavior for edge cases like no running timer or the impact of the end parameter. This is some added context but leaves gaps.

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

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

The description is a single, focused sentence that front-loads the action and outcome. It contains no filler or redundant information, making it exceptionally concise.

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 stop action with three optional parameters, the description covers the essential behavior and explicitly states the return value (finished entry with duration). Edge cases like no running timer are not specified but are not critical for basic usage, and the schema and annotations cover the rest.

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

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

The input schema provides full descriptions for all three parameters (end, user_id, workspace_id), including defaults. The tool description does not add parameter-specific meaning, so the baseline of 3 is appropriate given 100% schema coverage.

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