WakaTime MCP by usefulapi

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

Annotations already declare this is a read-only, non-destructive operation. The description adds useful behavioral detail by explaining that the result includes total time, daily average, and the covered date range, which helps set expectations in the absence of an output schema.

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

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

The description is a single front-loaded sentence followed by the endpoint path. Every element earns its place: scope, return contents, optional project effect, and API route.

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 tool with no output schema, the description adequately explains what is returned: total coding time, daily average, and covered range. It could define the daily-average denominator more precisely, but the core behavior is clear and 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 already documents the project parameter at 100% coverage with 'Only this project's total.' The description adds meaning by clarifying that the project option changes the scope to that project's creation date, which is more specific than the schema alone.

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

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

The description states a specific verb and resource: total coding time since the account or project was created, with daily average and covered range. It clearly distinguishes this all-time total from date-range siblings like get_stats and get_summaries.

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 when this tool applies: all-time total since account or project creation. It does not name alternatives or exclusions, but the scope itself makes the appropriate use case evident to an agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two non-trivial behaviors not present in structured fields: the required OAuth scope and the exact upstream route, and it hints at the returned data (time spent coding). It stops short of describing response shape or error behavior.

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

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

Three short sentences with zero filler: purpose first, auth prerequisite second, endpoint last. Every sentence contributes distinct information and nothing is repeated from the schema.

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

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

With no output schema, the description carries some burden for return values and does note the time-spent data, though not its fields. Combined with full schema coverage, annotations covering the safety profile, and the explicit scope requirement, an agent has enough to call this correctly; only the response structure is thin.

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 hash, branch and project semantics (formats, defaults, source of values) are already fully documented in the schema. The description adds no parameter-level detail beyond naming the hash, so the baseline 3 applies.

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

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

States a specific verb and resource ('One commit of a WakaTime project by hash') plus the payload it returns ('the time spent coding on it'), which cleanly separates it from the sibling wakatime_list_commits. An agent can identify the tool without opening the schema.

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

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

It gives a real prerequisite ('Needs the read_heartbeats scope for OAuth tokens') and pins the underlying endpoint, which is useful context for invocation. However, it never states when to reach for this versus wakatime_list_commits; the alternative is only implied through the schema's hash description, so the routing guidance is incomplete.

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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds the OAuth scope requirement (read_heartbeats) and the exact REST endpoint, which is genuinely useful context not present in annotations or schema. Still silent on rate limits and pagination.

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 efficient sentences with the resource and returned fields front-loaded, followed by the auth requirement. The trailing GET /users/current/durations is largely redundant for an agent since the tool is already identified by name, but it costs little.

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

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

With no output schema, the description compensates by describing the returned item shape (start time, length, project/slice), and it covers the auth scope. An agent has enough to call it correctly; only edge behavior like result volume or pagination is unaddressed.

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

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

Schema coverage is 100% across all 7 parameters, including the enum for slice_by and per-field defaults, so the schema carries parameter meaning. The description's mention of 'project (or other slice)' loosely signals slice_by but adds no syntax or format detail beyond what the schema already states. Baseline 3 applies.

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

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

States a specific resource and scope: 'coding sessions (durations) of one day', and enumerates the returned fields (start time, length in seconds, project/slice). This clearly separates it from aggregate tools like get_summaries or get_stats, though it never names a sibling explicitly.

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

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

Provides a real prerequisite ('Needs the read_heartbeats scope for OAuth tokens') and the underlying endpoint, which helps an agent predict behavior. However, it gives no guidance on when to pick this over get_heartbeats or get_summaries, so selection is left to inference.

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

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

Annotations already declare readOnly/non-destructive, so the burden is lower. The description adds genuinely useful behavior beyond them: results are cached, and an empty chart signals the cache is still building with a retry suggested. It stops short of noting auth scope or failure modes.

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

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

Two tight sentences with zero filler; the resource, its scope, and the cache caveat are all front-loaded before the raw endpoint reference.

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

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

With no output schema, the description carries the return shape burden and does describe the chart data plus a key edge case (empty chart). It is nearly complete for a single-resource getter, though it omits any note on what a goal object contains or error handling.

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 goal_id description already tells the agent the id comes from wakatime_list_goals. The description adds no further syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: retrieves "One goal by id with its chart data." The "by id" scope cleanly distinguishes it from the sibling wakatime_list_goals, and the included raw path (GET /users/current/goals/{goal}) pins down the exact operation.

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

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

Usage is only implied: the tool takes a single goal_id, so the agent infers it is for fetching one known goal rather than listing. It never explicitly says when to prefer this over wakatime_list_goals or what precondition (having a valid id) is required.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered; the description adds genuinely new context: truncation behavior ('Large days are cut to `limit` heartbeats starting at `offset`'), the total_heartbeats count, and the required read_heartbeats scope. Return shape is only partially described, and pagination ordering is not explicit.

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

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

Three sentences, front-loaded with the resource definition and ending with the endpoint and auth requirement. The middle sentence is dense with pagination facts, and the field enumeration in sentence one is list-like, but nothing is wasted.

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

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

With no output schema, the description usefully enumerates returned fields (entity, type, category, project, branch, language, time, lines, AI line changes) and covers pagination and auth. It is nearly complete for a single-parameter-required read tool, though it never states ordering of heartbeats or the concrete truncation default interaction.

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

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

Schema description coverage is 100%, so the schema already explains date, limit (default 200) and offset (slice busy days, default 0). The description reinforces the limit/offset interplay but adds no format or constraint detail beyond the schema, so the 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?

Names a specific resource ('the raw heartbeats') and defines the jargon inline ('activity pings from editor plugins') of one day, then enumerates the fields returned. An agent can distinguish this from aggregate siblings like get_summaries, get_durations, and get_stats by the word 'raw' and the day 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?

Usage is implied (fetch raw pings for a single day, slice busy days with limit/offset) and the OAuth prerequisite ('Needs the read_heartbeats scope for OAuth tokens') is stated, but there is no explicit when-to-use/when-not guidance relative to siblings such as get_durations for the same day.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context on what each insight_type yields (per-weekday averages, per-day totals) and the endpoint path, but says nothing about permissions, rate limits, or response shape.

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

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

A single dense sentence that front-loads the returned data types and ends with the route template; no filler sentences, and the per-parameter qualifiers are kept inline in parentheses.

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 5-param, no-output-schema read tool, the description covers the primary discriminator (insight_type) and its variants. Minor gaps remain: it doesn't clarify that timeout and writes_only act as global filters across insight types.

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 80%, so most parameters are self-documenting. The description goes beyond the schema by explaining the semantics of the otherwise undescribed insight_type enum values (days = per-day totals with optional weekday, weekdays = average per weekday), which is the key parameter for steering the call.

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

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

The description gives a specific verb+resource ('One WakaTime insight for a range') and enumerates the supported insight types, so an agent knows exactly what the tool returns. It stops short of differentiating itself from siblings like wakatime_get_stats or wakatime_get_summaries, leaving the overlap ambiguous.

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

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

Usage is only implied by the insight_type enumeration and the 'weekday is only for days' note; there is no explicit statement of when to choose this tool over get_stats, get_summaries, or get_durations. Adequate but no when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete REST endpoint it wraps and, usefully, the shape of the result ('grand total plus breakdowns per member'), which is not in any output schema. It says nothing about auth requirements, rate limits, or pagination, so it is adequate rather than 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?

One tight sentence with the scope front-loaded, followed by the endpoint. Nothing is wasted, though the raw URL path adds little to tool selection and borders on filler.

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

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

With no output schema, the description's note about the grand total plus per-member breakdown is the only signal an agent gets about return content, and it supplies it. Combined with fully covered parameters and annotations, only secondary details (auth, limits, empty-day behavior) are missing.

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

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

Schema description coverage is 100%, so the four/five parameters (org_id, dashboard_id, date, project, branches) are already documented, including the 'needs project' constraint on branches. The description adds nothing about parameter meaning or the interaction between project and branches, so the baseline 3 applies.

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

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

The description gives a concrete verb+resource+scope: one day of coding activity for every developer on a named org dashboard, with grand total plus per-member breakdowns. It implicitly separates itself from wakatime_get_org_member_summaries (per-member) and wakatime_get_summaries (personal), but never names those alternatives explicitly.

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

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

There is no when-to-use guidance, no prerequisites (e.g., dashboard must exist, membership required), and no exclusions. The scope phrase 'for every developer on an organization dashboard' hints at the situation, but the agent must infer it rather than being told when to pick this over the similarly named org/member summary tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint path and the date-range selection rule; it discloses nothing about pagination, rate limits, or the size/shape of the returned summaries. With annotations carrying the safety load, this is a minimum-viable 3.

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

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

Two short sentences with the core purpose front-loaded and the endpoint trailing. The endpoint path is marginally redundant for invocation, but nothing is bloated and no sentence is wasted.

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 summary tool with 100% schema coverage and no output schema, the definition supplies the date-range mechanics and identifies the member source via the schema. The remaining gap is explicit differentiation from the closely named sibling dashboard-summary 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%, so all 8 parameters are already documented, and the description's 'give start and end, or a named range' merely echoes the schema's start/end/range fields. No additional syntax or constraint meaning is contributed 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 states a specific verb and resource ('One dashboard member's coding activity as daily summaries') and scopes it with a date range. Writing 'One dashboard member's' distinguishes it in spirit from the dashboard-level wakatime_get_org_dashboard_summaries and the user-level wakatime_get_summaries, though it never names those siblings explicitly.

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

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

The only conditional guidance ('give start and end, or a named range') concerns parameter selection, not tool selection. There is no statement of when to prefer this member-level tool over wakatime_get_org_dashboard_summaries or wakatime_get_summaries, and no prerequisites.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so safety is covered; the description adds real non-obvious behavior by disclosing that omitting 'page' starts at the user's own page and that results can be broken down per language, country and board type. It stops short of documenting pagination termination or result size.

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

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

A single dense sentence front-loads what the tool returns, then adds the paging caveat and the endpoint. Nothing is wasted, though the semicolon-chained clauses and parenthetical require a second read.

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

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

With no output schema, the description carries the return-shape burden and does so by listing rank, member and coding time by dimension. Combined with the paging note and endpoint, an agent has enough to call it correctly; only pagination limits remain unstated.

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

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

Schema description coverage is 100%, so every parameter including the board_type enum is already documented in the schema; baseline 3 applies. The description adds only a light mapping of the grouping dimensions (language, country, board type) to the output, which the schema largely already conveys.

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

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

The description names a specific verb+resource ('The ranking of a private leaderboard') and enumerates the returned fields (rank, member, total coding time). The word 'private' plus the endpoint path GET /users/current/leaderboards/{board} distinguishes it from sibling wakatime_get_public_leaders without opening either schema.

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

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

Usage is implied rather than stated: it notes paging behavior and the board_id description points to wakatime_list_private_leaderboards as the source. However, it never says when to choose this over the public-leaders sibling or the leaderboard-listing tool, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context: the 7-day window, pagination, and a summary of fields returned per leader (rank, name, username, country, total and daily-average time, top 3 languages), which matters since no output schema 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?

Dense and front-loaded: purpose first, filters and paging second, return shape third. The trailing 'GET /leaders.' is minor API trivia but harmless, and every sentence otherwise 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 5-parameter, no-output-schema tool the description is nearly complete: it covers scope, filterability, pagination, and the returned fields per row. The only gap is the absence of explicit routing versus the private-leaderboard sibling.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the filter dimensions (language, country, hireable badge, ranking type) that the schema already fully documents, adding no syntax or semantic detail beyond 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?

States a specific verb and resource ('public leaderboard of the most active coders') plus scope ('over the last 7 days'). The word 'public' implicitly distinguishes it from the sibling wakatime_get_private_leaderboard, so an agent can tell them apart without opening either schema.

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

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

Usage is implied by the filters and time window, but there is no explicit when-to-use guidance or routing to alternatives. Notably it never says 'for authenticated/team boards use get_private_leaderboard', which is the obvious alternative a caller would weigh.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds genuinely useful behavioral context not in the structured fields: the response may indicate the stats are still calculating, in which case the agent should retry shortly. This async caveat is exactly the kind of trait annotations can't express.

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 content enumeration is front-loaded and the async-retry caveat plus endpoint reference follow compactly. Nothing is wasteful, though the trailing 'GET /users/current/stats/{range}' adds little an agent needs to invoke the tool.

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

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

With no output schema, the description carries the burden of describing return values, and it does so by listing the returned dimensions. Combined with the retry behavior, an agent has enough to call and interpret the result; only pagination/response size limits are unaddressed.

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

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

Schema description coverage is 100%, so the range, timeout and writes_only parameters are fully documented in the schema itself, including the range pattern and defaults. The description adds no parameter syntax beyond naming dimensions, which is the expected baseline when the schema does the heavy lifting.

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

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

The description names a specific verb (get aggregated coding stats) and enumerates the exact breakdown dimensions returned — total time, daily average, best day, AI vs human line changes, language, project, editor, OS, category, dependencies and machine. That is far more specific than the title 'Get coding stats', though it never names the sibling wakatime_get_summaries it likely overlaps with.

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

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

There is no guidance on when to use this tool versus alternatives such as wakatime_get_summaries or wakatime_get_all_time_since_today. The only procedural note ('call again shortly') is about retry behavior, not tool selection, so usage is left entirely to inference from the sibling list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the response is cache-backed and may legitimately be empty while the cache populates, which is exactly the kind of behavior an agent cannot infer from 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 compact sentences plus the REST endpoint, all front-loaded with the payload contents first and the caching caveat second. Nothing is redundant, though the endpoint path is marginally decorative for an agent that only needs the call semantics.

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

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

With no output schema, the description must sketch the return value, and it does: grand total plus breakdowns by project, language, editor, and more. Combined with the caching caveat, an agent has enough to invoke and interpret the call, though the exact nesting of the breakdown lists remains unspecified.

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

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

Zero parameters, so the schema imposes nothing to document and the baseline is 4. The description correctly spends no words on parameters and instead describes the response shape.

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

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

The description gives a specific verb and resource — today's coding activity with grand total and breakdowns by project, language, and editor — which is clearly narrower than siblings like get_summaries or get_all_time_since_today. It stops short of explicitly naming the sibling alternative for non-today ranges, so an agent must infer the contrast from the date scope alone.

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

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

It supplies one meaningful usage caveat: this returns cached data only, and an empty summary means the cache is still filling. That tells the agent how to interpret an unexpected empty result, but there is no guidance on when to prefer this over get_summaries or get_stats for overlapping date ranges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. With no output schema, the description carries the return-shape burden and does so well: it names the breakdown dimensions plus cumulative total and daily average, and discloses the conditional behavior that project+branches additionally yields per-branch and per-file entities. Auth/rate-limit behavior is not mentioned.

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

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

Three sentences, no filler, and the payload/return structure is front-loaded before the input mechanics. The trailing endpoint string 'GET /users/current/summaries' is useful for routing but is the one element that serves the implementer more than the caller.

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

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

For an 8-parameter, zero-required read tool with no output schema, the description covers what the call returns, how to specify the window, and the non-obvious project+branches interaction. The remaining parameters are fully documented at 100% schema coverage, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, which sets a baseline of 3, but the description adds meaning the schema does not: project combined with branches produces extra per-branch and per-file entities, and start/end are presented as one option against a named range. The remaining parameters (timeout, timezone, writes_only) are left entirely to the schema.

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

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

States a specific verb and resource ('coding activity as one summary per day for a date range') and enumerates what the summary contains: grand total, breakdowns by project/language/editor/OS/category/dependencies/machine, cumulative total, daily average. It does not explicitly distinguish itself from siblings such as wakatime_get_stats or wakatime_get_org_dashboard_summaries, so an agent must infer the boundary.

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?

'Give start and end, or one named range' tells the agent how to parameterize, but never says when this tool is the right choice versus wakatime_get_stats, wakatime_get_durations, or the org dashboard summary variants. Usage is implied by the scope statement rather than stated, and no prerequisites or exclusions appear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful non-annotation context: the result is scoped to the API key's owner and the exact set of returned fields (including last heartbeat time, which implies a live/latest-state read). It does not discuss rate limits or invalid-key behavior, but for a simple authenticated GET that is a minor omission.

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

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

One dense sentence plus the endpoint reference, with the resource identity front-loaded and the field list immediately after. No filler, no restatement of the title or annotations, and every clause carries information.

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

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

There is no output schema, so the description carries the return-value burden itself – and it does so by enumerating the fields, which is exactly what an agent needs before deciding to call it. What is missing is only peripheral: no note on authentication failure (invalid/expired key) or caching/rate-limit behavior. For a zero-parameter read bounded by explicit safety annotations, this is nearly 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 tool takes zero parameters, so the baseline is 4 per the rubric. The description correctly offers no parameter guidance because there is nothing to parameterize; all of its detail goes to the result shape instead.

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

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

The description names a specific resource ('The WakaTime user this key belongs to') and enumerates the exact fields returned (id, username, display name, email, timezone, plan, last plugin/project/branch, last heartbeat time). It also pins the underlying endpoint, GET /users/current, so there is no ambiguity about what is retrieved. No sibling tool does anything similar – the rest are stats/heartbeat/commit/org aggregations – so it is easy to route to.

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 'this key belongs to' implies the tool is for resolving the authenticated user's identity, and with zero parameters and a single obvious purpose, alternatives are effectively nil. However, the description never states when to reach for this tool (e.g., 'use to resolve the API key's owner before calling user-scoped endpoints') or any exclusions. Usage is inferable rather than stated.

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

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

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds beyond that: an explicit auth-scope requirement (read_heartbeats), a repository-connectivity prerequisite, and pagination. It doesn't describe what a page contains beyond the page cursor, but the added operational constraints are substantive.

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

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

Two compact sentences, front-loaded with purpose and payload before the prerequisites and filters. Every clause carries information (repository requirement, filters, paging, scope, endpoint), though the raw endpoint path is the weakest element for an agent choosing a tool.

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

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

With no output schema, the description still covers the essentials: what is returned (commits plus coding time), the required precondition, auth scope, and paging, with the cursor mechanism handled by the schema's next_page note. Return shape details (fields per commit) remain unspecified but are not blocking.

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 page, author, branch, and project are all documented in the schema with defaults and constraints. The description's 'Filter by author or branch; paged' only restates that at a high level and adds no name formats or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Commits of a WakaTime project') plus the distinguishing payload ('with the time spent coding on each'), which separates it from a plain commit listing. It never names the single-commit sibling wakatime_get_commit, so the plural-vs-singular distinction is left to inference rather than stated.

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

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

Gives real preconditions for use: a connected repository is required and OAuth tokens need the read_heartbeats scope. It also states the two filter axes (author, branch) and that results are paged. It stops short of naming when to prefer this over wakatime_get_commit for a single commit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact, the required read_goals OAuth scope, but says nothing about pagination behavior or result size even though a page parameter 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?

Two compact sentences that front-load the resource and its output shape, then the auth requirement. The comma-list of fields is dense but readable; no redundant filler.

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

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

For a zero-required-parameter list endpoint with no output schema, the description covers resource, returned fields, auth scope, and underlying endpoint. Only pagination semantics are unaddressed, which is a minor gap given the schema documents the page parameter.

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 single parameter is fully documented in the schema (page number, with the instruction to pass the previous reply's next_page), so the baseline is 3. The description adds nothing about the page parameter or pagination limits.

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

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

States a specific verb and resource (list the user's coding goals) and enumerates the fields returned, so an agent can tell what it produces. It doesn't explicitly distinguish itself from the sibling wakatime_get_goal, leaving the collection-vs-single distinction to be inferred from the names.

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

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

No statement of when to use this tool versus wakatime_get_goal. The only usage-relevant sentence is the OAuth scope requirement, which is a prerequisite rather than a use-case guideline.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context via the endpoint (GET /users/current/machine_names, i.e. current-user scope only) and the returned field set, but does not mention auth requirements, pagination, or rate limits.

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

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

Two tight sentences with the resource description front-loaded. The trailing endpoint citation is slightly redundant but brief and gives an API mapping, so it roughly earns its place.

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

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

A simple read-only, parameterless tool with safety annotations already covering the risk profile. Since no output schema exists, the description's enumeration of returned fields (id, name, host name, IP, timezone, last-seen) usefully compensates; only pagination/auth details are absent.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify. Baseline 4 applies for a parameterless tool.

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

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

States a specific verb+resource — 'The machines (computers) that sent coding activity' — and enumerates the returned fields. This clearly distinguishes it from siblings like wakatime_list_projects and wakatime_list_user_agents, which list 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?

The description says what the tool returns but gives no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer from the resource name alone that this is the tool for machine/device listings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the response fields, including the 'view-only hidden' activity flag and the underlying GET endpoint, but says nothing about pagination behavior even though the tool is paginated.

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

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

Two tight sentences: the resource and returned fields come first, the endpoint path trails as supporting detail. Every element earns its place, including the field list, since no output schema exists.

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

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

With no output schema, enumerating the returned fields is the right call and largely complete for a simple paginated list. Pagination semantics are only in the schema's page description, leaving a small gap in the description itself.

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 org_id, dashboard_id and page are fully documented in the schema, including the instruction to pass the previous reply's next_page. The description adds no parameter-level detail, which is acceptable at this coverage level but earns nothing extra.

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

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

The description names the resource precisely ('members of an organization dashboard') and enumerates the returned attributes, so an agent knows exactly what this returns. It distinguishes itself from wakatime_list_org_dashboards and wakatime_get_org_member_summaries by the dashboard-member scope, though it never explicitly contrasts them.

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

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

No statement of when to use this versus alternatives such as wakatime_get_org_member_summaries, nor any prerequisite guidance. The only routing hint (dashboard_id comes from wakatime_list_org_dashboards) lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the result includes what the user may view or join, but says nothing about pagination behavior or result size, which the page parameter implies.

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

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

Two compact sentences with the payload contents front-loaded and the endpoint appended as reference. No filler, though the raw GET path is marginal value for an agent.

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

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

With no output schema, the description usefully enumerates the returned fields, which is what an agent needs most here. It leaves paging/continuation behavior to the schema's next_page note, a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so org_id (with its pointer to wakatime_list_orgs) and page are already fully documented, giving a baseline of 3. The description adds nothing about parameter format or paging semantics beyond what the schema provides.

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

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

Names the resource (an organization's dashboards) and enumerates the salient fields returned (id, name, timezone, member count, view/join permission). It is clear what the tool does, but it does not distinguish itself from the closest sibling, wakatime_get_org_dashboard_summaries, so it falls short of a 5.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as wakatime_list_orgs (for finding the org id) or the dashboard-summaries tool. Usage is only implied by the required org_id and the endpoint path.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), so the bar is lower. The description usefully adds the OAuth scope requirement (read_orgs) and the underlying endpoint (GET /users/current/orgs), which is real behavioral context beyond the annotations.

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

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

Front-loads the resource and its contents in one sentence, followed by two short sentences for the auth scope and endpoint. No filler, though the field enumeration is slightly dense.

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

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

With no output schema, the description appropriately compensates by listing what each organization record contains. Auth scope and endpoint are included; only pagination behavior beyond the schema hint is absent.

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

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

Schema description coverage is 100% and the single 'page' parameter is fully documented in the schema (including the 'pass the previous reply's next_page' hint). The description adds nothing further about the parameter, so the baseline of 3 applies.

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

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

States a specific verb (list) and resource (organizations the user belongs to), then enumerates the fields returned (id, name, people count, preferences, permissions). It is clearly distinguishable from siblings like get_org_dashboard_summaries, though it doesn't explicitly name the contrast.

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

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

Usage is implied by the resource and the added fact that the read_orgs scope is required for OAuth tokens, which is a genuine precondition. There is no explicit when-to-use versus when-not-to-use guidance and no reference to the many sibling org/dashboard tools.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-annotated context: the required read_private_leaderboards OAuth scope and the underlying GET /users/current/leaderboards endpoint.

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

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

Three terse sentences with no waste, the resource and returned fields front-loaded before the scope and endpoint details. Slightly dense but every clause carries information (fields, auth, endpoint).

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

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

With no output schema, the description usefully enumerates the return fields, and the auth scope plus endpoint disambiguate the call. Pagination is handled by the schema, so the only remaining gap is differentiation from the singular sibling.

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

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

Schema description coverage is 100% and the single page parameter is fully documented in the schema, including the next_page chaining hint. The description adds no parameter detail beyond that, so the 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 resource precisely and even enumerates the returned fields (id, name, time range, member count, edit rights), so the agent knows exactly what data comes back. It does not differentiate itself from the singular sibling wakatime_get_private_leaderboard, which is a meaningful ambiguity in this tool set.

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

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

Usage is implied by 'the private leaderboards the user is in', and the OAuth scope prerequisite is stated, but there is no explicit when-to-use or when-not-to-use guidance and no routing to the singular get_private_leaderboard 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by disclosing the endpoint (GET /users/current/projects) and the non-obvious field set the response carries, but it says nothing about pagination or result-size behavior despite the presence of a page parameter.

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

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

Two tight sentences with no filler: the resource and return payload come first, the optional filter second, and the underlying endpoint last. The field enumeration is dense but earns its place given there is no output schema to document the response shape.

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

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

With no output schema, the description usefully compensates by listing the fields the reply contains, and pagination semantics are covered by the schema. The only gap is the absence of any guidance on when to prefer this tool over related listing/statistics siblings.

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

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

Schema description coverage is 100%, so both q and page are already documented in the schema, including the hint to pass the previous reply's next_page. The description only reiterates the name-search filter already described by the schema, adding no syntax, format or tie-breaking detail beyond it. 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 names the specific resource (the user's WakaTime projects) and enumerates the returned fields (id, name, repository, color, clients, heartbeat times, flags), and the trailing endpoint confirms it is a list operation on /users/current/projects. It is clearly distinguishable from siblings like list_machines, list_goals or list_orgs by resource alone, though it never states a verb explicitly.

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

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

The only usage signal is 'Optionally filter by a name search', which implies how to narrow results but gives no when-to-use guidance relative to alternatives (e.g. get_stats or list_machines). No prerequisites, no exclusion conditions, and no routing to a sibling are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds some context by enumerating what the payload contains and citing the upstream endpoint (GET /users/current/user_agents), but says nothing about pagination, auth scope, or ordering.

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

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

A single tight sentence (plus the endpoint reference) with the resource and payload front-loaded and no filler. It reads as a telegraphic noun phrase rather than a full sentence, which is a minor structural weakness but costs no clarity.

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

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

With no output schema, the field enumeration (editor, version, OS, AI model, last-seen time) does the job of telling the agent what it receives, which is the right compensation. A note on pagination or auth would be the only meaningful addition.

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

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

The tool takes zero parameters, so per the baseline no parameter documentation is required. The description correctly omits any param discussion, and the schema is trivially complete.

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

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

The description names the exact resource (editor and plugin user agents that sent coding activity) and enumerates the returned fields, so an agent knows precisely what comes back. It does not, however, differentiate itself from close siblings such as wakatime_list_machines or wakatime_list_projects, so it stops short of a 5.

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

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

There is no guidance on when to call this rather than the other list_* tools, and no prerequisites or exclusions are stated. Usage is only inferable from the name and the returned-field list.

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