Tick MCP by usefulapi

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds genuinely new context: the admin-only authorization requirement with the exact failure mode (403) and the plain-language warning that every call creates a new client. It stops short of describing the response payload or what happens if a same-named client 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?

Three compact clauses, front-loaded with the WRITE marker and the operation, then auth, then the duplicate-creation caveat. 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 create tool with no output schema, the description covers the operation, endpoint, authorization constraint, and non-idempotency risk, which is most of what an agent needs. It could add a note on the response (e.g., whether the new client ID is returned) but nothing essential 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 both parameters (name, archive) are already fully documented with defaults and length constraints. The description adds no parameter-level detail beyond what the schema provides, which is the expected 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 and resource ('create a new client') and even pins the endpoint (POST /clients.json), which cleanly separates it from tick_get_client and tick_list_clients. An agent can identify the operation without opening the schema.

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

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

It gives a critical precondition (Tick administrators only, 403 otherwise) and warns that each call produces a new client, which implicitly tells the agent not to retry blindly. However, it names no alternative tool or the condition under which an agent should prefer an update or lookup instead, so usage 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 readOnlyHint=false and idempotentHint=false, but the description adds real value beyond them: user_id is silently ignored for non-admins, every call creates a duplicate entry, and nothing is dispatched to anyone. Those are consequences an agent could not infer from the annotations alone.

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?

Four tight sentences, front-loaded with the WRITE marker and endpoint, then the prerequisites, then the caveats. No filler; each clause carries actionable 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?

Covers the mutation, its required inputs, the admin caveat, and the duplicate-creation behavior. With no output schema, it is silent on what the call returns (e.g. the new entry id), which is the only notable gap for a create 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 task_id, hours, and user_id semantics are already documented. The description largely restates the schema (decimal hours, admin-only user_id) and only adds the pointer to tick_list_tasks for obtaining task_id, 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 ('log a new time entry on a task') plus the endpoint, which distinguishes it cleanly from the sibling tick_update_entry. An agent knows exactly what operation this performs 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?

Points the agent to tick_list_tasks to obtain the required task_id, and 'Creates a new entry every call' implies the update path for existing entries. It never explicitly names tick_update_entry as the alternative for correcting an entry, so routing guidance is clear but not complete.

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?

Adds context beyond the annotations: the administrator-only permission requirement and the fact that the created project starts empty and needs a task before time entry works. 'Creates a new project every call' reinforces the non-idempotent behavior the annotations already hint at, and nothing here conflicts with openWorldHint or destructiveHint=false.

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

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

Four tight sentences, front-loaded with the 'WRITE:' marker and the operation, then permission, then post-state workflow constraint. Every sentence carries actionable information with no filler.

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

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

For a 7-parameter mutation tool with no output schema, the description covers permissions, non-idempotency, and the follow-up task requirement well. It does not indicate what the call returns (e.g., the new project id needed to chain into tick_create_task), which is the one gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so all seven parameters (name, client_id, budget, billable, owner_id, recurring, notifications) are already documented in the schema. The description contributes no additional parameter meaning beyond referencing tick_list_clients indirectly via the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('create a new project') plus the underlying endpoint (POST /projects.json), and it explicitly delimits scope by noting the new project contains no tasks, routing that work to tick_create_task. An agent can distinguish this from the create/list/get siblings without opening a schema.

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

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

Gives real preconditions ('Tick administrators only') and a workflow rule (create a task with tick_create_task before time can be logged), which tells the agent both who may call it and what must follow. It does not name an alternative for checking whether a project already exists (e.g., tick_list_projects), so it stops short of full when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the 'WRITE:' label is mostly redundant. However, 'Tick administrators only' adds an auth/permission requirement the annotations do not express, and 'Creates a new task every call' makes the non-idempotency operationally concrete (duplicate risk on retry).

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 fragments, front-loaded with the write classification and resource, then the permission constraint, then the idempotency caveat. No sentence restates the schema and nothing is padding.

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

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

For a simple four-parameter creation tool with no output schema and full annotation coverage, the description supplies endpoint, permissions, and duplicate-creation behavior – enough to call it correctly. It omits anything about the created-task response or rate limits, which is a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100% with four documented, self-explanatory parameters (name, budget, billable, project_id), so the schema carries parameter meaning. The description adds no format, unit, or constraint detail beyond it, matching the baseline-3 case.

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

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

States a specific verb and resource ('create a new task on a project') plus the backing endpoint POST /tasks.json. The resource noun cleanly separates it from sibling creators like tick_create_client, tick_create_project, and tick_create_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 a clear precondition ('Tick administrators only') and a retry warning ('Creates a new task every call'), which tells the agent to avoid blind re-invocation. It stops short of naming alternatives or when-not-to-use conditions, so it lands at clear-context-without-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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful context by disclosing the response content (a project summary with count and URL), which matters since there is no 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?

Front-loaded and compact: the returned shape is stated first, then the endpoint. The trailing 'GET /clients/{id}.json' is somewhat redundant for an MCP agent but harmless and keeps it terse.

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

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

For a simple read-by-id tool with full annotation coverage and a one-param schema, the description is nearly complete, covering purpose and return content. Minor gaps like error/not-found behavior remain but are not critical.

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

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

Schema description coverage is 100% for the single client_id parameter, so the schema already carries its meaning. The description's 'by id' adds essentially nothing beyond that, matching the baseline for fully documented params.

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 (client) with scope ('one client by id'), which implicitly distinguishes it from the sibling tick_list_clients. It does not explicitly name an alternative, so it falls short of the top mark.

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 only implied: an agent can infer this is for fetching a single known client by id versus listing all clients, but there is no explicit 'use this when / use list_clients instead' 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that the result is returned 'with its task' (an eager-loaded relation that changes how callers can use the response), but silent on 404/error behavior or whether data is ever cached.

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 terse sentences with the payload description front-loaded before the API path. Nothing is padded, though the raw REST path adds little for an agent that only calls the tool by name.

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

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

For a single-parameter read tool with full schema coverage and annotations covering the safety profile, the only gap is return-shape detail, which the description partly fills by noting the embedded task. Considering the missing output schema, this is close to adequate but not fully self-contained.

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

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

Schema description coverage is 100% and the single parameter has a clear schema description. The description adds nothing about the id beyond what the schema states, 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?

States a specific verb (get) and resource (one time entry by id), and adds that the response is hydrated with its task, which separates it from the bulk tick_list_entries. It does not name the sibling it replaces, so it is clear but not explicitly 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 statement, no prerequisite (e.g., where the id comes from), and no mention of tick_list_entries as the alternative for browsing entries. 'By id' implies a lookup, but the agent must infer the selection criteria entirely.

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, destructiveHint, and openWorldHint, and the description adds real value by disclosing what the response contains (total_hours, task count/URL summary, client). It does not address rate limits, permissions, or pagination, but for a single-item get this is solid 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?

A single front-loaded sentence that names the resource, scope, and returned fields, followed by the raw endpoint path. No filler; 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?

With no output schema, the description usefully compensates by summarizing the return shape (hours, task summary, client). It is nearly complete for a simple id-fetch tool, missing only error/not-found behavior.

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

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

Schema description coverage is 100% and the single project_id parameter is documented as 'Tick project id.' The description's 'by id' adds a slight framing but no format, range, or lookup-hint detail 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?

The description states a specific verb+resource ('one project by id') and enumerates the payload (total_hours, task summary, client), which clearly separates it from tick_list_projects. It does not name a sibling alternative explicitly, so it falls just short of full 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?

The phrase 'by id' implies this is the detail-fetch path when a specific project is known, but there is no explicit when-to-use or when-not-to-use guidance versus tick_list_projects or tick_get_task. Usage is only inferable.

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 goes beyond that by disclosing the return shape – total_hours, an entries summary (count and URL), and the associated project – which is genuinely useful context for planning a call. It omits auth/pagination details, so it stops short of 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?

A single front-loaded sentence that names the subject first, then the returned fields, then the endpoint. The trailing 'GET /tasks/{id}.json' is mildly redundant with the schema but serves as useful API mapping, so it is close to optimal without being wasteful.

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 describing the return value – and it does so partially (total_hours, entries count/URL, project). That is adequate for a one-parameter lookup tool, though the entry-summary detail is only sketched rather than specified.

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 a single documented parameter (task_id), so the baseline is 3. The description only restates 'by id' and adds no format, range, or lookup-source information 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?

States a specific verb and resource ('One task by id') and enumerates the payload (total_hours, entries summary, project), which cleanly separates it from tick_list_tasks and the sibling getters for clients/entries/projects. An agent can identify the tool 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?

Usage is implied by 'one task by id' – fetch a single task when you already have its id – but no alternative is named and no when-not condition is given. For a simple lookup tool where the alternative (tick_list_tasks) is obvious from the sibling set, this is minimally viable 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context: the hidden default filter (open projects only) and the 100-per-page pagination, though it omits response shape 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?

Three short sentences, front-loaded with purpose then default behavior then pagination/endpoint. Every sentence carries information; nothing is 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?

With no output schema, the description does not describe the response shape, which is a minor gap, but pagination (100 per page) and the next_page continuation hint in the schema cover the practical mechanics. Sufficient for a two-parameter read 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 baseline is 3, but the description extends the schema by clarifying that 'all' includes archived and projectless clients — the schema only says 'all clients'. It adds marginal but real semantics on top of documented parameters.

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 Tick clients') and immediately discloses the non-obvious default scope (only clients with open projects). An agent can distinguish it from tick_list_projects/tick_list_users by resource alone.

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 when to switch modes: default vs include_all=true for archived/projectless clients. It does not name sibling alternatives such as tick_get_client for single-client lookups, but the mode-selection guidance is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the required date-range/updated_at constraint, the 100-per-page pagination, and the fields each entry 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?

Front-loaded with the core constraint and filters, then return fields and pagination. Dense and mostly waste-free, though the trailing "GET /entries.json" adds little for an agent.

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 usefully enumerates the returned entry fields and flags pagination. Combined with the filter list and the required-parameter rule, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema documents each parameter's individual meaning. The description still adds a cross-parameter rule the schema lacks entirely — the OR relationship between (start_date + end_date) and updated_at — which is genuine semantic value.

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

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

States a specific verb and resource ("List time entries") that clearly separates it from the singular tick_get_entry sibling. It does not explicitly name that sibling or scope beyond the plural nouns, 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?

Gives a hard usage rule: you must supply EITHER start_date AND end_date OR updated_at, and lists the optional filters. This is clear invocation context, but it offers no explicit alternatives or when-not-to-use 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond that: page size (100 per page) and the underlying endpoints (GET /projects.json vs /projects/closed.json), which explains why the status parameter changes the target resource.

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 sentences with no filler; the returned-field list and default status come first, endpoint mechanics last. Slightly dense but 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?

No output schema exists, and the description compensates by naming the fields returned and the pagination model, plus the status-driven endpoint switch. An agent can call it correctly; only ordering/sorting behavior and next_page handling detail (which lives in the schema) are absent.

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 both parameters are already documented in the schema (page default 1, status enum open/closed). The description restates the same defaults and page size rather than adding format or edge-case 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 Tick projects') and enumerates the salient returned fields (budget in hours or money, billable flag, client_id, owner_id), which clearly separates it from tick_list_clients, tick_list_entries and tick_list_tasks. It does not explicitly contrast with any sibling, but the resource noun alone is unambiguous.

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

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

It gives the default behavior ('Open projects by default; status=closed for closed ones'), which tells the agent how to reach closed records, but never says when to prefer this over tick_get_project or how it relates to the other list tools. Usage is implied by the verb 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the default status=open filter, the four distinct endpoints reached depending on inputs, and the 100-per-page pagination size.

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?

Four short sentences, front-loaded with the resource definition and scoping before the endpoint detail. The endpoint enumeration is somewhat verbose but earns its place by mapping inputs to routes.

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?

No output schema exists, so the description should carry return-value context; it gives pagination size and hints at next_page handling in the schema. It stops short of naming returned fields, leaving a modest gap.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by stating what happens when project_id is omitted ("across all projects") and reinforcing the status default, which the schema only hints at.

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 Tick tasks") and even clarifies the domain concept ("budget lines that time entries are logged against"), which an agent cannot get from the name alone. The scoping rules make it easy to distinguish from sibling list tools like tick_list_projects or tick_list_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?

Explains the two scoping modes (all projects vs. one via project_id) and the default filter (open tasks). It also ties the tool into the logging workflow ("You need a task id to log time"), but it never explicitly names a sibling alternative or a when-not-to-use condition.

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 readOnly/destructive annotations, it discloses the authorization-dependent result set (a non-administrator sees only themself) and the admin-only restriction on the deleted listing — real behavioral context the annotations cannot express. It does not cover pagination behavior, which the schema handles.

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 sentences: purpose and returned fields first, then permission semantics, then the deleted variant. No filler, and the raw endpoints are a compact routing hint for an API-aware agent.

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 description supplies the returned fields, the permission-scoped result set, the deleted-mode behavior and the backing endpoints. Pagination is documented in the schema's page parameter, so nothing needed to call 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 coverage is 100%, so the baseline is 3, but the description adds a constraint the schema omits: the deleted flag is administrators-only. It also confirms what a deleted listing returns.

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 users of the Tick subscription') and enumerates the returned fields (id, name, e-mail, timezone). It is trivially distinguishable from the sibling list_* tools, which target clients, entries, projects and 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?

Gives concrete selection context: use deleted=true for removed users who still have time entries, and notes that path is administrators-only. It does not name a sibling alternative, but the sibling set covers entirely different resources, so no disambiguation is required.

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 destruction, idempotency and open-world scope, so the bar is lower. The description still adds real value by disclosing partial-update semantics ('only the fields you pass change; the previous values are overwritten'), which an agent needs to avoid accidentally clobbering data. It stops short of noting permissions or irreversibility of the billed flag.

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

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

Two sentences, zero padding, and the most decision-relevant token ('WRITE') is front-loaded followed immediately by the scope and endpoint. Everything earns its place, though the endpoint string is somewhat redundant for an agent that never sees URLs.

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 partial-update mutation with full schema coverage and annotations carrying the safety profile, the description supplies the one thing the structured fields lack: that omitted fields are preserved while passed fields are replaced. No output schema exists, so return values need not be explained. Minor gaps (auth requirements, conflict behavior) are acceptable here.

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

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

Schema description coverage is 100%, so the schema fully documents each field's type, bounds and format. The description only restates the same field names (hours, notes, date, task, billed) without adding format or constraint detail beyond the schema, 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 gives a specific verb ('change'), an explicit resource ('an existing time entry'), the endpoint, and the exact set of updatable fields. It cleanly separates this from tick_create_entry and the tick_get_* read tools, so an agent can select it 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?

The 'WRITE:' prefix and 'change an existing time entry' imply usage context, and the field list tells the agent what can be modified. However, it never states prerequisites (e.g. needing the entry_id from a list/get call) or when to prefer this over other write tools, so guidance remains 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.