harvest

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

With only destructiveHint=true in annotations, the description adds essential behavioral context: 'WRITE — creates data' and the condition 'on a timestamp-tracking account' for running timers. It explains the OR exclusivity of hours vs. timestamps. It doesn't mention rate limits or detailed side effects, but given the sparse annotations, it does a solid job.

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

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

The description is four sentences, each with clear purpose: action+requirements, mode explanations, prerequisite pointer, and REST/write note. It is front-loaded with the core purpose and avoids redundancy with the schema, making it concise and well-structured.

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

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

Given 8 parameters, no output schema, and only destructiveHint annotation, the description covers the essential invocation modes, required fields, and a companion tool for discovery. It doesn't mention return value or error behavior, but for a create tool with rich schema descriptions, this is a minor gap. Overall it is sufficiently complete for selection and 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the mode-based relationships between parameters: hours vs. started_time/ended_time vs. timer (omitting both). It also reiterates required fields and points to a sibling for discovery. This integration guidance elevates it above baseline.

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

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

The description states 'Create a time entry' with a specific verb and resource, and differentiates from sibling tools like delete, update, and get by explaining the three creation modes (hours, timestamped, or running timer). It also names the prerequisite tool for finding valid IDs, making the purpose unmistakable.

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

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

The description provides explicit parameter combination guidance: 'Provide hours... OR provide started_time... OR omit both to start a running timer.' It also directs users to harvest_list_project_assignments for valid project_id + task_id, giving clear when-to-use and preparation steps. This is strong, actionable usage 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 include destructiveHint=true, and the description reinforces this with 'cannot be undone' and 'destroys data', adding permanence context beyond the simple destructive flag. Also mentions the REST endpoint and WRITE nature, which is useful but not required.

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, each earning its place: purpose, irreversibility, REST endpoint, and side-effect class. No fluff, front-loaded with the core action.

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

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

For a one-parameter delete operation, the description covers action, irreversibility, API method, and write nature. It doesn't explain error handling or prerequisites, but for this simple tool with no output schema, the description is sufficiently complete.

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

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

Schema has 100% coverage with a clear description for time_entry_id. The description only says 'by id' and adds no additional parameter semantics, so it relies on the schema – 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 the specific action: 'Permanently delete a time entry by id' – a clear verb+resource combination. The description distinguishes this from sibling tools like update, stop, or restart by emphasizing deletion and permanence.

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?

Implies usage (delete the entry you want removed), but does not explicitly state when not to use it or compare to alternatives. Given siblings like harvest_stop_time_entry, an explicit exclusion (e.g., 'to stop a running timer, use stop_time_entry instead') would improve guidance, but the irreversible nature is a clear signal.

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 signals this is a safe read operation. The description adds only the REST GET endpoint, which repeats the read-only nature. It does not disclose error handling, return format, or authentication requirements, providing minimal behavioral context beyond the annotation.

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

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

Two short sentences with no filler. The first sentence states the action, the second provides the REST endpoint. Every word contributes to the description.

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 single-parameter read-only operation with strong annotations and schema coverage, the description is sufficient. It clearly identifies what the tool does. The absence of an output schema is not a gap because the return value is implied by 'Get client' and the sibling list is present for context.

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

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

The input schema has 100% description coverage, with client_id described as 'The client id (required).' The description's 'by id' merely restates the schema information and adds no new meaning or parameter semantics.

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

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

Clearly states 'Retrieve a single client by id' with a specific verb and resource. The REST path 'GET /clients/{id}' reinforces the exact scope, and it is distinct from sibling tools like list_clients which retrieve multiple clients.

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

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

The phrase 'single client by id' implies this tool is for fetching one specific client, contrasting with list_clients, but there is no explicit guidance on when to use this versus alternatives. No exclusionary or conditional language is provided.

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

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

The readOnlyHint annotation already indicates a safe read operation, and the description adds context about the specific settings returned (e.g., currency, formats, feature flags). This goes beyond the annotation by clarifying the scope of data, though it does not mention response structure or size limits, which are less critical for a zero-parameter GET.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, lists illustrative fields, and includes the REST endpoint reference. Every word adds value with no redundancy.

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

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

Given the absence of an output schema, the description provides a helpful list of returned fields, which gives the agent an expectation of the response content. It does not explicitly state the response format (e.g., a company object), but it is adequate for a simple, parameterless read 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?

The input schema has zero parameters, so the baseline is 4. The description effectively communicates that no additional parameters are needed, and the schema coverage is trivially 100%.

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

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

The description uses a specific verb 'retrieve' and clearly identifies the resource as 'company/account settings for the authenticated account.' It distinguishes itself from sibling tools like get_current_user or get_client by specifying the scope (company/account-level) and listing concrete fields (name, currency, time/date formats, week start, feature flags).

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

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

The description provides clear context by stating it retrieves settings for the authenticated account, which implies use when company-level settings are needed. However, it does not explicitly mention when not to use it or name alternative tools, though the distinction from siblings is 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, and the description reinforces this with 'Retrieve'. It adds the behavioral detail that the user is tied to the access token, which clarifies the scope of the tool. For a zero-parameter GET endpoint, this is sufficient transparency, though it doesn't discuss rate limits or permission prerequisites.

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

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

The description is a single sentence plus an endpoint reference, with no unnecessary words. It is front-loaded with the core action and resource, making it easy for an agent to parse quickly.

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

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

For a parameterless read-only tool, the description fully explains what it does. It doesn't describe the return object, but the endpoint and resource imply a standard user object, and no output schema exists. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema is empty (100% schema description coverage), and the description correctly adds no parameter information. With zero parameters, the baseline is 4, and no further elaboration is needed.

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

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

The description uses the specific verb 'Retrieve' and clearly identifies the resource as 'the currently authenticated user (whom the access token belongs to)'. This distinguishes it from sibling get_* tools like harvest_get_client or harvest_get_company, which target different resources. The REST endpoint 'GET /users/me' further anchors its purpose.

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

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

The description clearly implies when to use this tool: whenever the agent needs the identity of the authenticated user. It does not explicitly mention alternatives or exclusions, but the context is unambiguous given the sibling tools. This earns a 4 rather than a 5 because there is no explicit 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?

The annotation readOnlyHint=true already signals a safe read operation, and the description reinforces this with 'Retrieve' and 'GET'. It adds useful behavioral context by noting the result includes line items, which goes beyond the annotation.

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

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

Two short clauses that get straight to the point: what it does and the underlying REST call. No filler words or redundant content. Example of concise, high-signal writing.

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

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

For a single-parameter read tool with a readOnlyHint annotation and no output schema, the description provides adequate context: it identifies the resource, the identifier, and notes that the response includes line items. It could go further by hinting at the invoice object structure, but it is sufficiently complete for this simple 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?

The schema has 100% coverage: the only parameter invoice_id is described fully ('The invoice id (required)'). The description adds no additional parameter-level detail beyond confirming the parameter is the invoice ID, which is already in the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Retrieve') and resource ('a single invoice by id'), and explicitly mentions 'including its line items', which distinguishes it from list_invoices and other retrieval tools. It 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 'single invoice by id' clearly signals when to use this tool (when you have a specific invoice ID and need a single invoice), and the REST endpoint adds context. However, it does not explicitly name alternatives or exclusions, so it falls just short of a 5.

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

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

The description adds no behavioral traits beyond the readOnlyHint annotation. It only repeats the REST endpoint and does not disclose behavior such as error handling, authentication requirements, or response format. With annotations present, the bar is lower, but zero additional behavioral context is provided.

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

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

The description is a single sentence that clearly conveys purpose and endpoint, with no redundant information. It is appropriately concise and structured.

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

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

For a simple get operation with one parameter and readOnlyHint, the description is mostly complete. It could mention the return value explicitly, but the absence of output schema and low complexity make the current description sufficient.

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

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

Schema coverage is 100% and the parameter description already explains project_id. The tool description adds no extra meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool retrieves a single project by id, using a specific verb and resource. It distinguishes itself from list_projects and other get tools by specifying 'single project by id.'

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

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

The description implies usage when a specific project id is known and a single project is needed, but it does not explicitly mention alternatives like list_projects for fetching multiple projects. No when-not-to-use guidance is provided.

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

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

The annotation readOnlyHint=true already covers the safety profile (read-only). The description adds only the REST endpoint path, which does not disclose additional behavioral traits such as what happens if the id is not found, rate limits, or permission requirements. It does not contradict annotations, but it also goes little beyond them.

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

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

The description is two sentences, each earning its place. The first sentence states the verb and resource; the second gives the REST endpoint for reference. There is no fluff or redundant phrasing.

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

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

Given the simple tool (one required parameter, no output schema) and the readOnlyHint annotation, the description is sufficient. It explains what the tool does and the id parameter is fully documented in the schema. It does not explain return values, but for a simple retrieval tool this is acceptable without 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?

The input schema has 100% description coverage for the single parameter (time_entry_id is described as 'The time entry id (required).'). The tool description does not mention the parameter or add extra meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Retrieve a single time entry by id') and the resource (time entry). It distinguishes from sibling tools like harvest_list_time_entries (plural) and mutation tools (create/update/delete) by emphasizing 'single' and 'by id'.

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

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

The description implies the use case: when you have a specific time_entry_id and need that one entry. It does not explicitly name alternatives (e.g., 'use list_time_entries for multiple entries'), but the context is clear enough that an agent would know when to invoke it. This is 'clear context, 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, covering the safe-read nature. The description adds that results are paginated and filterable, but these are also evident from the schema. No extra behavioral context such as rate limits, authentication requirements, or response shape is given. With annotations handling the main safety trait, a 3 is appropriate.

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

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

Two sentences, front-loaded with 'List clients', no filler. Every word earns its place.

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

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

For a simple read-only list tool with 100% schema coverage and a read-only annotation, this description is adequate. It includes the endpoint and filter/pagination hints. Minor gaps: no response format mention and no reference to harvest_get_client for single-client lookups, but these are not essential given the tool's simplicity.

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

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

Schema coverage is 100%, with each of the 4 parameters having its own description. The description restates 'active status or updated-since' and 'Paginated' without adding new meaning beyond the schema. Baseline 3 is correct.

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

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

The description uses the specific verb 'List' with resource 'clients' and mentions optional filters and pagination, clearly distinguishing it from get_client (single client) and other list_* tools. The REST endpoint reference reinforces the tool's scope.

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

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

Provides clear context: lists clients, can filter by active status or updated-since, and is paginated. It does not explicitly state when to prefer this over harvest_get_client or other list tools, but the list-vs-get distinction is implicit. Lacks explicit exclusions, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds 'Paginated' and the REST GET method, which reinforces read-only behavior, but does not disclose return formats, rate limits, or other execution details. This is adequate but not rich beyond annotations.

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

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

The description is three short clauses, front-loaded with the verb and resource, then filters, pagination, and endpoint. Every phrase adds value and there is no redundancy or filler.

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

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

For a read-only list tool with full schema coverage, the description captures the core operation, optional filters, pagination, and endpoint. However, with no output schema, it omits the response structure and default pagination limits, which are minor gaps for such a tool.

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

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

All 7 parameters are fully described in the input schema (100% coverage), so baseline 3 applies. The description groups them as 'client, state, date range, or updated-since' and mentions pagination, which loosely maps to page/per_page, adding slight semantic organization. No additional syntax or behavioral detail beyond the schema.

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

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

The description opens with 'List estimates'—a specific verb and resource—and enumerates optional filters (client, state, date range, updated-since) plus pagination. This clearly distinguishes it from sibling list tools (e.g., list_invoices) by naming the resource and its filter dimensions. The REST endpoint reinforces the scope.

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

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

The description implies usage context: use when you need to list estimates with optional filters. It does not explicitly name alternatives or exclusion criteria, but the resource name and sibling context make the appropriate use clear. Lacks an explicit 'when not to use' statement.

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 the description complements this with 'Paginated' and 'Harvest REST: GET /expenses,' reinforcing the non-mutating GET nature. It does not disclose rate limits, auth requirements, or return envelope, but the read-only annotation lowers the burden; this is adequate but minimal.

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

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

The description is two short sentences, each adding value: the first states the action and filter options, the second notes pagination and the REST endpoint. No filler or redundant elaboration.

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 operation, the description covers the core capabilities: filtering across all major dimensions, pagination, and the backing REST call. It omits the exact response structure (likely an array of expenses), but given there is no output schema and the annotation already marks it read-only, the description provides sufficient context for selection and basic 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?

All 9 parameters have descriptions in the schema, so the schema coverage is 100%. The description's phrase 'filtered by user, client, project, date range, billed status, or updated-since' summarizes the filter parameters, but adds no new meaning beyond the field-level schema documentation. 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?

Description opens with 'List expenses,' a clear verb+resource pair, and enumerates optional filters (user, client, project, date range, billed status, updated-since). It is easily distinguished from sibling list tools like list_projects or list_clients by the expense resource.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or fallback tools. Usage must be inferred from the plural 'List expenses' and the pagination note; there's no guidance like 'use this when retrieving expense records.'

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

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

Annotations already indicate readOnlyHint=true; description adds pagination and REST GET method, reinforcing non-mutating behavior. No contradictions.

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

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

Two short sentences; front-loaded with action and subject; every phrase adds value.

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

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

Description covers purpose, filters, and pagination; lacks explicit return format, but tool name implies list of invoices. Adequate for a read-only list tool.

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

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

Schema covers 100% of parameters with descriptions; description only summarizes filters ('client, project, state, date range, updated-since') without adding new syntax. 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' with resource 'invoices'; additional filter options clarify scope. Distinguishes from sibling list tools by resource (invoices vs clients/projects).

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

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

States it lists invoices and can be filtered by several criteria; implies use when needing an invoice list. Does not explicitly contrast with harvest_get_invoice or other list tools, but context is clear.

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

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

Annotations include readOnlyHint: true, so the read-only nature is already disclosed. The description adds valuable behavioral context: it filters to 'active' assignments, notes pagination, and specifies the REST endpoint (GET /users/me/project_assignments). No contradiction exists.

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

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

The description is concise and well-structured: first sentence states the core purpose, second explains the use case, then pagination and REST endpoint. Every sentence adds distinct value, with no redundant or filler content.

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

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

Despite having no output schema, the description conveys what the tool returns (active project assignments and assignable tasks) and why it's useful (finding IDs for time entry creation). Pagination is mentioned, and the REST endpoint gives a reference point. This is sufficient for a simple list tool.

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

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

Schema description coverage is 100% for both page and per_page, including details like default 2000. The description only mentions 'Paginated' without adding new parameter-specific information. Since the schema fully documents parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the authenticated user's active project assignments, specifying the exact resource (project assignments) and scope (authenticated user's active). It explicitly mentions the purpose of finding project_id and task_id for harvest_create_time_entry, distinguishing it from sibling tools like list_projects or 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?

The description provides clear when-to-use guidance: 'use this to find the project_id + task_id for harvest_create_time_entry.' This names a specific scenario and references a sibling tool, but it does not explicitly state when not to use this tool or compare it to alternative list tools, so it falls short of a 5.

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

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

The description discloses that the operation is a read (GET /projects), is paginated, and supports optional filters. The annotation readOnlyHint=true already indicates safety, and the description adds the pagination behavioral detail, which is useful beyond the annotation.

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

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

The description is a single, front-loaded sentence covering the core purpose, filters, and pagination, followed by a useful API reference. No wasted words.

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

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

For a list endpoint with a readOnlyHint annotation and complete parameter schema, the description adequately covers the tool's purpose and key behaviors (filtering, pagination). It lacks explicit return format details, but the simplicity of listing projects makes it sufficient.

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

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

The input schema provides full descriptions for all five parameters (page, per_page, client_id, is_active, updated_since), so the description need not repeat them. The description's mention of 'active status, client, or updated-since' merely summarizes the schema, adding no new semantic depth. Baseline 3 applies.

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

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

The description clearly states the tool lists projects, with optional filters for active status, client, and updated-since, and mentions pagination. This distinguishes it from sibling tools like harvest_get_project, which retrieves a single 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?

The description provides clear context: use this to list projects with filters and pagination. It does not explicitly exclude alternatives like harvest_get_project, but the 'list' action and filters make the intended use obvious.

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 marks the operation as safe. The description adds useful behavioral context: pagination behavior, filter availability, and the REST endpoint (GET /tasks). It does not disclose rate limits or response shape, but for a read-only list endpoint the added context is meaningful.

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

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

Two concise sentences front-load the purpose, define the resource, list optional filters, note pagination, and provide the REST endpoint. Every sentence adds valuable information with zero redundancy.

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

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

For a straightforward read-only list tool with well-documented parameters and no output schema, the description fully covers the necessary context: what is listed, filter options, pagination, and the endpoint. Sibling differentiation is implicitly handled by the unique resource type.

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

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

Schema description coverage is 100%, with each of the four parameters fully documented. The description mentions 'active status' and 'updated-since' which map to is_active and updated_since, but only restates what the schema already provides. It adds no new parameter-level semantics beyond the existing schema descriptions.

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

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

The description clearly states the action ('List tasks'), defines what tasks are ('billable/non-billable work categories'), and includes the API endpoint. This distinguishes it from sibling list_* tools since no other task-listing tool exists among siblings.

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

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

The description implies usage for listing task categories and clarifies optional filters (active status or updated-since). It doesn't explicitly state when not to use it, but with no competing task-list sibling, the context is clear and self-sufficient.

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

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

The readOnlyHint annotation already signals this is a safe read operation. The description adds 'Paginated' and the REST endpoint reference, which provides useful behavioral context without contradicting any annotations. A higher score would require disclosure of rate limits or auth specifics, but these are not critical for a simple list operation.

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

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

Two sentences, front-loaded with the core purpose, then listing filters compactly. Every word earns its place; no redundant or verbose content.

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

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

For a simple list tool with full schema coverage and readOnlyHint, the description covers the core purpose, all filter dimensions, and pagination. Although no output schema exists, the return value is inherently 'a list of time entries' and the REST endpoint is given. It could mention the response shape, but it's not essential for this resource type.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented. The description summarizes the filter dimensions (user, project, client, task, date range, running/billed, updated_since) but does not add new meaning beyond what the schema provides. It also omits pagination parameters (page, per_page) in the summary, though they are in schema.

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

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

The description clearly states 'List time entries' with a specific verb and resource, and the optional filters are enumerated. It distinguishes from sibling tools like harvest_get_time_entry (single entry), harvest_create_time_entry, and other resource-specific list tools.

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

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

Usage is implied for listing multiple time entries with optional filters, but no explicit when-to-use or exclusion guidance is provided. The description doesn't mention alternatives for single-entry retrieval, though the name and resource make it fairly obvious.

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 marks this as safe, and the description adds that the operation is paginated and supports optional filters (active status, updated_since), plus the underlying REST endpoint. This gives the agent behavioral context beyond the annotation without overexplaining.

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

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

The description is extremely concise—two short sentences—and front-loads the core action ('List users'), then adds filters, pagination, and the REST endpoint. Every word earns its place.

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

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

For a simple list tool with 4 optional params and no output schema, the description covers the main semantics (filters, pagination) and the read-only nature is covered by annotations. It doesn't describe the response shape, but the act of 'listing users' implies a user collection, and the presence of other metadata compensates.

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

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

The input schema provides 100% coverage for all four parameters with clear descriptions, so the baseline is 3. The description's mention of 'active status or updated-since' and 'Paginated' reinforces the param semantics, adding a slight extra layer of clarity.

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

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

The description clearly states the tool lists users in the account, using the verb 'list' with a specific resource. It differentiates from sibling list tools (clients, projects) by naming 'users' and also mentions optional filters and pagination, reinforcing the exact purpose.

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

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

The description provides clear context: use this to list all or filtered users in the account. Though it doesn't explicitly name alternative tools, the sibling tools are for different resources, and the description's focus on users makes the appropriate use case apparent. No exclusion criteria are given, but they aren't necessary here.

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

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

The description adds behavioral context beyond the destructiveHint annotation by stating the error condition and that it resumes the timer. It also includes the REST endpoint and WRITE operation, providing a fuller picture of the tool's behavior.

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

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

The description is concise and front-loaded with the purpose, followed by a key error condition and technical details. No redundant information or fluff.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential purpose, error behavior, and write nature. It could mention the return value, but this is not critical given the simplicity.

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

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

The schema description coverage is 100% for the single parameter time_entry_id, so the baseline is 3. The description does not add extra parameter semantics beyond what the schema already provides.

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

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

The description clearly states the specific action (restart), the resource (previously stopped time entry), and the effect (resuming its timer). It also distinguishes from siblings like harvest_stop_time_entry by explicitly noting the condition that it errors if already running.

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

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

The description implies the use case: restarting a stopped time entry, and notes the error condition if already running. It does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

Beyond the destructiveHint annotation, the description discloses the no-op error behavior and explicitly labels the operation as WRITE, adding valuable behavioral context beyond the structured annotation.

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

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

The description is concise with two short sentences plus the REST endpoint and WRITE tag. It is front-loaded with the core purpose and contains no wasted words.

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

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

For a simple one-parameter mutation with complete schema coverage and relevant annotation, the description covers the key behavior including the edge case. No output schema exists, so return details are not required.

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

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

The input schema already fully describes the single parameter as 'The running time entry id to stop (required)', so the description adds little extra meaning. Baseline 3 applies due to high schema coverage.

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

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

The description clearly states the specific action: stopping a running time entry. It distinguishes from related tools like restart_time_entry by specifying 'currently running' and the no-op error case.

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 explicitly says when to use (when a time entry is running) and when not (already stopped leads to no-op error), providing clear usage boundaries. It also implies the WRITE nature.

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 include destructiveHint=true, and the description adds that this is a PATCH request and 'Only the fields you provide are changed,' which explains the partial-update behavior. This is valuable context beyond the annotation, though it does not disclose side effects like permission requirements or whether updates are reversible.

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

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

The description consists of four short, purposeful sentences: action, partial-update behavior, REST endpoint, and write nature. It is front-loaded with the primary purpose and contains no redundant content.

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

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

While the schema documents all parameters and the annotation flags destructiveness, the description does not mention the response format (no output schema) or any operational constraints (e.g., updating a running entry). This leaves gaps for a tool with 8 parameters and no output schema documentation, making it adequate 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?

The schema has 100% description coverage for all 8 parameters, so the baseline is 3. The description's enumeration of fields ('hours, notes, spent date, or project/task') merely paraphrases the schema and does not add deeper semantics such as mutual exclusivity or formatting constraints beyond what the schema already provides.

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

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

The description states a specific verb ('Update') and resource ('existing time entry'), and lists the updatable fields ('hours, notes, spent date, or project/task'). This clearly differentiates it from siblings like create or delete, which are unambiguous.

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

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

The description says 'Update an existing time entry,' which implies use for existing entries, but it does not explicitly contrast with alternatives such as harvest_create_time_entry, harvest_restart_time_entry, or harvest_stop_time_entry. The partial-update note provides context, but no explicit 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.