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

Annotations already include readOnlyHint: true, covering the safety profile. The description adds value by listing the exact data returned (name, email, id, roles, timezone) and indicating it can be used to verify connectivity, which enriches behavioral understanding 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 two sentences: the first states the core function and return fields, the second gives practical use cases. There is no redundancy or unnecessary detail, making it efficient and 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?

Given the simplicity of the tool (no parameters, no output schema), the description fully covers the necessary context: what data is returned, how it can be used to resolve 'my' entries, and as a connection check. No significant gaps remain.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty), so the baseline is 4. The description does not need to explain parameters; instead, it adds context about the output fields and use cases, which is sufficient.

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

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

The description clearly states the tool's purpose: to get the authenticated Harvest user with a specific list of fields (name, email, id, roles, timezone). The verb 'Get' and resource 'authenticated Harvest user' are specific, and it distinguishes from sibling tools like list_users by focusing on the current user.

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

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

The description provides a clear use case: 'resolve my time entries and check the connection.' This implies when to use the tool, though it does not explicitly name alternatives. It offers enough context for an agent to decide to use it for current-user identification.

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

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

Annotations declare readOnlyHint=true, which already conveys this is a safe read operation. The description adds useful behavioral detail: it returns aggregated hours, includes billable vs total hours, and billable amounts only when permitted. This goes beyond the annotation without contradicting it.

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

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

The description is two sentences with no wasted words. The first sentence front-loads the core function and options; the second gives a natural-language example. Every phrase earns its place.

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

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

Although there is no output schema, the description tells the user what the report contains (aggregated hours, billable/total hours, billable amounts) and how it can be grouped. This is enough for a simple reporting tool with only three parameters, though it does not specify response format or pagination, which is a minor gap.

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

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

The input schema covers 100% of parameters (from, to, group_by) with clear descriptions, including enum values for group_by. The description adds only a slight restatement ('date range', 'grouped by'), which is minimal extra value over 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 clearly states the tool aggregates hours over a date range with grouping options (clients, projects, tasks, team members), and the title 'Time report' reinforces this. It is distinct from siblings like list_time_entries (detailed entries vs aggregated summary) and log_time (write vs read).

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

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

The description provides a concrete use case ('how many hours did we spend on X this month?') and implies it is for reporting/aggregation rather than listing individual entries or logging time. However, it does not explicitly name alternatives or state when not to use this tool, 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 readOnlyHint annotation already signals that the operation is safe. The description adds that the response includes id, name, and active state, but it does not disclose other behavioral nuances such as default filtering (though the schema covers active_only's default). This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that states the action and the output fields. There is no wasted wording or redundancy, earning full marks.

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

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

For a simple list tool with one optional parameter, the description is sufficiently complete given the annotations and schema. The return fields are specified, and the tool's low complexity means few gaps remain. A half-point is lost for lacking any mention of pagination or edge cases, though this is not critical.

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

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

The schema provides 100% coverage of the sole parameter with its description ('Only active clients (default true)'), so the description need not add parameter semantics. The description adds no extra meaning beyond the schema, matching the baseline.

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

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

The description clearly states the tool's function with a specific verb ('List') and resource ('clients in the Harvest account'), and it distinguishes the resource from sibling tools that list other entities. However, it lacks explicit scoping or differentiation statements, so it does not fully earn a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or when not to use it. The sibling tools are unrelated resources, but no explicit usage guidance is given.

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

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

The readOnlyHint annotation already declares this as a safe read operation. The description adds that projects are listed with budget info and can be filtered, but does not discuss pagination, default sort order, or other behavioral details. It neither contradicts annotations nor provides substantial extra transparency.

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

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

The description is a single sentence, front-loads the main action, and includes no redundant information. It is highly concise.

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

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

For a list tool with two documented parameters and a readOnlyHint, the description adequately conveys the purpose and basic filtering options. Missing pagination or return-structure details are minor 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?

Both parameters are fully described in the schema (client_id and active_only with defaults). The description mirrors the filtering capability but does not add new syntax or format details, 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?

The description states a specific verb ('List') and resource ('projects'), and specifies the information returned ('client, code, and budget info'). This clearly distinguishes it from sibling tools like list_project_tasks or list_time_entries.

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

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

The description gives clear context for filtering by client_id and including archived projects, which are parameters. However, it does not explicitly mention when to use this over alternatives such as list_project_tasks or list_clients, nor does it state any exclusions. So guidance is clear but lacks explicit differentiation.

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 read-only behavior is covered. The description adds the functional output (task_id + name) and the prerequisite for time logging, but does not disclose other behaviors like pagination, filtering, or whether it returns all tasks. This is acceptable for a simple read-only tool but not exceptionally informative.

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

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

The description is two short sentences, front-loaded with the verb and resource. The first sentence states the action and output; the second sentence provides essential context for its use. 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?

The tool is simple with one parameter, a read-only annotation, and no output schema, so the description does not need to explain return values. It explains the practical purpose (getting a task_id for time logging) and is therefore sufficiently complete for this complexity level. Minor missing details like scope or limitations are not critical 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?

The schema covers 100% of the parameter details: project_id is a required number with a clear description ('The Harvest project id'). The description does not add additional parameter semantics, but the schema already provides full clarity, so a 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 the tool lists task assignments for a project, specifying the exact fields returned (task_id + name). It distinguishes itself from sibling tools by focusing on tasks rather than time entries or projects, and connects to the workflow of needing a task_id before logging time or starting a timer.

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 explains when this tool is needed ('to log time or start a timer on that project'), which directly guides the agent to use it before invoking log_time or start_timer. It does not explicitly exclude alternative tools, but the context is clear enough for a simple list operation.

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

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

With the readOnlyHint annotation already signaling safety, the description adds valuable behavioral details: newest-first ordering, the 300-entry per-call limit, and filter capabilities. It does not expose potential rate limits or pagination nuances, but the added context 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?

The description is two sentences, front-loaded with the core action and ordering, then enumerates filters and the limit. Every word earns its place with no redundancy 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 read-only list tool with 6 optional parameters and no output schema, the description covers the essential behavior: listing, ordering, all filter options, and the page size limit. It omits pagination behavior (what happens when more than 300 entries exist), but the core functionality is well-covered for an agent to invoke correctly.

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

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

Schema coverage is 67% (4/6 params have descriptions), so the description partially compensates. It explicitly lists all filter dimensions and clarifies date format (YYYY-MM-DD) and the mine=true semantics. It does not deeply explain user_id/project_id, but theirnames are self-explanatory and the filter list is helpful.

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 resource and action, and adds 'newest first' for ordering. It does not explicitly differentiate from sibling tools like list_project_tasks, but the name and resource are unambiguous. A sibling-differentiating phrase would earn a 5.

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

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

The description provides clear context on how to use the tool: filters by date range, project_id, user_id, or only_running, and the mine=true option. It does not explicitly state when to use an alternative tool (e.g., get_time_report for aggregates), but the usage scenarios are well implied by the parameter descriptions.

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 adds value by disclosing the required permission level (admin/manager) and the specific output fields (id, name, email, roles). This goes beyond the annotation without contradicting it.

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

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

The description is two sentences, front-loaded with the core action and resource, then includes usage context and access requirements. Every sentence earns its place with no redundancy.

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

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

The tool is simple (one optional parameter, no output schema). The description covers the returned fields, usage purpose, and access requirements, which is adequate for an agent to select and invoke it. It does not mention pagination or ordering, but these are not critical 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?

The input schema already provides 100% coverage for the single parameter 'active_only' with a clear description. The tool description does not add any parameter-specific detail, so it relies fully on the schema, meeting the baseline but not exceeding it.

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

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

The description clearly states the verb 'List' and the resource 'users in the Harvest account', and specifies the returned fields (id, name, email, roles). This distinguishes it from sibling tools like list_clients and list_projects, which target different resources.

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

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

It provides clear usage context: 'Needed for per-person filters and team reports', and mentions the access prerequisite (admin/manager access). However, it does not explicitly state when not to use it or name alternative tools, so it misses the top bar for 'when-not/alternatives'.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds that the entry is 'completed' (as opposed to running), and instructs to add a note, which is a behavioral expectation not captured by annotations.

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

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

The description is two sentences, front-loaded with the main purpose and prerequisite. Every sentence earns its place with no filler or redundancy.

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

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

It covers the workflow (list tools first), all required fields, and the optional note. With annotations covering the safety profile and schema covering most formats, the description is sufficiently complete for this simple 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?

The schema documents hours, notes, and spent_date, but leaves project_id and task_id undocumented. The description fills this gap by mentioning 'project, task' and instructing to get IDs, clarifying they are ID references. It also provides an example for hours format.

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 ('Create') and resource ('completed time entry'), distinguishing it from siblings like start_timer by emphasizing 'completed'. It lists the key fields (project, task, date, duration), making its purpose unambiguous.

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

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

It explicitly instructs to call list_projects and list_project_tasks first to obtain IDs, which is a clear prerequisite for correct usage. It doesn't explicitly exclude start_timer or update_time_entry, but the 'completed' qualifier provides enough context to differentiate.

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 annotations (readOnlyHint=false, destructiveHint=false), the description discloses that any other running timer is stopped automatically, a meaningful side effect. It also notes the scope ('for today') and authentication requirement, adding useful context without contradicting the annotations.

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

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

Two sentences: the first states the action and scope, the second provides the side effect and a prerequisite. It is front-loaded and contains no unnecessary words.

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

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

For a simple timer tool, the description covers the main behavior, a critical side effect, and a prerequisite for one parameter. It does not discuss error conditions or return values, but given the absence of an output schema and the presence of annotations, this is acceptable.

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 only 33% (only 'notes' has a description). The description adds semantic value by indicating that task_id should be obtained from list_project_tasks, but it does not explain project_id beyond the name. It partially compensates for the low schema coverage but leaves a gap.

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 ('Start a running timer'), the resource ('a project + task for today'), and the authentication context ('authenticated user'). It distinguishes from siblings like stop_timer and log_time by specifying 'running timer'.

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 usage context: it is for the authenticated user's timer for today, and it explicitly mentions that any other running timer is stopped. It also directs users to list_project_tasks to obtain task_id, which is a helpful prerequisite. However, it does not explicitly differentiate from log_time (manual entry) as an alternative.

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

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

Annotations already indicate a non-read-only action. The description adds the auto-find behavior for the currently running timer but fails to disclose what happens if no timer is running or if the timer is not owned by the user, which is a notable 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?

The description is two sentences, front-loaded with the primary action, and contains no fluff. Every word earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description sufficiently covers main behavior and conditional logic. It could mention error cases, but overall completeness is adequate 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%, providing a baseline of 3. The description adds valuable meaning to the optional parameter by explaining what happens when time_entry_id is omitted (auto-find current timer), exceeding 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 clearly states the tool's function: 'Stop a running timer.' It is specific and distinct from siblings like start_timer or log_time, with a clear verb+resource structure.

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 explains the conditional usage when time_entry_id is omitted, providing context for when to use this tool. It implies use for stopping timers but does not explicitly contrast with alternatives like update_time_entry.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds valuable context by stating partial-update behavior and the intentional absence of a delete tool, which informs the agent of workarounds. It does not contradict annotations, and the added context goes beyond the structured safety hints.

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 sentences: purpose, behavior, and contextual note. Every sentence earns its place, with no fluff. The key information is front-loaded, and the structure is tight and clear.

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

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

Given the tool's moderate complexity, the presence of annotations, and absence of an output schema, the description covers the essential usage: what is edited, partial update semantics, and the no-delete policy. It does not mention return values or error handling, but for a straightforward update tool this is acceptable. The description is sufficiently complete for an agent to select and invoke the tool.

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

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

Schema coverage is only 17% (only spent_date has a description). While the description lists editable fields and explains partial updates, it does not explicitly map 'date' to spent_date, nor does it mention the required time_entry_id or constraints like hours > 0. It partially compensates for low coverage but leaves gaps that the schema alone does not fill.

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 starts with a specific verb and resource: "Edit an existing time entry's hours, notes, date, project, or task." This clearly identifies what the tool does and lists the editable fields. It also distinguishes itself from siblings by noting the absence of a delete tool, reinforcing that this is for editing not deleting.

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 partial-update guidance ("Only provided fields are changed") and explicit alternatives for deletion ("set hours or move entries instead, and delete in Harvest itself"). However, it does not explicitly contrast with log_time or start_timer for creating new entries, so it stops short of a full when/when-not differentiation.

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