Harvest MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and it delivers: it discloses that the timer mode only works on a timestamp-tracking account, that ended_time is optional alongside started_time, and that the call is a write ('WRITE — creates data'), consistent with the write hint. It does not state what the response contains or whether the action is reversible, 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?

Front-loaded with the action and the three modes before the routing hint and REST metadata. Dense but every sentence adds usable information; the trailing 'Harvest REST: POST /time_entries. WRITE — creates data.' is mildly redundant with the tool name, keeping it out of 5 territory.

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

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

For an 8-parameter create tool with full schema coverage and no output schema, the description covers the required IDs, the three invocation patterns, the account-type caveat, and a helper sibling. The one thing an agent must infer is what the created entry returns (e.g., the new entry id needed to later stop or update it), which is not stated.

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 baseline is 3, but the description adds semantics the schema cannot express: the mutual exclusivity of hours / started_time / (neither) and the account-type precondition on the timer mode. This is real meaning beyond the field-level descriptions.

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

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

States a specific verb+resource ('Create a time entry') and then enumerates the three distinct operating modes, which lets an agent immediately distinguish this from harvest_update_time_entry, harvest_stop_time_entry and harvest_restart_time_entry. No sibling does what this does, and the description makes that 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?

Gives explicit mode-selection guidance (hours vs. started_time vs. neither for a running timer) and routes the agent to harvest_list_project_assignments to resolve valid project_id/task_id, which is genuinely actionable. It stops short of naming when NOT to use it (e.g., 'use harvest_update_time_entry to modify an existing entry'), so it is clear context without full 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 destructiveHint=true, so the bar is lower; the description still adds real value by stating the deletion is permanent and irreversible and by naming the underlying write endpoint (DELETE /time_entries/{id}). It does not discuss auth requirements, error behavior, or restrictions on locked/invoiced 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?

Three short, front-loaded sentences with the destructive consequence stated first. The trailing 'WRITE — destroys data' and the REST path partially restate the destructiveHint, but they cost little and are useful for an agent mapping to the API.

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 mutation with destructive annotations and no output schema, the definition covers what the agent must know before calling it. It leaves out failure modes (e.g., entries tied to invoiced time) and any confirmation expectation, which would be the finishing touch.

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?

Only one parameter and schema coverage is 100%, so the schema already documents time_entry_id as a required positive integer. The description's 'by id' adds nothing 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?

The description uses a specific verb+resource ('Permanently delete a time entry') and pins the target ('by id'), which cleanly separates it from list/get/create/update/restart/stop siblings in the same namespace. 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 warns that the action is irreversible ('This cannot be undone') but gives no guidance on when to delete versus alternatives such as harvest_stop_time_entry, harvest_restart_time_entry or harvest_update_time_entry. The warning is a caution, not usage routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the REST endpoint mapping (GET /clients/{id}), contributing marginal context; it says nothing about error behavior when the id is not found or what the payload contains.

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 sentences, front-loaded with the action and scope, with zero filler. Every word earns its place.

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

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

A simple single-id read tool with annotations covering safety and a fully documented parameter needs little more; the description is nearly complete for correct invocation. Only the absence of any return-shape note (no output schema) keeps it short of 5.

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 (client_id) is fully documented in the schema, so the description's 'by id' adds nothing new. Baseline 3 applies 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?

Specific verb+resource: 'Retrieve a single client by id', which contrasts with the sibling harvest_list_clients by scope. It is clear but does not explicitly name or differentiate itself from the list/other get_* siblings beyond the word 'single'.

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 by 'by id' – an agent can infer this is the lookup path when it already has a client id, but the description never states when to prefer it over harvest_list_clients or the other get_* tools, and gives no prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by naming the underlying REST call (GET /company) and previewing the payload, but says nothing about auth requirements, rate limits, or what happens when settings are unavailable.

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 front-loaded sentence that leads with the verb and scope, followed by a short REST mapping. Every clause earns its place and there is 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?

With no output schema, the description carries the return-value burden and does list representative fields (name, currency, formats, week start, feature flags). It is adequate for a simple read, though the field list is illustrative rather than exhaustive.

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 of 4 applies; there is nothing for the description to disambiguate. The description correctly conveys that no identifier is needed because scope comes from the authenticated account.

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 (Retrieve) plus resource (company/account settings) scoped to the authenticated account, and it enumerates the notable fields returned. It does not explicitly name any sibling tool, but the 'authenticated account' scoping implicitly separates it from harvest_get_client or harvest_get_project.

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: a zero-parameter getter of the account's own settings is fairly self-evident. There is no explicit when-to-use, no exclusion, and no pointer to a related sibling such as harvest_get_current_user.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does add two useful facts: identity is derived from the access token, and it maps to REST GET /users/me. It says nothing about auth failure modes or return shape, which keeps it at a modest 3.

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 and scope, with the REST endpoint as a compact trailing reference. 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 zero-parameter read-only lookup, the description covers scope and the underlying endpoint, which is enough for correct invocation. With no output schema, one might want a hint about what user fields come back, but that gap is minor for this simple resource.

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 there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no filtering or lookup input is needed.

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

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

States a specific verb ('Retrieve') and a precisely scoped resource ('the currently authenticated user (whom the access token belongs to)'), which cleanly separates it from the sibling harvest_list_users. An agent can tell instantly this returns one identity tied to the token, not a collection.

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 statement, but the scope wording ('currently authenticated user') implicitly tells the agent this is the identity-resolution call rather than harvest_list_users. No alternatives or exclusions are named, so the guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful return-content context ('including its line items'), which annotations cannot convey, but it omits error behavior (e.g., missing/invalid id) and auth requirements.

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 zero filler: the first states the action and return scope, the second gives the REST endpoint. Every element earns its place.

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

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

For a single-resource read with one fully documented parameter, readOnlyHint annotations, and no output schema, the description is nearly sufficient. The addition of line-item inclusion is helpful; only minor details like error handling 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 the single required parameter invoice_id is fully documented in the schema with type and constraint. The description's 'by id' adds no syntax or format 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 (Retrieve) and resource (a single invoice by id) and adds the scope qualifier 'single', which distinguishes it from the sibling harvest_list_invoices without naming it directly. The REST mapping (GET /invoices/{id}) further pins down the operation.

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

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

Usage is only implied: the word 'single' and 'by id' suggest this is for fetching one known invoice rather than listing, but no alternatives (e.g., harvest_list_invoices) or conditions are stated explicitly. No when-not guidance or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying REST mapping (GET /projects/{id}), which is useful orientation, but says nothing about error behavior for a missing/inaccessible project or permission requirements.

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 very short sentences, front-loaded with the action and resource, with no filler. Slightly terse rather than padded, which is appropriate for a simple getter.

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 getter with a fully documented single parameter this is nearly adequate, but with no output schema the description could at least hint at what a project record contains or that a missing id errors out.

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?

One parameter with 100% schema description coverage already documents project_id fully. The description's 'by id' adds no constraint, format, or example beyond the schema, so 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?

Specific verb ('Retrieve') and resource ('a single project'), with the lookup key ('by id') stated. It implicitly separates itself from harvest_list_projects by saying 'single', though it never names that sibling.

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

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

Usage is only implied: an agent can infer this is the point-lookup counterpart to harvest_list_projects. There is no explicit when-to-use/when-not statement or named alternative, so the routing signal is weak given 20 sibling tools.

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

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

The readOnlyHint annotation already tells the agent this is a non-mutating read, so the description's main addition is the REST endpoint mapping (GET /time_entries/{id}), which helps correlate with API docs. It says nothing about failure modes such as a missing/404 id or whether the entry is scoped to the authenticated user.

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, purpose first, endpoint second, with no filler or repetition. Nothing could be cut 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?

For a single-parameter read tool with an annotation covering safety, this is nearly sufficient; the only genuine gap is return/error behavior, since no output schema exists to document the shape of the returned time entry or the not-found case.

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

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

Schema coverage is 100% and the schema already documents time_entry_id as a required positive integer, so the description's 'by id' adds no new syntax or constraint information. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb ('Retrieve') and resource ('a single time entry') and pins the scope to one record by id, which separates it from harvest_list_time_entries. It stops short of naming any sibling explicitly, so it is clear but not fully 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?

Usage is only implied: fetch one entry when you already have its id. There is no statement of when to prefer this over harvest_list_time_entries with filters, nor any precondition (e.g. valid or accessible id).

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, so safety is covered structurally. The description adds that results are paginated and ties the call to a concrete REST endpoint, which is useful orientation, but it does not state result-size behavior or what a client record looks like.

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 fragments, front-loaded with the core action and filters before the endpoint detail. Nothing is redundant, though the telegraphic 'Paginated.' fragment is slightly clipped rather than elegantly brief.

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-required-parameter list tool with full schema coverage and a readOnly annotation, the essentials are present. However, with no output schema, the description gives no hint about the shape or volume of returned client objects, leaving an agent to infer the return surface entirely.

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 page, per_page, is_active, and updated_since are all documented in the schema itself. The description only restates two of the four filters and adds no syntax (e.g., ISO-8601 form) beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List clients') plus the filters it supports, and echoes the underlying endpoint (GET /clients). It is clearly distinguishable from harvest_get_client by the list-vs-single distinction, though it never names that sibling explicitly.

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 mention of optional active-status and updated-since filters implies the use cases (syncing recently changed records, separating archived from active clients), but there is no explicit 'use this instead of X when Y' guidance against harvest_get_client or the other list_* siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining burden is light. It adds two useful facts beyond annotations — that results are paginated and that the underlying call is GET /estimates — but says nothing about return shape, page-size ceilings, or rate limits.

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, no filler: purpose and filters first, then pagination, then the REST mapping. Every clause carries information and the scoping details are front-loaded.

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

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

For a zero-required-parameter read-only list tool with a fully documented schema and readOnlyHint covering safety, this is nearly sufficient; the pagination note is the one piece of context the schema cannot convey. Output schema absence is expected for a list endpoint, so 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%, so every parameter including formats (yyyy-mm-dd, ISO-8601), enum values, and page bounds is already documented in the schema. The description restates the same filter set without adding syntax or semantics beyond it, which is the baseline for this 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 ('List') and resource ('estimates') and enumerates the filter dimensions, so the agent knows exactly what comes back. The resource itself distinguishes it from sibling list tools like harvest_list_invoices or harvest_list_expenses, though the description never explicitly says so.

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 filter list implies when the tool is appropriate (broad listing with optional narrowing), but there is no explicit when-to-use guidance and no stated exclusions or alternative tool to prefer. Usage is inferable rather than directed.

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, so the safety profile is covered by structured data. The description adds that results are paginated and maps to the upstream REST call, which is useful context, but it does not disclose pagination limits, ordering, or default page size behavior 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?

Two tight sentences with zero filler; the core action and filters are front-loaded and the pagination/endpoint note follows.

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 could say more about the returned collection shape, but for a read-only listing tool with fully documented parameters and a readOnlyHint annotation, the filtering and pagination coverage is sufficient for correct invocation.

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

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

Schema description coverage is 100% with all nine parameters individually documented, so the schema carries the parameter burden. The description's filter list ('user, client, project, date range, billed status, updated-since') mirrors the schema without adding format, default, or interaction details.

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 expenses') and enumerates the available filter dimensions, so an agent knows exactly what the tool returns. It does not explicitly contrast itself with the other harvest_list_* siblings (time entries, invoices, projects), though those target different resources so ambiguity is low.

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

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

The description implies when the tool is useful ('optionally filtered by...'), but gives no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g. needing an account token), and no routing to an alternative for cross-resource retrieval.

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?

readOnlyHint=true already establishes the safety profile, so the description's burden is lighter. It adds 'Paginated' and the underlying REST endpoint (GET /invoices), which is useful for mapping, but says nothing about default page size, result ordering, or response shape beyond what the annotations and schema imply.

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, front-loaded with the core action and scope, then pagination and the API mapping. Nothing is redundant and 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?

For an all-optional, fully documented list endpoint with a readOnly annotation and no output schema, the description covers action, filters, and pagination. It omits sorting behavior and any hint of result volume, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so every parameter (to, from, page, per_page, state, client_id, project_id, updated_since) is already documented in the schema. The description's filter list mirrors those parameters without adding format or interaction detail, 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 ('List invoices') and enumerates the filter dimensions, which cleanly separates it from the sibling harvest_get_invoice (singular fetch). It never names an alternative tool explicitly, but the List/Get distinction is unambiguous.

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

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

The phrase 'optionally filtered by...' implies the tool's usage context, but there is no guidance on when to prefer this over harvest_get_invoice or how the filters interact. 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, so safety is covered. The description adds real value beyond that: results are limited to 'active' assignments (an implicit filter), the response is paginated, and the underlying REST endpoint (GET /users/me/project_assignments) is disclosed. No rate-limit or auth-scope detail, but solid context for a read tool.

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

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

Three compact sentences, front-loaded with the scope and purpose before the parenthetical pointer to harvest_create_time_entry. Nothing is padded or repeated from the schema/annotations.

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 sketches the return content (projects plus their assignable tasks) and flags pagination, which is the key thing an agent must handle. It does not describe the pagination envelope or per-item fields, a minor gap rather than a blocking one.

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

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

Schema description coverage is 100% for both parameters (page and per_page, including the 1–2000 range and default), so the schema carries the parameter burden. The description only adds the word 'Paginated', which is consistent with the schema but adds no new syntax or constraint detail. 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 (List) and a precisely scoped resource (the authenticated user's active project assignments), then expands what that means: the projects and their assignable tasks time can be logged against. This is clearly distinguishable from siblings like harvest_list_projects and harvest_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?

Explicitly routes the agent: use this to find the project_id + task_id needed by harvest_create_time_entry, which is a concrete downstream-use case absent from the sibling list tools. It does not, however, state when NOT to use it (e.g. vs. harvest_list_projects for a workspace-wide view).

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context beyond annotations – pagination exists and the call maps to GET /projects – but says nothing about rate limits, default page size behavior, or result shape.

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

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

Three short sentences, front-loaded with the core action, and each one carries distinct information: purpose, pagination, endpoint. 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?

A zero-required, all-optional read tool with full schema coverage and no output schema; the description covers purpose, filters, and pagination adequately. Only the absence of return-value hints or result-shape notes keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all five params including ranges and defaults. The description restates the filterable fields (active status, client, updated-since) without adding syntax or format detail, so 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 projects') and names the filter dimensions, plus maps to the underlying REST call. It distinguishes itself from harvest_get_project by the plural listing verb, though it never explicitly contrasts the two.

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 filters and the para 'Paginated', but there is no explicit when-to-use guidance, no statement of when to prefer harvest_get_project for a single project, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the agent knows nothing is mutated. The description adds that results are paginated and gives the REST mapping, but it discloses nothing about authentication requirements, rate limits, or the shape/size of a page beyond what the schema's page/per_page fields already imply.

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, all front-loaded: identity and scope first, filters second, pagination and endpoint last. Every clause carries information and there is no filler or repetition of the 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 read-only, annotation-covered list tool with a fully documented schema this is nearly complete, but there is no output schema and the description never indicates what a task record contains or whether results are a flat array. The pagination note partially compensates, leaving a modest gap for an agent that must reason about 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%, so page, per_page, is_active and updated_since are already fully documented with ranges and formats. The description restates the filter meaning (active status, updated-since) at a coarser level without adding syntax, defaults, or edge-case behavior, 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?

States a specific verb and resource ('List tasks') and immediately disambiguates the domain term by defining tasks as the billable/non-billable work categories assignable to projects, which prevents confusion with time entries or project assignments in the sibling set. It also pins the operation to a concrete endpoint (GET /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?

The description implies when the optional filters apply ('optionally filtered by active status or updated-since'), which gives some usage framing, but it never states when to reach for this tool versus other harvest_list_* siblings or whether prerequisites exist. With no competing task-listing tool, the guidance gap is moderate rather than severe.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's extra burden is low. It does add two useful facts beyond the annotation: results are paginated, and it maps to Harvest's GET /time_entries endpoint. No auth scopes, rate limits, or default-page behavior are disclosed.

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

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

Three short sentences, front-loaded with the purpose and filter list, then pagination, then the API mapping. No filler or repetition; each 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 read-only list with full param coverage and safe-read annotations, the description covers purpose, filtering, and pagination. Since there is no output schema, it could have said more about the shape of returned entries or page/envelope behavior, but nothing required 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%, so every one of the 11 parameters is already documented with type, pattern, and bounds. The description only re-enumerates the filter categories in prose, adding no format or interaction detail (e.g., from/to combining semantics) 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?

Specific verb ('List') + resource ('time entries') plus the full set of optional filters, which cleanly separates it from harvest_get_time_entry (single entry) and the other harvest_list_* siblings. 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 phrase 'optionally filtered by ...' implies the tool's role as a filtered collection read, but there is no explicit when-to-use guidance versus harvest_get_time_entry or when-not to use it (e.g., prefer get_time_entry for a known id). 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?

The readOnlyHint=true annotation already establishes this is a safe read, so the description only needs to add value beyond that. It does add useful context — pagination and the mapping to GET /users — but omits practical traits such as Harvest's rate limits, auth scope requirements, and what a page of results looks like. Reasonable 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?

Three tight clauses: resource+scope first, then filtering, then pagination and the REST path. Every sentence carries information and nothing is front-loaded incorrectly.

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, non-destructive read tool with a fully-documented schema and annotations covering the safety profile, the description is nearly sufficient; the only meaningful omission is any hint about the pagination response shape, which is arguably fine since no output schema exists but pagination semantics matter 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 page, per_page, is_active, and updated_since are already fully documented in the schema. The description only restates the filter concepts at a high level, adding no syntax, format, or defaulting detail beyond what the schema provides — the baseline 3 for a fully-covered 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 and resource ('List users in the account') plus the filtering scope and the underlying REST endpoint. It is unambiguous, though it does not explicitly contrast itself with any sibling tool (there is no competing user-listing tool in the sibling set, so the risk of confusion is low).

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

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

The description implies usage through 'optionally filtered by active status or updated-since', which tells the agent when the filters apply, and notes pagination. However, there is no explicit when-to-use/when-not guidance and no reference to alternative tools (e.g., harvest_get_current_user) for cases that do not need the full 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 only give destructiveHint=true; the description adds that it mutates data (WRITE), restarts/resumes the timer, and describes the failure mode if the entry is already running. That is meaningful behavioral context beyond the annotation, though it omits auth/rate-limit 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 tight clauses: what it does, the error condition, and the REST endpoint plus write marker. Front-loaded and nothing extraneous.

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 mutation with no output schema, it covers purpose, precondition, failure mode, and the underlying REST semantics. Output/response shape is unspecified, but that is minor.

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 only parameter is fully described in-schema as the stopped entry id to restart (positive integer). The description repeats 'previously stopped' without adding format or constraint details 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?

Specific verb (restart) plus resource (stopped time entry), and it names the complement sibling harvest_stop_time_entry by implication of 'previously stopped'. The error condition 'error if it is already running' further disambiguates it from create/update.

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?

Clearly states the operation applies to a previously stopped entry and errors if already running, so the agent knows the precondition. No explicit routing to alternatives like harvest_create_time_entry or harvest_stop_time_entry, but the precondition implies when it applies.

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 supply only destructiveHint=true, so the description adds meaningful behavioral context: the underlying REST call (PATCH /time_entries/{id}/stop), the fact that it is a write, and the non-idempotent error behavior when the entry is already stopped. It stops short of covering return payload, side effects on the timer, or auth requirements.

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, front-loaded fragments with no filler. The trailing 'WRITE — modifies data' partially duplicates the destructiveHint annotation, but the overall density is good.

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 mutation with no output schema, the description covers what the tool does, the state requirement, the error edge case, and the endpoint. Nothing an agent needs in order 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 description coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description adds only the implicit constraint that the id must reference a *running* entry, which is a marginal gain over the schema's 'running time entry id to stop'.

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 precise verb and resource ('Stop a currently running time entry'), which is unmistakably distinct from siblings like harvest_restart_time_entry, harvest_delete_time_entry, and harvest_update_time_entry. 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?

The parenthetical clarifies the state in which the call is valid ('currently running') and that an already-stopped entry produces a no-op error, which implies usage context. However, it never explicitly routes between this tool and its closest sibling, harvest_restart_time_entry, nor states prerequisites such as needing the entry to belong to the current user.

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

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

Annotations only supply destructiveHint=true and a title, so the description meaningfully adds PATCH-based partial-update semantics (unspecified fields are left untouched) and labels the operation WRITE. It still omits behaviors an agent would want for a mutation: permission requirements, whether approved/locked entries reject updates, and reversibility.

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 tightly packed segments: purpose and field list first, then the partial-update rule, then endpoint and write marker. No filler and the most decision-relevant information is front-loaded.

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

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

For a mutation tool with no output schema, the description covers scope, patch behavior, and the underlying endpoint, which is most of what an agent needs. Missing pieces are the update preconditions (locked/approved entries) and permission scope, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters with examples and constraints, which sets the baseline at 3. The description repeats a subset of the mutable field names and adds no format guidance (e.g., started_time/ended_time formats) 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?

States a specific verb and resource ('Update an existing time entry') plus the mutable fields (hours, notes, spent date, project/task), which clearly separates it from harvest_create_time_entry, harvest_delete_time_entry, and harvest_get_time_entry. It stops short of explicitly naming any sibling as the alternative, so it falls just under the top bar.

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: the patch semantics ('only the fields you provide are changed') tell the agent this is a partial edit of an existing record. However, there is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives such as harvest_stop_time_entry / harvest_restart_time_entry for active timers, and no prerequisites.

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