paymo

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

Annotations only carry destructiveHint=true, so the description adds useful context: content permits basic HTML and the underlying endpoint is POST /api/comments. It does not disclose permission requirements, whether the comment can later be edited or removed, or what the call returns. With annotations covering the mutation flag, 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?

Two short sentences, no filler, with the core action front-loaded and the read alternative and richer content note following. Every clause carries information an agent can act on.

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 two-parameter write tool with no output schema and minimal annotations, the description covers action, content format, sibling route for reading, and endpoint. The main remaining gap is the response shape (e.g. the created comment id), which would help since no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuinely useful constraint for the content parameter: it may contain basic HTML. That is format information absent from the schema, which specifies only minLength 1 and type string.

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 (add) plus resource and scope (a comment to a task's discussion thread). It is immediately distinguishable from siblings like paymo_create_task or paymo_update_task, which operate on the task itself rather than its thread.

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 clear when-to-use and routes the agent to paymo_get_task with include=thread.comments for the read-side counterpart. It does not state exclusions or prerequisites (e.g. permissions, whether the task must be open), so it stops just short of explicit 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 only declare destructiveHint=true, so the description carries most of the load and does it well: it discloses the implicit 'Sample Client' side effect and a concrete failure mode (403 on free-plan limits). It stops short of saying whether the change is reversible or what permissions are required.

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

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

Three compact sentences, front-loaded with the core action and the highest-risk caveat. The trailing 'Paymo: POST /api/projects.' is endpoint detail of marginal use to an agent but 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?

For a create tool with 8 parameters and no output schema, the description covers side effects and one error case but omits the return value (e.g., the new project id needed for follow-up calls) and any permission requirements. Adequate but with a real gap for a creation workflow.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks for client_id — the auto-created 'Sample Client' fallback when it is omitted. The other seven parameters gain nothing beyond their schema descriptions.

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

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

States a specific verb and resource ('Create a project') that is immediately distinguishable from siblings like paymo_create_task and paymo_create_time_entry. It does not explicitly contrast itself with alternatives, but the resource is unambiguous.

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

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

Gives useful conditional context — omitting client_id triggers auto-creation of a 'Sample Client', and free plans hit an active-projects limit (403). However, it never states when to prefer this tool over paymo_list_projects/paymo_get_project or what prerequisites (e.g., valid client_id, user ids) are needed.

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

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

Annotations supply only destructiveHint=true, which is oddly weak for a create operation, so the description carries most of the burden. It does add a real behavioral fact — that a project_id target routes into that project's 'Default Task List' — but says nothing about permissions, side effects, or what is returned.

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

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

Two short clauses plus an endpoint reference; the targeting distinction is front-loaded and nothing is padded. The trailing 'Paymo: POST /api/tasks' is low-value for an agent but 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?

For a 9-parameter mutation tool with no output schema, the description covers the key call-time decision (where the task goes) but leaves the agent without any sense of the response or post-creation state. It is minimally adequate given the fully populated schema, but not rich.

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 nine parameters are already documented and parameter descriptions (including the project_id fallback rule) largely duplicate what the description says. The only genuinely additive detail is the destination 'Default Task List' behavior, which is not in 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 ('Create a task') and clarifies it can land in a task list or a project, which separates it from the read/update task siblings. It does not explicitly name or contrast against other create tools (create_project, create_time_entry), so it stops short of 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 gives a routing rule between the two mutually exclusive targeting parameters (tasklist_id vs project_id), which is useful implied guidance for calling it correctly. However there is no when-to-use/when-not-to-use framing against sibling tools and no prerequisites 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?

With destructiveHint=true already declared, the description adds a real constraint beyond the schema ('min 1 minute') and the Paymo endpoint. However, it never states that this creates a new record, who may log for whom (the user_id default only appears in the schema), or that no edit path exists here. Useful but not rich behavioral context.

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

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

Two sentences, front-loaded with the action and input shapes, followed by the alternative tool and endpoint reference. No filler and nothing 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?

For a 7-param create tool with full schema coverage and no output schema, the description covers what the tool does, the two valid input modes, and the sibling to use instead. Return-value detail is not required here, so nothing essential is missing.

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

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

Schema description coverage is 100%, so baseline would be 3, but the description adds the mutual-exclusivity contract that the schema only implies: date pairs with duration_seconds, start_time pairs with end_time. That is genuine semantic value the agent cannot infer from field descriptions 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?

States a specific verb and resource ('Log a completed time entry on a task') and immediately disambiguates from the nearest sibling by naming paymo_start_timer for live timers. An agent can distinguish it from paymo_list_time_entries and paymo_update_time_entry by the word 'log' plus 'completed'.

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

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

Explicitly routes to paymo_start_timer when the user wants a live timer and gives the two accepted input shapes for a completed entry. It does not mention paymo_update_time_entry as the correction path, so coverage of alternatives is good but not exhaustive.

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 is a safe, non-mutating read, so the safety profile is covered. The description adds value by listing the concrete configuration fields returned, which the annotations and empty schema do not provide, but it says nothing about permissions required or the response structure.

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

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

A single front-loaded sentence naming the resource and its fields, with no filler. The trailing 'Paymo: GET /api/company' is mildly redundant but harmless implementation context.

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-argument read tool with no output schema, the description sensibly enumerates the returned settings, covering the main gap. It does not claim to cover the full response shape, but it is sufficient for correct invocation.

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

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

The tool takes zero parameters and the input schema is empty, so per the baseline there is nothing for the description to document. The listed field names loosely describe the return payload rather than inputs, but no parameter gap exists.

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 ('Fetch the company (account) info and settings') and enumerates the returned fields, so an agent knows exactly what it gets. It does not explicitly distinguish itself from the sibling paymo_get_me, which is the most likely confusion point, 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as paymo_get_me or paymo_list_users. The agent must infer the context entirely from the tool name.

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 readOnlyHint, the description discloses the response shape (totals, line items, payments) and that line items and payments are expanded by default, plus the underlying Paymo endpoint. It does not cover auth requirements or rate limits, but the added behavioral context is genuine.

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 waste; the core action and scope are front-loaded, and the endpoint detail is appended as reference rather than padding the lead.

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 states what is returned (totals, line items, payments) and the default expansion behavior, which is enough to call it correctly. Only permissions and error behavior are unaddressed, which is minor for a read-only tool.

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

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

Schema coverage is 100% with only two parameters, so the schema already defines both. The description reinforces the include_items default and clarifies that the include flag bundles line items and payments together, which is a small semantic addition rather than new information.

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

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

The description uses a specific verb+resource, 'Fetch one invoice', which implicitly separates it from the sibling paymo_list_invoices because it emphasizes a single record by id. It never names an alternative sibling, so it falls just short of full explicit differentiation.

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

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

Usage is only implied: an agent can infer this is for retrieving a single known invoice rather than enumerating invoices, but there is no explicit when-to-use or when-not-to-use statement, and no mention of the list counterpart.

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

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

readOnlyHint already tells the agent this is a safe read, and the description adds real value beyond that: it names the auth/identity semantics (the API key's own user), advertises the call as a cheap credential check, and discloses the returned fields plus the backing endpoint (GET /api/me). No rate limits or error behavior, hence not a 5.

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

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

Three short sentences, each front-loaded with purpose, then usage, then cost/verification value and endpoint. Every sentence earns its place with no repetition of the name or title.

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

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

With no output schema, the description carries the return-shape burden and does so by listing id, name, type, and timezone. For a zero-parameter, read-only identity tool, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It still usefully clarifies that no user_id input is needed because identity is derived from the API key.

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 (Fetch) and resource (the Paymo user the API key belongs to) and enumerates the returned fields (id, name, type, timezone). This distinguishes it from sibling list_user/get_company/get_project tools that 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?

Gives a concrete downstream usage ('Use the id as user_id for my time entries and timers') and a second use case ('a cheap way to confirm the key works'). It stops short of explicitly excluding alternatives such as paymo_list_users, so it is clear context without full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the inline-embedding behavior and the endpoint mapping, but says nothing about failure modes (e.g. nonexistent id) or permission requirements, 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?

A single front-loaded sentence conveys purpose, the optional include capability, and a concrete example, followed by a brief endpoint mapping. No wasted words.

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

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

For a two-parameter read tool with no output schema, the description covers the essential purpose and the one non-obvious parameter behavior. The gap is the absence of any hint about the returned object's shape, though annotations remove the need to explain mutability.

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 project_id and include are already documented in the schema. The description's example of embedding 'the whole task tree' via dotted include paths adds some semantic depth beyond the schema's short example, but the baseline of 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (one project) with clear singular scope, which naturally distinguishes it from the plural paymo_list_projects sibling. Also names the underlying Paymo endpoint, removing any ambiguity about which entity is targeted.

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

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

Gives concrete usage context by explaining when to use the include parameter ('include=tasklists.tasks for the whole task tree or include=client'), which is the main usage decision for this tool. It does not, however, state exclusions or explicitly contrast with paymo_list_projects, so it falls short of a full when/when-not routing statement.

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

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

readOnlyHint=true already declares the safe-read profile, so the description adds only incremental context: that include embeds related objects and that it maps to GET /api/tasks/{id}. It says nothing about error behavior for missing ids or response shape, which is acceptable given the annotation already covers safety.

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 core action and the optional include behavior. The trailing "Paymo: GET /api/tasks/{id}" is mildly redundant but small and useful for API mapping.

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 only two parameters at 100% schema coverage, a readOnly annotation, and no output schema, the description covers what an agent needs: the single-task scope and how include works. Only minor gaps remain around selection against sibling list/read tools.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds concrete meaning beyond the schema's generic examples by naming specific include values (thread.comments, subtasks, entries, files, project). This makes the include parameter more actionable 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?

States a specific verb+resource ("Fetch one task") and its singular scope, which implicitly distinguishes it from paymo_list_tasks and paymo_update_task. However, it never names a sibling explicitly, so the differentiation is inferable rather than explicit.

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 optional include path (when you want related objects embedded), giving implied usage context. It does not state when to use this tool versus paymo_list_tasks or paymo_update_task, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the endpoint mapping and the shape of returned fields, which is modestly useful, but says nothing about truncation behavior, auth requirements, or rate limits beyond what the schema already notes.

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

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

Two compact sentences, front-loaded with the resource and its fields. The trailing endpoint reference earns a little place as an API mapping hint, though it is close to filler for an agent that only needs to call 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?

For a simple read-only list tool with full parameter documentation, this is largely complete: the field list compensates for the absent output schema and the annotations cover safety. Only the lack of any usage/filtering guidance keeps it short of full marks.

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 four parameters (limit, where, active, include) are already thoroughly documented in the schema, including the no-pagination truncation caveat. The description adds no parameter meaning beyond that, which is the expected 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?

States a specific verb (List) plus resource (clients) and even enumerates the returned fields (id, name, contact details, active flag) and the backing endpoint. It is unambiguous against siblings like paymo_list_projects or paymo_list_users, though it never explicitly differentiates itself from 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 when-to-use guidance is given. There is no mention of when to reach for this versus a filtered client lookup, no prerequisites, and no indication of when the 'where' escape hatch should be preferred over the typed filters.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds the return field set and the REST endpoint, but omits behavioral facts like truncation/no-pagination policy (which lives only in the schema). Adequate but thin beyond annotations.

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

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

Two short sentences, purpose front-loaded with the endpoint as trailing detail. No wasted words, though the parenthetical field list is somewhat 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, naming the returned fields is genuinely useful for the agent. Combined with rich filter descriptions in the schema, the definition is nearly complete; only usage guidance and truncation behavior are unaddressed in prose.

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

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

Schema description coverage is 100%, so all seven filters (limit, where, date_from/to, invoiced, client_id, project_id) are already fully documented. The description adds nothing about filter semantics, 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+resource ('List expenses') and enumerates the returned fields, plus the underlying endpoint GET /api/expenses. It is distinguishable from siblings such as paymo_list_invoices and paymo_list_clients by resource, 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 guidance on when to use this versus alternatives, no prerequisites, no mention of auth or context. The agent must infer usage purely from the name and resource.

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

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

readOnlyHint=true already declares the safety profile, so the description need not restate that it is a safe read. It adds genuine value by enumerating the returned field set (id, number, client_id, status, currency, date, due_date, subtotal, total), which compensates for the absent output schema; truncation behavior is left to the schema rather than the description.

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 segments with zero waste: the purpose and return fields come first, followed by the Paymo endpoint. Nothing is padded or redundant.

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 inline field enumeration usefully conveys the return shape, and the schema fully covers inputs. The only shortfall is the absence of usage/routing guidance, which is minor for a straightforward read-only list tool.

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

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

Schema description coverage is 100%, so all four parameters (limit, where, status, client_id) are already fully documented in the schema. The description adds no parameter syntax or semantics beyond what structured data 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 clear verb+resource ("List invoices") and enumerates the returned fields, so the agent knows it is a collection read against the Paymo invoices endpoint. It does not, however, distinguish this from the sibling paymo_get_invoice tool or clarify the list-vs-single relationship.

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 when-to-use, when-not, or alternative guidance is given. The agent is not told to prefer this over paymo_get_invoice for a single record, nor that the typed filters (status, client_id) exist as the intended narrowing mechanism.

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 essentially nothing behavioral beyond mapping to 'GET /api/projects'. The important trait here — Paymo has no pagination and results past the limit are silently truncated — lives only in the schema's limit field, not in the description.

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

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

Two short sentences, front-loaded with the verb and resource, with zero filler. The field enumeration is slightly long but defensible given there is no output 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, listing the returned fields is genuinely useful, and the endpoint reference grounds the tool. The remaining gap is that pagination/truncation behavior for a list tool is never surfaced 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 all eight filters (limit, where, active, include, user_id, billable, client_id, manager_id) are already documented in the schema. The description's parenthetical lists output fields rather than input parameters, so it adds little parameter meaning beyond the schema 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?

States a specific verb (List) and resource (projects), and enumerates the returned fields (id, name, code, client_id, active, billable, budget_hours, users, managers), which clearly separates it from single-project tools like paymo_get_project. It stops short of naming that sibling explicitly, so it is clear but not maximally differentiated.

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

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

'optionally filtered' implies the tool can be narrowed but gives no explicit when-to-use guidance, no mention of the alternative paymo_get_project for a single project, and no statement about which filters compose. Usage is inferable from the schema but not 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by naming the returned fields (useful since there is no output schema) and the underlying endpoint, but says nothing about auth needs, rate limits, or ordering. With annotations covering the safety profile, this is adequate but thin.

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, zero waste, with the resource and returned fields front-loaded before the use case. Nothing is padded or repeated.

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

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

For a simple read-only list tool with fully documented parameters and annotations covering safety, the definition supplies the purpose, a use case, the endpoint, and the returned fields. Only minor gaps (ordering, auth context) remain, which is acceptable at this complexity.

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%: limit, include, and project_id are all documented in the schema, including the truncation behavior. The description adds no parameter syntax or semantics beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (List) and resource (task lists), and even enumerates the returned fields (id, name, project_id, milestone_id), which makes it easy to tell apart from list_tasks and list_projects. It stops short of naming a sibling explicitly, so it is clear but not maximally differentiated.

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

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

The phrase 'e.g. to pick a tasklist_id when creating a task' gives a concrete when-to-use tied to the create_task sibling. There is no explicit when-not or named alternative, but the usage context is clear rather than merely implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the concrete returned field set and identifies the underlying Paymo endpoint (GET /api/tasks), which is useful behavioral context given there is no output schema. It does not mention the no-pagination/truncation behavior, which lives only in the schema.

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

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

Front-loaded with purpose, then filters, then endpoint; no filler sentences. The parenthetical field enumeration is dense but earns its place since no output schema exists, though it makes the single sentence list-heavy.

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 supplies the return-field list; annotations cover read-only safety; all 8 parameters are documented in the schema. Truncation/pagination caveats and the raw `where`/`include` semantics are only in the schema, but the description is otherwise sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters in more detail than the description (e.g. my_tasks semantics are spelled out in the schema). The description only restates the filter axes, adding no syntax or format detail beyond the structured field. Baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (tasks), enumerates the returned fields, and describes the filter dimensions. The 'my_tasks=true returns the caller's My Tasks' clause separates it from a plain filtered list and from the single-task paymo_get_task sibling.

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

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

It clearly states the filter dimensions (project, task list, assignee, completion) and the special my_tasks mode, which tells the agent when this tool is the right choice. It never names an alternative tool or an explicit when-not-to-use condition, so it stops 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?

Annotations declare readOnlyHint=true, so safety is already covered. The description adds a genuine hard constraint not present in the schema ('At least one filter is required') and discloses the return shape (field list) plus the underlying endpoint GET /api/entries, which is real value 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?

Three tight sentences, front-loaded with the returned fields followed by the key constraint and then parameter behavior. The field enumeration is long but earns its place given there is no output schema; little waste overall.

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 11-parameter read-only list tool with no output schema, the description covers purpose, the required-filter rule, key filter semantics, and the return fields. The main omission is absence of any guidance on selecting this tool versus adjacent timer/entry tools, which leaves a small gap.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented, including the truncation caveat on limit and operators on where. The description's 'from/to filter by the entry's time interval' and 'running_only=true returns running timers' largely restate schema text, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List time entries') and enumerates the fields it returns (id, task_id, user_id, project_id, start/end time, duration, description, billed), which is well beyond a restatement of the name. It does not explicitly contrast itself with siblings such as paymo_list_tasks or paymo_update_time_entry, but the resource is unambiguous.

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

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

Gives one concrete usage rule ('At least one filter is required') and explains what from/to and running_only do, which is useful context. However, it never states when to prefer this tool over alternatives like paymo_start_timer, paymo_stop_timer, or paymo_update_time_entry, so selection guidance is implied rather than explicit.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds that results span the whole company and includes sensitive fields like hourly rate, plus the Paymo endpoint, but says nothing about truncation behavior (which the schema covers) 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 compact sentence that front-loads scope and follows with the returned fields; no filler. The field parenthetical is dense but earns its place given there is no output 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 compensates by listing the fields returned, which is the key missing piece. Filtering semantics live in the schema, so a complete tool call is achievable from the combined definition.

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 four parameters are already fully documented in the schema with defaults, limits, and operator syntax. The parenthetical in the description describes output fields rather than parameter meaning, so it adds little beyond 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?

States a clear verb+resource ('List users') plus the scope ('in the company') and enumerates the returned fields, so an agent knows exactly what it gets. It does not explicitly differentiate itself from the many sibling list_* tools, but the name plus field list makes the subject 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?

No when-to-use guidance, no alternatives, and no mention of how to combine the optional filters. The agent is left to infer everything about selecting this tool over paymo_get_me or the other list_* siblings.

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

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

Annotations only carry destructiveHint, so the description usefully discloses a behavioral trait the agent cannot infer: the single-running-timer invariant and the exact failure mode ('Paymo returns 409'). It stops short of covering auth requirements or what the response contains, but the conflict semantics are the key operational fact.

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

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

Three tightly written sentences, front-loaded with the core action before the constraint and error. The trailing 'Paymo: POST /api/entries' is an implementation detail of marginal value to an agent, a minor bit of 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 small 4-parameter creation tool with no output schema, the description covers purpose, the running-timer constraint, and the error case. It omits what the call returns (e.g. the created entry id), which an agent might want, but otherwise nothing essential is missing.

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

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

Schema description coverage is 100%, so all four parameters (task_id, user_id, start_time, description) are already documented in the schema. The description reinforces the start_time/no-end_time concept but adds no syntax or default details beyond it — baseline 3.

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 ('Start a running timer on a task') and then defines the resource precisely as 'a time entry with a start_time and no end_time', which differentiates it from the sibling paymo_create_time_entry and pairs conceptually with paymo_stop_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 one-running-timer-per-user constraint and the resulting 409 give real usage context, but it never explicitly says when to prefer this over paymo_create_time_entry or paymo_stop_timer, leaving the sibling routing implied.

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

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

Annotations only declare destructiveHint=true; the description adds meaningful behavior: end_time defaults to now, the resulting duration must be >= 1 minute, and the underlying PUT /api/entries/{id}. It doesn't say what happens if the timer is already stopped or whether end_time can be set in the past, which keeps it from a 5.

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

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

Three tight sentences: action, constraint, discovery step, and endpoint. Zero filler and the core behavior is front-loaded.

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

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

With no output schema, the description covers the key operational facts (default end_time, duration floor, how to obtain entry_id). It stops short of describing server responses or error cases for an already-stopped timer, which an agent might want.

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 already 100%, so the baseline is 3, but the description adds the non-obvious default (now) and the minimum-duration constraint that governs the end_time value. The description field's role on a stop operation is still unexplained.

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 ('Stop a running timer by setting its end_time') and implicitly distinguishes itself from paymo_start_timer and paymo_update_time_entry. An agent can tell immediately what this mutates and how.

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

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

Gives a concrete prerequisite path: find the running entry via paymo_list_time_entries with running_only=true, and states the constraint that final duration must be at least 1 minute. It does not explicitly say when not to use it (e.g., versus editing an already-stopped entry), 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?

Annotations only declare destructiveHint=true, so the description carries the behavioral load and does so well: it discloses patch semantics ('Only the fields given are changed') and the destructive replace-list behavior of 'users replaces the whole list'. It omits auth/permission needs and side effects of moving between lists or workflows.

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

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

Front-loaded with the verb and full capability list, followed by one critical semantic caveat and an endpoint reference. No filler sentences; 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?

For a 10-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers the key semantics (partial update, list replacement, endpoint). It could still mention permissions or failure behavior, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter, including that users is the 'New FULL list of assignee user ids'. The description's 'users replaces the whole list' largely restates that, adding little 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 (update) plus resource (task) and enumerates every updatable facet (name, description, assignees, due date, priority, completion, list, status). It is easily distinguished from paymo_create_task and paymo_get_task.

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 field enumeration, and 'Only the fields given are changed' communicates partial-update behavior, but there is no explicit when-to-use vs alternatives guidance or prerequisite/permission note, and no sibling is named.

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 destructiveHint=true, and "Edit" is consistent with that mutation profile. Beyond the annotation, the description only adds the PUT endpoint path; it does not disclose reversibility, required permissions, or side effects of reassigning task_id, so it adds limited behavioral context on top of what annotations already carry.

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

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

Three short sentences, front-loaded with the verb and editable fields, then the conditional rule. The trailing "Paymo: PUT /api/entries/{id}" is mild restatement but compact and harmless.

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

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

No output schema exists, so return values need not be described, and the schema fully documents the 7 parameters. For a mutation tool the description covers what can be edited and the entry-type branching, though it omits permission/reversibility context that the single destructiveHint annotation does not supply.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter conditional logic absent from the flat schema descriptions: duration_seconds applies only to date+duration entries while start/end entries must change end_time instead. That link between parameters is genuinely useful 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?

States a specific verb+resource ("Edit a time entry") and enumerates the editable surfaces (description, task, length), which clearly separates it from paymo_create_time_entry and paymo_list_time_entries. An agent can identify the operation without opening the schema.

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

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

The description gives useful conditional routing between duration_seconds (date+duration entries) and end_time (start/end entries), which is real invocation guidance. However, it offers no explicit when-to-use vs alternatives (e.g., create vs update, or timer-based flows through paymo_start_timer/paymo_stop_timer), so usage selection is only implied.

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