Paymo MCP by usefulapi

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

Annotations only carry destructiveHint=true, so the description must add context. It does disclose the accepted content format ('content may contain basic HTML') and the underlying API operation (POST /api/comments), which is useful. However, it says nothing about required permissions, whether a posted comment can be edited or removed, or what the response contains — meaningful gaps for a mutation tool.

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

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

Three short sentences, front-loaded with the action and resource, then the format caveat, then the read alternative. Nothing is redundant and no sentence wastes space.

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 mutation tool with no output schema and thin annotations, the description covers the action, content format, related read tool, and the backing endpoint. It leaves out permission/auth requirements and return behavior, which keeps it just short of fully complete.

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

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

Schema coverage is 100% and both parameters are documented, so the baseline is 3. The description adds real meaning beyond the schema by specifying that the content field accepts basic HTML, which the schema's 'Comment text.' does not convey. It adds no further detail on task_id beyond what the schema states.

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

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

States a precise verb + resource + location: 'Add a comment to a task's discussion thread.' It is clearly distinct from sibling tools like paymo_update_task or paymo_create_task, and it names paymo_get_task as the read counterpart, so an agent can place it without opening a 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?

Gives explicit routing guidance for the counterpart operation ('Read existing comments with paymo_get_task include=thread.comments'), which is genuinely actionable. It does not state prerequisites (task must exist, permissions needed) or when *not* to comment, so it stops short of full when/when-not coverage.

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 bar is low, and the description adds real side-effect disclosure beyond them: omitting client_id silently auto-creates a 'Sample Client', and free plans hit an active-project limit returning 403. It omits permission/role requirements and what is returned, keeping 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 short sentences, front-loaded with the action and followed by the highest-value caveats; nothing is buried. The trailing 'Paymo: POST /api/projects' restates an endpoint an agent cannot act on, which is minor 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 single-required-param create with fully documented schema and no output schema, the description covers the critical hidden behavior (implicit client creation) and a failure mode (403 on plan limits). It lacks permission prerequisites and any indication of what the created project returns (e.g., an id for follow-up calls).

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?

With 100% schema coverage the baseline is 3, and the description goes beyond the schema by explaining the omission semantics of client_id (auto-creation of a Sample Client), which the schema's terse 'Client the project is for' does not convey. Other params 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+resource ('Create a project') that cleanly distinguishes it from read siblings like paymo_get_project and paymo_list_projects and from paymo_create_task. It does not explicitly name an alternative or contrast scope, 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 use this versus alternatives (e.g., when to create vs reuse an existing project, or when to call paymo_list_projects first). The notes address edge-case behavior (auto-created Sample Client, free-plan 403) rather than usage selection, so the agent must infer context.

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

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

Annotations already declare destructiveHint=true, so the write/mutation profile is known. The description adds the backing endpoint (POST /api/tasks) and the Default Task List side effect, but says nothing about auth requirements, whether assignees are notified, or that the operation is not undoable. Useful but not rich context for a mutation tool.

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

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

One sentence plus an endpoint reference, with the placement rule front-loaded. Every clause carries 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?

Covers the one genuinely tricky decision (where the task lands) for a 9-parameter, 1-required tool whose schema is fully documented. The only gap is that with no output schema the description never indicates what comes back (e.g. the new task id), which an agent chaining into paymo_update_task would 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 100%, so the baseline is 3. The description earns above that by explaining the interaction the schema only hints at: project_id is only a fallback when tasklist_id is absent, and the task lands in the project's 'Default Task List' — a destination the schema never names.

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 immediately clarifies the two placement targets (tasklist_id vs project_id), which is the real ambiguity in this tool. An agent can tell it apart from paymo_create_project and paymo_create_time_entry without opening any 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?

Gives clear routing guidance between the two mutually exclusive location parameters, including the fallback behavior for project_id. It does not explicitly state when not to use this tool versus siblings (e.g. update_task for existing tasks), but the create/update split is obvious from the 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?

Annotations only supply destructiveHint=true, so the description carries most of the burden. It usefully adds the either/or input contract and the one-minute minimum, but says nothing about permissions, whether entries can be edited afterward (paymo_update_time_entry exists), or side effects of logging time.

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: capability and validation first, alternative tool second, endpoint last. No filler or repetition of schema details.

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-parameter creation tool with no output schema and thin annotations, the description covers the input contract and sibling routing adequately. It omits what the call returns and any post-creation behavior, which would round it out.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds the mutually-exclusive grouping of date+duration_seconds vs start_time+end_time that the flat schema cannot express. That is genuine semantic value beyond the parameter list.

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 explicitly distinguishes itself from the sibling paymo_start_timer, which handles the live-timer case. An agent can pick between them 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?

Gives the exact input shapes ('EITHER as date + duration_seconds OR as start_time + end_time'), a validation rule (min 1 minute), and names the alternative tool for a different intent. This is near-complete routing 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 read-only safety profile is covered by structured data. The description adds useful context by naming the specific settings fields returned, but says nothing about authentication, scoping (single company per account?), or freshness. 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 tight sentences, field list front-loaded after the core purpose. The trailing API endpoint reference ('Paymo: GET /api/company') is informational filler 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?

A zero-parameter read tool with no output schema, so the description carrying the return-field list is exactly the needed compensation. Nothing critical for correct invocation is absent; only sibling differentiation and usage context 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No misleading parameter hints are present.

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 ('company/account info and settings') and enumerates the concrete fields returned (name, default currency, timezone, working days, invoice numbering). It is not tautological like the title. It stops short of distinguishing itself from the similar-sounding sibling paymo_get_me, which also retrieves account/user-level data.

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 indication of when to call this tool versus alternatives such as paymo_get_me, nor any prerequisites or context for its use. The use case is only weakly implied by the field list. An agent must guess when account-level settings are the right source.

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 readOnlyHint=true; the description adds real behavioral context by disclosing that line items and payments are included by default and that this maps to GET /api/invoices/{id}?include=invoiceitems,invoicepayments. It does not describe the response shape, but for a read-only single-fetch tool 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?

Two compact sentences: the first front-loads the operation and its return scope, the second supplies the exact upstream endpoint. Nothing is wasted 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 only two fully documented params, a read-only annotation, and no output schema, the description usefully compensates by naming what comes back (totals, line items, payments) and the default inclusion behavior. Only the non-naming of the list sibling and lack of any error/permission note leave 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 the schema already documents invoice_id and include_items (including its default true). The description restates the default-inclusion behavior but adds no syntax or edge-case detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb (Fetch) and resource (one invoice) and even enumerates what is returned: totals, line items, payments. The word 'one' implicitly contrasts with paymo_list_invoices, but the sibling is never named, which is the only thing keeping this from 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?

Usage is only implied by 'Fetch one invoice' — an agent can infer this is for retrieving a single invoice by id, but the description never states when to prefer this over paymo_list_invoices or how to obtain the required invoice_id. No exclusions or prerequisites are given.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value beyond that: no parameters required, it acts as a low-cost credential/auth verification, and it enumerates the returned fields (id, name, type, timezone). It doesn't discuss failure modes when the key is invalid, keeping it at a solid 4.

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

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

Four short sentences, front-loaded with the core purpose and followed by actionable usage and the endpoint. Every sentence earns its place with no redundancy.

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

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

With no output schema present, the description compensates by naming the returned fields and the underlying endpoint, making it complete enough for an agent to call and interpret the result correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed and instead documents the output shape, which is helpful but not a parameter-semantics contribution.

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 distinguishes itself from siblings like paymo_list_users by scoping to the authenticated key's own user. The endpoint reference (GET /api/me) reinforces the exact identity.

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 clear when-to-use context: obtain the id for 'my' time entries and timers, and as a cheap key-validity check. It stops short of naming alternatives such as paymo_list_users for other users' data, so it is clear context without explicit exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that related objects can be embedded inline (affecting payload size and shape), but says nothing about what fields are returned or whether a missing id errors versus returning null.

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 leading with the core action, followed by a compact endpoint reference. Nothing is redundant and the most important information (single-project fetch, optional include) comes first.

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-only lookup, the description covers the essentials and the annotations carry the safety profile. The only gap is return-value shape (no output schema exists), which the description leaves entirely 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 both parameters are already documented, including an example for `include` ('client or tasklists.tasks') that closely matches the description's example. The phrase 'for the whole task tree' adds a small interpretive gloss on nested includes, but it is largely repetition.

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 verb and resource ('Fetch one project') and immediately scopes it as a single-record read with optional inlined relations. The singular framing implicitly separates it from paymo_list_projects, and the API endpoint line grounds it further.

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 'Fetch one project' with a required project_id, and the include examples show how to expand the response. However, it never states when to prefer this over paymo_list_projects or paymo_get_task, nor any precondition such as needing a known project id.

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

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

readOnlyHint already declares this a safe read. The description adds useful context that include= can pull related objects, but does not disclose rate limits, response shape, or error behavior 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?

One compact sentence plus the endpoint reference; front-loads the core action and the include examples without waste.

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 2-param read tool with readOnlyHint and full schema coverage, this is nearly complete; only the return format is left implicit, which is acceptable without an output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by giving concrete include examples (thread.comments, subtasks, entries, files, project) that illustrate valid values beyond the schema's generic example.

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 distinguishes itself from the sibling listers (paymo_list_tasks) by making clear it retrieves a single task by id.

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

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

Usage is implied (fetch one task by id) but there is no explicit when-to-use vs paymo_list_tasks or when to add includes. Adequate minimum, no exclusions.

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

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

readOnlyHint=true already declares this as a safe read; the description adds only the GET /api/clients mapping, which is mild extra context. It does not disclose that results are truncated with no pagination (that fact lives only in the limit param schema), nor any rate-limit or auth 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?

Two short fragments with zero filler; the purpose is front-loaded and the REST endpoint is appended as supporting context. It is arguably terse given the schema's nuanced truncation behavior, 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 does helpfully preview returned fields, which is appropriate for a simple read-only list. However, for a tool whose pagination model is non-standard (hard truncation at 500), the definition omits any behavioral summary an agent would want before calling it.

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 limit, where, active, and include are all fully documented in the schema itself. The description's parenthetical (id, name, contact details, active flag) describes returned fields rather than adding parameter meaning, so it does not exceed 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 specific verb+resource ('List clients') and names the fields returned (id, name, contact details, active flag), plus the underlying REST call. It is distinguishable from siblings like paymo_list_projects or paymo_list_invoices by the resource alone, though it does no explicit sibling 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?

No guidance on when to use this versus paymo_get_company, paymo_list_projects, or other list_* tools, and no mention of how the active/where filters should be applied when choosing this tool. The agent must infer usage entirely from the 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?

annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description's only added behavioral content is the shape of returned records (id, client_id, project_id, user_id, amount, currency, date, notes, invoiced, tags), which is genuinely useful given there is no output schema, plus the underlying endpoint. It says nothing about truncation, ordering, or default result volume.

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 clauses with the core verb-resource claim front-loaded and no filler. The trailing 'Paymo: GET /api/expenses.' is marginally redundant with the tool name but cheap and adds endpoint provenance.

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 returned-field enumeration is a real contribution toward completeness, and no parameters are required. However, the description omits the truncation/no-pagination caveat that the schema surfaces only on the limit parameter, and gives no indication of result ordering or typical volume for a list endpoint.

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 (limit, where, date_from, date_to, invoiced, client_id, project_id) is already documented with semantics, operators, and defaults in the schema itself. The description adds no parameter-level information at all, 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 ('List expenses') and enumerates the fields the records contain, so the agent knows exactly what object is being fetched. It is unambiguous against siblings like paymo_list_invoices or paymo_list_time_entries, though it never explicitly contrasts itself with 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The parenthetical field list reads like a description of returned columns rather than filters, which could momentarily mislead an agent about what this tool accepts, since the actual filter parameters are client_id, project_id, date range, invoiced and where.

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 response field list, but says nothing about truncation/limit behavior beyond what the schema already documents, so it adds only modest 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 short sentences, front-loaded with the verb+resource and the returned-field list, with zero filler. 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?

With no output schema, the description usefully enumerates the returned fields, which is exactly what an agent needs to interpret results. Combined with 100% schema coverage on the inputs, the definition is nearly self-sufficient; only filter-selection guidance 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 limit, where, status and client_id are already fully documented in the schema. The description lists response fields rather than adding parameter meaning, 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+resource ('List invoices') and enumerates the returned fields, plus the underlying endpoint (GET /api/invoices). This clearly separates it from the singular paymo_get_invoice, though the description never names that sibling explicitly.

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

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

There is no guidance on when to use this versus paymo_get_invoice, nor any mention of how the typed filters (status, client_id) and the raw 'where' clause should be chosen. The endpoint line is informational, not usage advice.

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, and the schema's limit description already discloses the no-pagination/truncation behavior. The description adds only the Paymo endpoint mapping (GET /api/projects) and the returned field list, so it clears the lower bar set by annotations but adds little behavioral depth.

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 capability and returned-field list lead, the endpoint mapping trails. No filler or redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields, and annotations cover the read-only profile while the schema covers filtering and truncation. Only a partial field list is given and usage routing is absent, so it is not fully complete.

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

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

Schema description coverage is 100%, so all eight parameters (limit, where, active, include, user_id, billable, client_id, manager_id) are already fully documented in the schema. The description names returned fields rather than filter parameters and adds no interpretation 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+resource (list projects) and enumerates the returned fields, so its purpose is unambiguous next to paymo_get_project. It stops short of naming siblings explicitly, so sibling differentiation is only implicit via the list-vs-get naming.

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 guidance is 'optionally filtered,' which restates the schema rather than telling the agent when to choose this tool over paymo_get_project or paymo_list_tasks. No prerequisites, no exclusions, no alternatives are offered.

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 the underlying endpoint (GET /api/tasklists) and the fields returned, but says nothing about truncation or result shape. Since annotations carry the safety profile, a 3 is appropriate.

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

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

A single compact sentence with the purpose, fields, use case, and endpoint front-loaded. 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 read-only, zero-required-param list tool with full schema coverage and annotations, this covers what an agent needs. It even compensates for the absent output schema by naming the returned fields.

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 limit, include, and project_id are fully documented in the schema. The description lists return fields rather than adding meaning to the parameters, so baseline 3 applies.

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

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

States a specific verb and resource ('List task lists') and even enumerates the returned fields (id, name, project_id, milestone_id). It is unambiguous and distinguishable from siblings, though there is no near-sibling list tool it needs to be differentiated from.

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 use case: 'to pick a tasklist_id when creating a task,' which routes the agent toward its downstream use (paymo_create_task). There are no real alternatives to exclude, but it stops short of stating when NOT to call it.

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 bar is lowered. The description usefully names the underlying endpoint (GET /api/tasks) and the exact field set returned, but says nothing about truncation/no-pagination or result limits, which the schema covers instead.

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 verb and resource, with the endpoint appended last. The parenthetical field enumeration is dense but has no wasted prose.

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 returned fields, and it covers the main filter modes plus my_tasks. An agent has enough to call it correctly, though it lacks guidance on interleaving typed filters with the raw `where` string.

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 where, include, limit) is already documented in the schema. The description only restates filters and glosses my_tasks in nearly the same words the schema uses, adding little beyond the structured fields.

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

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

States a specific verb and resource ("List tasks") and enumerates the returned fields plus the filter dimensions (project, task list, assignee, completion), so the agent immediately knows this is a filtered list, not a single-fetch. It does not explicitly contrast itself with paymo_get_task or the other list_* siblings, which keeps it off 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?

It names the filter axes and clarifies the my_tasks flag, which implies when to use it, but never says when to prefer paymo_get_task, paymo_list_tasklists, or how to combine filters with the raw `where` clause. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a genuinely behavioral prerequisite the schema never states — that at least one filter must be supplied — and notes running_only surfaces timers with no end_time, but says nothing about truncation behavior (left to the schema) or auth requirements.

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

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

Four dense sentences, front-loaded with the resource and its return shape, then constraints, then the upstream endpoint. Nothing is padding; even the Paymo endpoint pointer earns its place as an escape hatch for edge-case filtering.

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 returned fields, and it covers the mandatory-filter rule that governs 11 optional parameters. Combined with 100% schema coverage on the parameters themselves, an agent has everything needed to call this 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 baseline is 3, but the description contributes a cross-parameter constraint not expressible in the schema (at least one filter required) and clarifies that from/to filter on the entry's own interval and that running_only selects entries lacking an end_time.

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 (time entries), and enumerates the returned fields, which lets an agent distinguish it from the other list_* siblings (tasks, projects, invoices) without ambiguity. It stops short of naming a sibling to use instead, but the resource is unique among siblings so differentiation is effectively achieved by the noun.

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?

"At least one filter is required" and the from/to and running_only semantics give concrete conditions for correct invocation. It does not, however, name an alternative tool or an exclusion case (e.g., use start_timer for the running-timer lifecycle), so it stays a clear-context-4 rather than a full 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds some value by listing the returned fields and the underlying API endpoint, but it does not describe pagination, rate limits, authentication needs, or return formatting beyond the field names. The schema itself covers truncation behavior in the limit 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?

The description is front-loaded with the core purpose, followed by the returned fields and API endpoint. It is a single efficient sentence with no redundant or wasted language.

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

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

For a simple list tool with a fully documented schema and a readOnly annotation, the description is largely complete: it states purpose, returned fields, and endpoint. It could be slightly stronger by mentioning filtering options or that results are returned in a single batch, but those details are covered by the schema.

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

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

Schema description coverage is 100%, so the baseline score of 3 applies. The description lists output fields (id, name, email, type, hourly rate, assigned/managed projects) rather than explaining parameter semantics, and adds no meaning beyond the fully documented 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: 'List users in the company.' It also lists the returned fields, making the tool's output scope clear. However, it does not explicitly differentiate itself from the many sibling list_* tools, relying on the resource name 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?

There is no guidance on when to use this tool versus alternatives, nor any mention of when not to use it. The description does not reference the schema's filtering parameters or sibling tools that might be more appropriate for other user-related queries.

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

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

Annotations only supply destructiveHint=true, a low bar. The description adds real behavioral context beyond that: the entry it creates (start_time, no end_time), the single-running-timer constraint, and the 409 conflict response. It doesn't cover auth requirements or what the call returns.

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 action and definition before the constraint and endpoint. The trailing 'Paymo: POST /api/entries' is marginally useful API trivia rather than load-bearing 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?

No output schema exists, so the description could ideally say what the created entry looks like or what is returned. Still, for a well-specified 4-param start-timer tool, the combination of definition, constraint, and error behavior is close to sufficient.

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

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

Schema description coverage is 100%, so task_id, user_id, start_time, and description are already documented with defaults and formats. The description adds nothing per-parameter, 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+resource ('Start a running timer on a task') and defines the resulting artifact as a time entry with start_time and no end_time. This distinguishes it in spirit from paymo_create_time_entry, though that sibling is never named, so the differentiation is inferred 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?

Gives clear usage context: one running timer per user, and the 409 response if one is already active. It stops short of naming alternatives (e.g. use paymo_stop_timer first, or paymo_create_time_entry for a completed entry), so the agent must infer the routing.

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

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

Annotations only declare destructiveHint=true; the description adds real behavioral context: the end_time defaults to now, and the resulting duration must be at least 1 minute — a validation constraint not derivable from the schema. It does not disclose permission/error behavior, so it is good but not exhaustive.

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: the core action and default lead, the constraint follows, then the discovery hint. Zero filler and the most important information is front-loaded.

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

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

No output schema exists, but for a simple mutation the description covers the action, the default, the validation constraint, and the endpoint. Minor gaps around error/permission behavior keep it just under 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 the schema already documents all three parameters including the end_time default. The description restates the now-default and the entry_id meaning without adding format or edge-case detail, so baseline 3 applies.

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

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

States a specific verb (Stop) and resource (running timer), and the mechanism (setting end_time). It is trivially distinguishable from the sibling paymo_start_timer and from paymo_update_time_entry.

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

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

Explicitly routes the agent to paymo_list_time_entries with running_only=true to locate the target, which is genuine workflow guidance. It stops short of stating exclusions (e.g., what to do if no timer is running, or use of update_time_entry instead), so not a full 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 supply only destructiveHint=true, so the description must carry the rest, and it does add real context: the partial-update guarantee ('Only the fields given are changed') and the overwrite semantics of 'users replaces the whole list', which is exactly the kind of destructive behavior an agent needs warned about. It stops short of permissions, error handling, or what happens to omitted vs. empty values.

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

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

Front-loaded with the action and its full field list, followed by one short behavioral caveat and the endpoint reference. Dense but every clause maps to a real capability; the 'Paymo: PUT /api/tasks/{id}' tail is marginal but cheap.

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, the description covers the mutation semantics, the overwrite hazard on assignees, and the endpoint, which is what an agent needs to call it safely. Missing are failure modes (invalid task_id/status_id) and whether changes are reversible, which the destructiveHint alone does not clarify.

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 is already documented, and the description's field mapping (complete/incomplete, tasklist_id/workflow status) largely restates it. The 'users replaces the whole list' note duplicates the schema's own 'New FULL list of assignee user ids' text, adding no new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

Names a specific verb (update) and resource (task), then enumerates the exact mutation surface: rename, re-describe, reassign, due date, priority, complete/incomplete, move task list or workflow status. This clearly separates it from siblings like paymo_create_task, paymo_get_task and paymo_update_time_entry.

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 enumeration of editable fields, and 'Only the fields given are changed' signals the partial-update contract. However, it never states when to prefer this over alternatives (e.g. create vs update, or how it relates to paymo_update_time_entry), nor any preconditions such as the task needing to exist.

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

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

Annotations already declare destructiveHint=true, so the mutation risk is signaled in structured data. The description adds the entry-type model (date+duration vs start/end) and the endpoint mapping (PUT /api/entries/{id}), which is useful context. It does not disclose partial-update semantics, permissions, or whether unspecified fields are cleared — meaningful gaps for a mutation with no 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?

Two sentences, front-loaded with the verb and editable fields, then the one constraint that would actually cause a bad call. The endpoint reference is short and earns its place. No filler.

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

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

For a 7-parameter mutation with only one required field, no output schema, and annotations limited to destructiveHint, the description covers the core editing model but leaves the update semantics ambiguous — PUT suggests replacement, yet the agent cannot tell whether omitted fields are preserved or cleared. Adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the entry-type restrictions. The description's only marginal addition is the cross-reference telling the agent to use end_time rather than duration_seconds for start/end entries. Baseline 3 applies where 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+resource ('Edit a time entry') and enumerates the editable surface (description, task, length), so an agent can distinguish it from paymo_create_time_entry, paymo_list_time_entries, and paymo_update_task. It does not name a sibling to route against, but the verb/resource pairing 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 an explicit conditional: duration_seconds applies only to date+duration entries, and for start/end entries the agent should change end_time instead. That is real when-to-use guidance inside the tool's own parameter space. It stops short of stating when to prefer this tool over siblings or what prerequisites exist (e.g., entry ownership).

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