Clockify MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the mutation and non-idempotency profile is covered. The description only restates writability ('WRITE:') and adds the endpoint path; it says nothing about auth requirements, duplicate-name failure behavior, or rate limits that would add 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?

Two short, front-loaded fragments with no padding; the mutation marker comes first. The trailing endpoint string is mildly redundant with the tool name but is useful for API-oriented clients, so it is not wasteful enough to drop below a 4.

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 five-parameter create with full schema coverage and annotation-supplied safety hints, the description is adequate. However, with no output schema it never indicates what is returned, and it omits any note about the duplicate-name failure implied by the schema's uniqueness constraint.

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 five parameters (including the uniqueness constraint on name and the workspace_id default) are already documented in the schema. The description contributes no additional parameter meaning beyond that baseline.

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

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

The description names a specific verb ('add a client'), the resource type, and the target scope ('to a workspace'), so the operation is unambiguous. It does not explicitly contrast itself with siblings like clockify_list_clients or clockify_create_project, so it stops short of a 5.

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

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

The 'WRITE:' prefix and 'add a client to a workspace' imply a create workflow, but there is no explicit when-to-use guidance, no mention of checking for existing clients or following up with an update tool, and no prerequisite context. Usage is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint false, idempotentHint false, destructiveHint false, openWorldHint true), so the bar is lower, and the description still adds the role/permission requirement and the raw HTTP endpoint. It does not mention rate limits or that non-idempotent retries can create duplicate projects, but it adds solid 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?

Two dense, front-loaded sentences: the write intent and permission requirement come first, then the endpoint. Nothing is redundant or padded.

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 seven-parameter write tool with no output schema, the description covers the operation, the required privilege, and the endpoint. It would be stronger if it mentioned what the response contains (the created project object/id), but otherwise an agent has what it needs to call it correctly.

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

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

Schema description coverage is 100% and all seven parameters are documented in the schema, including uniqueness per client, color pattern, and workspace default behavior. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('create a project in a workspace') and reinforces it with the literal endpoint POST /v1/workspaces/{workspaceId}/projects, so there is no ambiguity about what the call does. It does not explicitly contrast itself with the other create_* siblings, but the resource is distinct enough that differentiation is easy.

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

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

It gives a genuine prerequisite (admin or project-manager role, workspace-dependent), which is real usage guidance. However it never says when to prefer this over e.g. checking clockify_list_projects first, nor what to do on a duplicate-name conflict, so guidance is implied rather than explicit.

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 write (readOnlyHint=false), non-idempotent, non-destructive and open-world behavior, so the description's 'WRITE:' marker and POST endpoint largely restate them. It adds no context on error handling, duplicate-name behavior, or permissions required, so it does not exceed the annotation baseline.

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

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

Two short clauses, front-loaded with the operation type and endpoint; zero filler. An agent can act on it immediately without wading through prose.

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

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

For a two-parameter create tool with full schema coverage and annotations that carry the safety profile, the description covers what an agent needs to call it. The only omission is behavior on a duplicate tag name, which the schema hints at via 'unique in the workspace' but does not resolve.

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 both parameters (name with uniqueness/length constraints, workspace_id with a default) are fully documented in the schema. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('add a tag to a workspace') and names the exact endpoint, which is far from a tautology. It does not explicitly differentiate from sibling creates like clockify_create_project, but the verb+resource pairing 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?

No guidance on when to use this versus alternatives. It does not tell the agent to check clockify_list_tags first to avoid duplicate names, nor does it state prerequisites beyond the implicit workspace context. Only the 'WRITE:' prefix hints at the mutation 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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the "WRITE" prefix is redundant. The description adds nothing behavioral beyond that: it doesn't say that repeated calls create duplicate tasks (non-idempotent), what permission/scope is needed, or what happens on failure — the endpoint string is not behavioral context.

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

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

Two short sentences, front-loaded with the operation class and the action, with zero filler. Nothing can be trimmed without losing 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?

A simple mutation tool with complete schema coverage and annotations covering the safety profile, so the core call is unambiguous. However, with no output schema and no note about what the created task returns or how the non-idempotent behavior affects retries, an agent lacks some operational 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 100% and every parameter (name, estimate ISO-8601 pattern, assignee_ids, project_id, workspace_id with default) is documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("add a task to a project") plus the exact HTTP endpoint, so an agent can tell this apart from clockify_create_project or clockify_create_time_entry by resource. It does not, however, explicitly name sibling alternatives for the same resource family (e.g., list_tasks).

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

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

There is no when-to-use guidance, no prerequisite that a project_id must come from clockify_list_projects, and no mention of the relationship to clockify_list_tasks. Usage is only implied by the word "add".

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 as a non-read-only, open-world, non-idempotent write. The description goes beyond them by disclosing the log-vs-timer branching, that start defaults to now, and that required custom fields can cause refusal — useful failure-mode context. It omits auth requirements and the single-running-timer constraint.

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

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

Front-loads the 'WRITE' marker, then two compact sentences covering mode, default, precondition, and endpoint. Every clause earns its place with no padding.

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

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

For a nine-parameter write tool with no output schema and zero required params, the description covers mode selection, defaults, and the main refusal case. It could say more about the return value or running-timer conflicts, but the essentials are present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the end-omitted/start-default behavior that the schema properties already document, adding only the cross-parameter interaction. Little net new meaning.

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

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

States a specific verb and resource ('add a time entry for yourself') and disambiguates the two modes: with end it logs completed time, without end it starts a running timer. This cleanly separates it from siblings like clockify_stop_timer and clockify_update_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?

Gives clear mode-selection guidance (supply end to log, omit it to start a timer) plus a failure precondition about workspaces with required custom fields. It stops short of naming alternatives such as stop_timer or update_time_entry, or warning that an already-running timer may block a new one.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description still earns credit for adding irreversibility ("It cannot be undone") and the underlying endpoint, details the annotations do not convey. It does not say what happens on a nonexistent id, which is the remaining gap.

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

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

Three short sentences, all front-loaded: the operation class and destructiveness come first, then irreversibility, then the endpoint. No filler and nothing buried.

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

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

For a two-parameter delete with no output schema and full annotation coverage, the definition supplies what an agent needs to call it safely. Only the error/edge-case behavior (deleting an already-deleted or unknown entry, interaction with a running timer) is unaddressed.

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%: time_entry_id and workspace_id (with its default and provenance from clockify_list_workspaces) are fully documented in the schema. The description adds nothing about parameter formats or defaults, so this is 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?

States a specific verb and resource ("permanently delete one time entry") and even names the REST path, so there is no ambiguity about scope. The destructive verb distinguishes it cleanly from sibling read tools like clockify_get_time_entry and 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 never says when to choose deletion over the obvious alternatives (clockify_update_time_entry to modify, clockify_stop_timer to end a running entry). It also gives no precondition such as requiring the entry id to exist or be owned by the caller, leaving the agent to infer everything from the verb 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are 'newest first' (ordering), 'paged' (pagination behavior), and include totals, plus the underlying POST reports endpoint. It does not state rate limits or an upper bound on returned entries.

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

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

One dense but front-loaded sentence covers scope, payload, ordering and pagination, with a terse endpoint line after it. No filler, though the long parenthetical of output fields makes the first sentence heavier than necessary.

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, so the description carries the burden of explaining returns — and it does, listing the fields and noting totals, ordering and paging. All 12 parameters are covered by the schema. Minor gaps remain around result limits and error behavior, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% — all 12 parameters, including the 31-day free-plan constraint and next_page chaining, are documented in the schema itself. The description's parenthetical lists returned fields rather than clarifying parameter semantics, so it adds no meaning beyond the schema. 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?

States a specific resource ('Every time entry in a date range across the workspace') and enumerates the returned data (user, project, client, task, tags, description, start/end, duration, amount, totals), so the agent knows exactly what it produces. It stops short of naming its closest sibling, clockify_summary_report, to make the detailed-vs-aggregated distinction explicit.

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

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

Usage is implied by the scope statement — a per-entry report over a date range — but there is no explicit when-to-use, when-not-to-use, or pointer to clockify_summary_report as the aggregation alternative. Prerequisites (e.g. workspace scope, free-plan date limit) are left to the 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real value by disclosing the returned payload fields and the underlying endpoint (GET /v1/user), which is meaningful given there is no output schema. It does not mention auth failure modes, but that is a minor omission for a zero-parameter read.

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

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

One sentence plus the endpoint, front-loaded with identity and scope, then the field list. No filler and every clause carries information.

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

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

For a zero-parameter read with annotations covering safety and no output schema, the enumerated return fields make the definition self-sufficient. Only the behavior on an invalid/expired API key is left unspecified.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to clarify inputs, and it correctly does not invent any.

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

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

States a specific verb+resource ('The Clockify user this API key belongs to') and enumerates the fields returned. This implicitly but clearly distinguishes it from the sibling clockify_list_users, which returns all users rather than the authenticated one.

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 rather than stated: the phrase 'this API key belongs to' tells an agent this is for resolving the caller's own identity and default workspace, but there is no explicit when-to-use/when-not or named alternative such as clockify_list_users.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about auth, hydration behavior beyond the schema flag, or rate limits. With annotations carrying the safety burden, this is adequate but not rich.

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

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

A single dense sentence front-loads the resource and its returned fields, then gives the endpoint. Nothing is wasted, though the field enumeration is slightly long for the space it occupies.

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

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

With no output schema, the description compensates by listing the returned fields, which is exactly what an agent needs for a read tool. Coverage of return data is good; minor gaps around hydrated behavior and sibling routing remain.

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 three parameters (including the hydrated flag and default active workspace) are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the correct baseline when the schema does the work.

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

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

States a specific verb (get) and resource (project) and clarifies it is 'One project by id', implicitly distinguishing it from clockify_list_projects. It also enumerates the returned fields, so an agent knows exactly what it yields. It stops short of explicitly naming the list sibling as the alternative.

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

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

The phrase 'One project by id' implies when to use it (single-resource lookup), and the field list signals read usage, but there is no explicit when-to-use vs. clockify_list_projects or any prerequisites. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description does add useful behavior: the default user is 'you' and the call returns 'running: false' when nothing is active, which tells the agent how to interpret an empty 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 front-loaded sentence plus the endpoint reference; nothing is padded. The raw endpoint string is slightly extraneous but compact and 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?

For a two-parameter read tool with full schema coverage and no output schema, the description covers purpose, defaults, and the empty-result case. Only error/auth behavior and the concrete response shape are unstated, which the annotations largely excuse.

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 both parameters and their defaults are already documented in the schema. The description only echoes the 'default: you' behavior and adds no syntax or format detail 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?

States a specific verb (get) and resource (the running timer) and even names the underlying endpoint, so an agent can distinguish it from clockify_stop_timer and clockify_list_time_entries. It does not explicitly name those siblings, but the scope 'running right now' 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?

There is no explicit when-to-use guidance or routing to alternatives such as clockify_list_time_entries or clockify_stop_timer. The intended use (check whether a timer is currently active) 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is genuinely useful given there is no output schema, but says nothing about the hydrated flag's effect, permissions, or error behavior.

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

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

Two compact fragments with the resource and payload front-loaded; little waste. The trailing REST path is mildly redundant but gives an agent a concrete anchor.

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, listing the returned fields is the right compensation and largely closes the gap. What remains unstated is the default hydration behavior and whether related objects are embedded without hydrated=true, which matters for interpreting the response.

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 hydrated (embed project/task/tags), workspace_id (default active workspace) and time_entry_id fully documented inline, so the baseline of 3 applies. The description adds no syntax or behavioral detail 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?

Names the resource and the identifier key ('One time entry by id') and enumerates the payload fields (description, project, task, tags, billable, rates, custom fields, timeInterval), plus the underlying endpoint. It reads clearly against list_time_entries/update_time_entry, though the differentiation is implied by 'by id' rather than stated.

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 statement of when to use this tool versus alternatives, no mention of prerequisites (e.g. needing a valid time_entry_id or workspace context), and no exclusions. The only routing hint lives in the schema, not the description.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about default pagination behavior or result ordering beyond what the schema already implies.

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

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

A single sentence plus the endpoint reference, with the core action front-loaded. No padding or redundancy.

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

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

For a read-only list tool with no output schema, the inclusion of the returned field list (id, name, email, address, currency, archived) fills the gap an output schema would normally cover. Annotations handle the safety profile, so the definition is nearly complete for its 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 each of the five parameters (name, page, archived, page_size, workspace_id) fully documented in the schema. The description enumerates returned fields rather than input parameters, adding no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the clients of a workspace') and even enumerates the fields returned, so the agent knows exactly what it gets back. It does not explicitly differentiate itself from siblings like clockify_list_projects or clockify_list_users, but the resource noun is specific enough to be 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?

No when-to-use, when-not-to-use, or alternative guidance is provided. The usage for a plain list tool is implied, but nothing tells the agent how this relates to clockify_list_projects or clockify_list_workspaces.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint (GET /v1/workspaces/{workspaceId}/projects) and the workspace scoping, but says nothing about pagination limits or the cost of hydrated=true. With annotations carrying the safety burden, this is adequate but thin.

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

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

Three tight segments — purpose plus returned fields, filter dimensions, then the endpoint — with no filler or redundancy. Front-loaded with the core verb+resource before the filter 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?

With nine optional params and no output schema, the description usefully enumerates the response fields, compensating for the missing output schema. It falls short only on pagination behavior and what hydrated=true costs, which an agent would need before relying on this for large workspaces.

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 nine parameters are already documented with defaults and constraints. The description's filter list roughly restates name/client/user/billable/archived and omits hydrated, page and page_size, so it adds essentially nothing beyond the structured schema. 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?

States a specific verb and resource ('List the projects of a workspace') and enumerates the fields returned, which immediately separates it from clockify_get_project (single project) and the create_* siblings. An agent can identify the tool's scope without opening the schema.

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

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

It names the filterable dimensions ('Filter by name, client, user, billable or archived'), which implies the discovery use case, but never states when to reach for this versus clockify_get_project or clockify_list_workspaces for resolving a workspace id. No exclusions or prerequisites are given; usage 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about pagination behavior, page-size limits, or rate limits beyond what the schema already carries.

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, front-loaded sentences with no filler. The trailing raw endpoint (GET /v1/workspaces/{workspaceId}/tags) is somewhat redundant with the tool name, keeping this just short of perfect.

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

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

With no output schema, the description partially compensates by naming the returned fields, and pagination mechanics live in the schema. For a simple read-only list tool this is nearly sufficient; it lacks any note on total counts or ordering, which would complete the picture.

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 (name filter, page, archived, page_size, workspace_id) is already fully documented in the schema, including defaults and the next_page hint. The description's '(id, name, archived)' reads as return fields rather than parameter semantics, so it adds no meaning beyond the schema. 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?

States a specific verb and resource ('List the tags of a workspace') and even enumerates the returned fields (id, name, archived), so the agent knows exactly what this returns. It does not explicitly contrast with siblings, but 'list tags' is naturally unambiguous against clockify_create_tag.

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

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

No when-to-use or when-not-to-use guidance is given; the description never mentions alternatives or the conditions (e.g., filtering by name, walking pages) under which this tool is the right call. Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing the endpoint (GET) and the shape of the result (id, name, status, assignees, estimate, duration tracked), which is important because no output schema exists. It omits pagination behavior and any rate-limit or permission notes, keeping it from a 5.

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

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

Two tight sentences that front-load the core action and the returned fields, followed by the endpoint for reference. Nothing is padded and nothing needs to be re-read.

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 100% schema coverage, full annotations and no output schema, the description covers scope, returned fields and the endpoint, which is close to sufficient. The one gap is that it says nothing about the filtering options or pagination flow, leaving that entirely to 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 description coverage is 100%, including filter semantics for name, is_active, page and page_size, so the schema carries the parameter burden. The description adds no additional parameter meaning (it never mentions the name or is_active filters), so the baseline 3 applies.

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

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

States a specific verb+resource ('List the tasks of a project') and even enumerates the fields returned, which clearly separates it from clockify_create_task or clockify_get_project. It stops short of naming a sibling or scope boundary explicitly, so it is clear but not maximally differentiated.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The only hint is the required project_id, which merely restates that the tool is scoped to one project; an agent gets no help choosing between this and language-adjacent siblings such as clockify_get_project or clockify_list_projects.

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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds real behavioral context on top: newest-first ordering, the default user scope, and the field set returned (id, description, project, task, tags, billable, timeInterval with ISO 8601 duration). It does not mention pagination semantics or rate limits, but it goes beyond restating 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?

Three compact sentences with no filler: scope and ordering first, then filter dimensions, then the alternative tool, then the endpoint. Each sentence carries distinct information and nothing is repeated from the schema.

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

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

With 11 optional params, no output schema and no required fields, the description compensates well by listing the returned fields, stating the default user/workspace scope and ordering, and routing totals to a sibling. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented in the schema, including the admin/manager role note on user_id and the next_page hint on page. The description only summarizes the filterable dimensions ('time range, project, task, tags or description') without adding format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the time entries of one user'), names the default scope (you), and specifies the ordering (newest first). It also explicitly carves out the sibling it is not: 'For totals across users use clockify_summary_report', so an agent can separate it from clockify_detailed_report and clockify_summary_report without opening any schema.

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

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

Gives a clear routing rule to an alternative ('For totals across users use clockify_summary_report') and enumerates the filter dimensions, which tells the agent when this tool is the right fit. It stops short of a full when-not statement (e.g. when to prefer clockify_detailed_report or clockify_get_time_entry for a single entry), so it is strong but not exhaustive.

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, destructiveHint=false and openWorldHint=true, and the description's mention of GET reinforces the read-only nature without contradicting it. It does add useful behavior beyond the schema by listing the shape of returned members (settings included), which partially compensates for the missing output schema.

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

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

Three short clauses, front-loaded with the resource and returned fields before the filters and endpoint. The trailing 'GET /v1/workspaces/{workspaceId}/users' is largely redundant with the tool name and schema but is short enough not to bloat the definition.

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 7-parameter, no-required-argument list tool, the definition covers resource, filters, and returned fields, and annotations carry the safety profile. Pagination mechanics are left entirely to the schema; with no output schema the description's field list is a helpful, if brief, stand-in.

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 one of the seven parameters is already documented in the schema, including the page/next_page continuation hint and page_size bounds. The description simply restates the filter dimensions (name, email, status, project access) without adding syntax, defaults, or edge-case behavior beyond what the schema provides.

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

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

The description states a specific verb and resource ('List the members of a workspace') and enumerates the returned fields (id, name, email, status, settings), which clearly separates it from the other list_* tools in the sibling set. It does not explicitly name its nearest alternative (clockify_get_current_user), so it falls just short of full sibling differentiation.

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

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

It tells the agent that results can be narrowed by name, email, status or project access, which implies the tool's role as a filtered directory lookup, but it gives no when-to-use vs. when-not guidance and no alternatives for fetching a single user. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the concrete return payload and the fact that the id is the workspace_id input for other tools, plus the underlying endpoint GET /v1/workspaces.

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

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

Front-loaded with the core action and result fields, followed by two short, purposeful sentences about downstream use and the endpoint. Slight density in the field enumeration but no wasted 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?

There is no output schema, so the description correctly compensates by naming the returned fields and explaining how to reuse the id. Combined with annotations covering safety, an agent has everything needed to call it, though pagination or result-size behavior is not addressed.

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 sole parameter 'roles' is fully documented in the schema, so the baseline is 3. The description never mentions the roles filter and adds no syntax or semantics beyond the schema, so it does not exceed the baseline.

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

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

States a specific verb and resource ('List the Clockify workspaces you belong to') and enumerates the concrete fields returned (id, name, plan, subdomain, currencies, rates). An agent can distinguish this from sibling list tools (clients, projects, tags) without opening any schema.

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

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

Explicitly tells the agent how to consume the result: 'Use the id as workspace_id in other tools,' which is the key cross-tool routing information. There is no competing sibling for listing workspaces, so no exclusion guidance is needed, but no usage conditions (e.g. when to filter by role) are stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: Clockify returns 404 if no timer is running, and it names the PATCH endpoint. It does not explain what the response contains after stopping, but that is a minor gap given the annotation coverage.

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?

Extremely compact: the action and scope are front-loaded, followed by the notable 404 behavior and the endpoint. Every clause is load-bearing with no filler.

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

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

For a 3-param, zero-required stop operation with no output schema, the description plus annotations cover what an agent needs: safety profile, defaults, and the key 404 failure mode. It could mention what the stopped entry returns, but nothing critical is missing.

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

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

Schema description coverage is 100%, and each parameter already documents its default and constraints (e.g., admin role needed to stop another user's timer). The description's restatement of the 'default: you/now' behavior adds little beyond the schema, so baseline 3 is appropriate.

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

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

Specific verb+resource: 'stop the running timer of a user'. The 'WRITE:' prefix immediately signals the operation class, and it is clearly distinguishable from the sibling clockify_get_running_timer (read) and clockify_create_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 states the defaults for user (you) and end (now), implying normal single-timer usage, and it warms about the 404 when no timer runs. But it never explicitly says when to prefer this over alternatives (e.g., get_running_timer to check first, or update_time_entry to edit instead of stop). Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond them: the output is time in seconds plus amounts, grouping maxes at 3 levels with a stated default, and filters apply. It omits return shape, pagination, and any auth or rate-limit notes, so it does not reach the 4-5 band.

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

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

Three sentences, front-loaded with what is totalled and an example, followed by a filter note and the HTTP endpoint. Efficient with no wasted filler, though the raw endpoint line adds little for an agent choosing between tools.

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

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

For a read-only report tool with no output schema, the description conveys the key result semantics (seconds and amounts, grouped levels) and defaults, which is most of what an agent needs. It leaves the response structure and pagination unexplained, a minor gap given there is no output schema to lean on.

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 11 parameters are already documented individually. The description restates the default grouping (PROJECT → TIMEENTRY) and that filters are respected, which the schema already conveys, adding no new syntax or semantics; 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?

States a specific verb and resource: 'Totals of tracked time (seconds) and amounts ... grouped by up to 3 levels' with a concrete example. An agent knows it is an aggregated report, but the description never names its closest sibling clockify_detailed_report, so the aggregate-vs-per-entry distinction must be inferred.

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 statement is 'Respects the filters', which explains behavior rather than when to choose this tool. There is no guidance on when to use summary_report versus clockify_detailed_report, nor any stated exclusions or prerequisites, even though a near-identical sibling exists.

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

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

With annotations already declaring destructiveHint=true and idempotentHint=true, the description still adds substantial non-obvious behavior: only passed fields change, the entry is read first and re-sent wholesale, a concurrent edit (e.g. in the Clockify app) can be silently lost, and a new project_id without task_id clears the task. It also states the exact GET-then-PUT endpoint. This is rich behavioral disclosure well 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?

Front-loaded with the 'WRITE:' marker, then four dense sentences that each carry distinct payload: mutation scope, partial-update semantics, concurrency/lost-update risk, and the cross-field task rule. No filler or restatement of the name or title.

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

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

For a 9-parameter mutation with no output schema, the description covers what it must: what changes, what is preserved, concurrency hazard, cross-field side effects, and the underlying endpoint. Annotations cover safety hints, and the absence of an output schema means return-value detail is not required.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents each field. The description adds real semantic value on top: the cross-field rule that 'a new project without task_id clears the task' is not expressible in the flat schema. That single cross-parameter interaction is the main addition; other parameters are left to the schema.

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

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

The description opens with a specific verb+resource framing ('WRITE: change a time entry') and enumerates exactly which fields are mutable (start, end, description, project, task, tags, billable). This makes the tool's function unambiguous. However, it never names a sibling (e.g. create_time_entry, get_time_entry, delete_time_entry) to route the agent, so it falls short of the 5 tier.

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 'use this when...' or 'do not use this when...' guidance, nor any reference to the create/get/delete siblings. Usage is only implied through the word 'WRITE' and the partial-update section. An agent can infer this is the mutation path, but the description leaves sibling selection to the tool name.

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