Plutio MCP by usefulapi

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

Annotations already declare write/non-destructive/non-idempotent, so the bar is lower, yet the description still adds real behavior: the hard precondition rejection and the fact that Plutio computes line totals, subtotal and total server-side. It omits auth/rate-limit context and the shape of the response, but the critical failure mode is disclosed.

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, zero filler, and the 'WRITE:' prefix plus the precondition are front-loaded. Every sentence carries distinct information (mutation type, precondition, side effect, endpoint).

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

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

For a two-parameter mutation with no output schema and no annotations gap, this covers purpose, precondition and computation behavior adequately. It could say a bit more about what is returned after the POST, which is the only remaining gap for a no-output-schema 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%, so baseline is 3. The description earns above baseline by clarifying that totals are derived server-side, which tells the agent that 'amount' is a unit price and that no total fields should be sent — meaning the description reinforces the schema rather than repeating it.

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

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

The description opens with an explicit write verb and resource ('put line items on an invoice'), scoped by a precondition ('that has none yet') and traced back to the sibling that creates the invoice. An agent can distinguish this from plutio_create_invoice and plutio_get_document_blocks without reading 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?

It names the triggering scenario ('an invoice made with plutio_create_invoice') and an explicit exclusion ('Refuses an invoice that already has an items block'), which prevents a common wrong call. It stops short of naming where to go when the invoice already has items, leaving that case unresolved.

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=false, destructiveHint=false and idempotentHint=false, so the description's job is lighter. It still adds real value by disclosing the visibility model (everyone who can see the record sees the comment), the return shape ("Returns the new record") and the underlying endpoint POST /comments.

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

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

Two short sentences with zero filler: the operation, the visibility caveat, the return value and the endpoint, all front-loaded. Nothing could be removed without losing 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 3-required-parameter create tool with full schema coverage and annotations covering the safety profile, the description covers what an agent needs to invoke it. The only modest gap is that it does not explain what the returned record contains, but "Returns the new record" is sufficient given there is no 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 description coverage is 100% and the entityType enum is self-documenting, so the schema carries the parameter burden. The description only reinforces the accepted entity kinds (task, file, conversation) and adds nothing about bodyHTML formatting, the 20k limit, or how entityId relates to entityType — baseline 3 is appropriate.

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

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

The description leads with a specific verb and resource ("post a comment") and enumerates the three target record types, so the agent knows exactly what the tool creates. The "WRITE:" prefix clearly separates it from the read-side plutio_list_comments sibling, though no alternative is named 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?

Usage context is implied rather than stated: "visible to everyone who can see that record" hints at the audience/impact, but there is no explicit when-to-use vs. when-not, and no mention of prerequisites such as needing an existing task/file/conversation id. The agent must infer that this is the write counterpart to plutio_list_comments.

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=false, idempotentHint=false and destructiveHint=false, so the safety/mutation profile is covered. The description adds value beyond that by stating the return shape ('Returns the new record') and the endpoint, which matters since there is no output schema; it does not mention permission requirements or validation failure behavior.

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

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

Three short clauses, front-loaded with the WRITE marker and the core action. Every sentence carries distinct information (action, optional relation, return value, endpoint) with 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 simple 3-parameter create tool with full schema coverage and annotations, the description covers action, optional linkage, return value and endpoint. Only minor gaps remain, such as error/validation behavior for a wrong industry slug.

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

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

Schema coverage is 100% and the schema itself explains the industry slug format and the personIds _id semantics in detail. The description only gestures at the optional person linking, adding no format or constraint detail 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 and resource ('add a company') plus the optional relationship behavior and the underlying endpoint (POST /companies), which clearly separates it from plutio_list_companies. It does not explicitly name a sibling it replaces, 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?

The 'WRITE:' prefix signals this is the creation path rather than a read, and 'optionally linking existing people' hints at the intended use case. But there is no explicit when-to-use or when-not-to-use guidance relative to plutio_create_person or the list tools; the routing is only 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?

Adds useful context beyond the annotations: no invitations are sent, the new record is returned, and it maps to POST /events. Annotations already declare it is a non-read-only, non-idempotent, non-destructive open-world write, so the remaining gaps are minor.

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 critical 'WRITE' signal. Every sentence adds useful information with 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 five-parameter create tool with no output schema, the description covers the key behavioral facts: write operation, no invitations, return value, and endpoint. Required fields are left to the schema, which is acceptable, though optional parameter behavior remains underspecified.

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 description gives no parameter-level guidance, while schema coverage is only 60%. The schema still documents required title and startDate and provides formats for dates, but isAllDay and descriptionHTML are left undocumented in both places.

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: 'add a calendar event.' The purpose is immediately distinguishable from the sibling plutio_list_events, which lists rather than creates events.

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 'WRITE: add a calendar event' phrasing implies when to use it, but it does not explicitly say when to prefer it over alternatives or mention prerequisites. Usage is inferable but not actively guided.

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?

Goes beyond the annotations by disclosing the critical behavioral guarantees: the client cannot pay it and nothing is emailed — which is exactly the reassurance needed for a write operation that is flagged non-destructive. It also discloses the return ('Returns the new record') and the underlying POST /invoices. It stops short of warning that non-idempotent calls may create duplicate invoices.

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 WRITE marker and the draft constraint, with zero filler. Every clause (draft state, no payment, no email, next-step sibling, return, endpoint) carries distinct 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 5-param mutation tool with no output schema, the description covers the safety profile, the return value, and the follow-up tool. The only minor gap is whether duplicate invocations create duplicate invoices, given idempotentHint=false.

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

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

Schema description coverage is 100%, so every parameter including the clientType enum is already documented in the schema. The description only echoes the person/company distinction and adds no format, default, or validation detail beyond what the schema provides. 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 + state ('create a DRAFT invoice for a person or company'), which cleanly separates it from plutio_list_invoices and plutio_add_invoice_items. The 'WRITE:' prefix and explicit draft qualifier make the operation 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?

Explicitly routes the agent to plutio_add_invoice_items for line items, establishing this as the create-then-populate first step. It does not explicitly say when not to use it (e.g. for existing invoices or subscriptions), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description usefully adds the return shape ('the new record with its _id') and the underlying POST /people endpoint, but says nothing about duplicate handling despite the non-idempotent hint, or about rate limits or permissions.

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 WRITE marker and the core action, then the return value and the endpoint. No sentence is 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 simple four-parameter create tool with full schema coverage and no output schema, the description supplies the essential missing piece (the returned _id) and matches the annotations. Only the non-idempotent duplication risk is left 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 every parameter is already documented in the schema, and the description's only parameter-relevant detail ('a client by default') restates the role field's own schema description. Baseline 3 is correct since the schema carries the load.

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

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

The description names a specific verb and resource ('add a person... to the workspace') and labels the operation with a leading 'WRITE:' marker, so the effect is unambiguous. It does not explicitly contrast with the closest sibling, plutio_create_company, so it stops short of the 5 tier.

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 'add a person' framing implies when to use it and the default 'client' role hints at the common case, but there is no explicit guidance about when to prefer plutio_create_company or plutio_list_people, nor any stated prerequisites or duplicate-handling 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description reinforces this with an explicit "WRITE:" label. More valuably, it discloses side effects the annotations cannot: a default status and a first task board are created, and the new record is returned. It does not mention permission/auth requirements, but the side-effect disclosure is substantive.

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

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

Three short sentences, front-loaded with the "WRITE:" marker, and every clause carries information (effect, side effects, follow-up tool, return value, endpoint). No filler or repetition of schema data.

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 6-parameter create tool with no output schema, the description covers the mutation, its automatic side effects, and the return value, while the schema covers all field semantics. It lacks guidance on resolving clientId/clientType before calling, which is the one gap an agent might trip on.

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 (name, dueDate, clientId, clientType, startDate, descriptionHTML) is already documented with format patterns and enum values. The description adds no additional parameter semantics such as whether clientType defaults are enforced server-side, 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?

"WRITE: create a project" gives a specific verb and resource, and the description adds scope details (default status, first task board, POST /projects) that make the operation unambiguous. It is not explicitly differentiated from sibling creates like plutio_create_task, but the resource noun does the disambiguation implicitly.

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 statement of when to use this versus alternatives or what preconditions apply (e.g. whether clientId must be resolved first via plutio_list_people or plutio_list_companies). The only routing hint is a follow-up pointer: use plutio_list_task_boards to find the auto-created board.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real value on top: new tasks default to incomplete, the created record is returned, and the underlying call is POST /tasks. It does not mention failure modes such as an invalid taskBoardId or a board that does not belong to the project.

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?

Five terse fragments with the operation class and target front-loaded, followed by the dependency, the default state, and the return value. Every clause carries information an agent needs; nothing is padding.

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 six-parameter write tool with no output schema, the description covers the dependency chain, default state, and a summary of the return, which is enough to call it correctly. It leaves out error behavior and constraints on optional fields, but 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 coverage is 100%, so the baseline is 3, and the description earns an extra point by explaining where taskBoardId comes from and that the projectId filter ties the board to its project — a relationship the schema's one-line property descriptions do not convey. It says nothing about dueDate, taskGroupId, or descriptionHTML, but those are adequately documented 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?

Opens with an explicit operation class ("WRITE") and a specific verb+resource ("add a task to a project's task board"), which separates it cleanly from plutio_update_task and plutio_list_tasks. An agent can identify the operation and target entity 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?

Gives a concrete prerequisite chain: obtain taskBoardId from plutio_list_task_boards using a projectId filter, which is the main thing an agent could get wrong here. It stops short of stating when not to use this tool (e.g., batching or updating an existing task instead), so it is clear context rather than full 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 establish read-only, non-destructive, open-world behavior. The description adds useful context about what is returned (textHTML and invoice line items) and the underlying GET endpoint, though it omits error behavior and pagination details.

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 compact and front-loaded: it states what the blocks contain, explains the document-record relationship, and notes required parameters. Every sentence contributes useful 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 simple read-only retrieval tool with complete input schema coverage and no output schema, the description sufficiently explains the returned content and the reason the tool exists. An agent can invoke it correctly without additional context.

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

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

Schema coverage is 100%, so both required parameters are fully documented in the schema. The description reinforces that entityType and entityId are required and names the valid document types, but adds little beyond the schema itself.

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 specifies the exact resource: content blocks of a contract, proposal, or invoice, including textHTML and invoice line items. It also clarifies that a document record only holds block ids, which distinguishes this retrieval tool from document-list tools.

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

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

It clearly indicates when this tool is needed: to retrieve the actual content behind block ids on a contract, proposal, or invoice. It does not explicitly state when not to use it or name alternative tools, but no direct sibling alternative exists.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful context by naming the HTTP endpoint (GET /businesses) and listing the workspace fields returned, which helps the agent understand the operation's output and network involvement.

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

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

The description is a single, front-loaded sentence followed by the endpoint shorthand. It contains no filler and conveys the key information efficiently.

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 no-parameter read operation, the description gives enough context: the resource, the fields returned, and the underlying HTTP call. Annotations cover the safety profile, and no output schema is necessary because the description lists the return values.

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 no parameters, so the schema has nothing to document. Per the rubric, a zero-parameter tool receives a baseline of 4, and the description appropriately does not invent parameter details.

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

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

States a specific resource (the workspace for this API client) and enumerates the returned fields (name, domain, currency, locale, timezone, settings). There is no sibling tool that overlaps this purpose, so the agent can identify it immediately.

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 use case is implied by the description and the absence of parameters, but there is no explicit statement of when to call this versus other tools. Given that no sibling provides workspace context, the implied usage is reasonably clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral context by disclosing the response envelope { count, next_skip, items } and the pagination continuation contract. It omits page-size defaults and total-count semantics, but nothing contradicts 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?

Dense and front-loaded: resource meaning first, then return shape, paging contract, single-record mode, filtering modes, endpoint. Five short clauses, no filler, no repetition of the 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 correctly compensates by spelling out the return envelope and pagination loop, and annotations cover the read-only profile. What's still missing is any hint about what fields a category record actually has, which matters for constructing 'filters' or 'sort' values on an unfamiliar resource.

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 already carries documentation, and the description largely restates it — 'pass next_skip as skip' duplicates the skip parameter text, and 'pass id to read one record' duplicates the id text. The only marginal addition is naming the two filtering styles side by side, which the schema already explains in more detail.

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

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

States the resource (categories used to organize time entries and transactions), the read semantics, and the endpoint GET /categories, so the agent can tell this is a read-only list of category records. It never explicitly says 'list' as a verb and offers no differentiation from the many other list_* siblings (statuses, custom_fields, folders), which keeps it below 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?

Gives clear in-tool routing: 'Pass id to read one record', 'Filter with exact-match fields or a MongoDB-style query', and 'pass next_skip as skip for the next page'. That tells the agent which mode to pick for single-record vs filtered vs paged access. It does not say when to choose this tool over a sibling category-adjacent tool, so no exclusion guidance.

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

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

The annotations already declare this as a safe, read-only, non-destructive operation. The description adds useful behavioral context beyond annotations: the return shape { count, next_skip, items }, the pagination continuation pattern, and the GET /comments endpoint.

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

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

The description is compact and front-loaded: purpose, covered entity types, return shape, pagination, single-record mode, filtering, and endpoint are all stated without filler. Each sentence carries operational 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?

Although there is no output schema, the description explains the return envelope and pagination continuation. With fully documented parameters and read-only annotations, it provides enough context for an agent 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 defines every parameter. The description still adds value by explaining the relationship between next_skip and skip, the special single-record behavior of id, and the distinction between exact-match filters and MongoDB-style query.

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: it lists comments, scoped to tasks, files, and conversations, and names representative fields returned. It is clearly distinguishable from the sibling create_comment tool.

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

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

It gives practical usage guidance: pass id to read one record, use exact-match filters or a MongoDB-style query, and use next_skip as skip for pagination. It does not explicitly state when not to use it or name alternatives, but the list-vs-create distinction is clear from the 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds the response envelope and the next_skip paging loop, which is real behavioral context. It does not say how filters and query combine when both are supplied, nor how large the collection is, but for a read-only list tool this is solid.

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

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

Four short sentences, each carrying distinct information — resource identity, return shape, paging, then filtering — with the identity and response shape front-loaded. The trailing "GET /companies." is nearly free but is the one clause that does no work for an agent choosing a tool.

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

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

With no output schema, the description correctly supplies the return envelope { count, next_skip, items } and the continuation rule, which is the main thing an agent cannot infer. Six optional parameters are all schema-documented, so the remaining gap is only interaction behavior when multiple filter inputs are combined.

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 mostly restates it — "pass next_skip as skip" and "filter with exact-match fields or a MongoDB-style query" mirror the schema's own wording for skip, filters, and query. It adds no format or precedence detail 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?

Names the resource and disambiguates it domain-wise with "clients that group people," which separates it from the many create_* siblings and from list_people. The list semantics come from the sibling-name pattern and from "Returns { count, next_skip, items }", but the description never says outright "lists companies" — it leads with a noun definition.

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 routing: "Pass id to read one record" (single-record fetch instead of a filtered list), the paging contract, and a choice between exact-match filters and a MongoDB-style query. It stops short of stating when to prefer filters over query, or when to reach for a different list tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the exact response envelope { count, next_skip, items }, the paging contract, and the underlying GET /contracts endpoint.

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

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

Telegraphic but zero waste — fields, the document-blocks pointer, return shape, paging, id mode, filtering, and endpoint, all front-loaded in five compact sentences. Nothing repeats the schema or the annotations.

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 six optional parameters and no output schema, the description carries the burden well by spelling out the return envelope and the pagination loop. The only residual gap is what an item's field values look like, which it partly offloads to plutio_get_document_blocks rather than explaining.

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, and the description still adds operational meaning: next_skip maps to skip for the following page, id switches the call into single-record read mode, and it clarifies the split between exact-match filters and MongoDB-style query. It does not add syntax detail beyond the schema's own examples.

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

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

The description names the resource and enumerates the fields a contract carries (name, client, status, signatures), plus it separates the document-text concern by pointing to plutio_get_document_blocks. That is enough to tell it apart from plutio_list_invoices or plutio_list_proposals, though it never explicitly contrasts itself with those sibling list tools.

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

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

It gives concrete usage modes: pass id to read a single record, use exact-match filters or a MongoDB-style query to narrow, and feed next_skip back as skip to page. It stops short of saying when to prefer query over filters or when not to use this tool at all.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value on top: the response envelope { count, next_skip, items }, the paging contract (feed next_skip back as skip), and the single-record mode via id. It does not mention rate limits or whether the query/filters are combined with AND, which keeps it shy of 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?

Five short sentences with zero filler, and the most important facts (resource, return shape, paging) are front-loaded. The telegraphic fragment style is dense but slightly harder to parse than full sentences, which is the only reason it is not a 5.

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

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

There is no output schema, so the description must explain return values — and it does, giving the envelope keys and the pagination token flow. Combined with the record-read mode and filtering options, an agent has enough to call it correctly; only secondary details (default sort, auth requirements, filter/query interaction) are absent.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the input schema, including the same pagination hint ('pass the previous reply's next_skip'). The description largely restates that, adding only the linkage between the returned next_skip and the skip input; baseline 3 applies when the schema carries the load.

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

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

States the resource precisely ('Inbox conversations') and names the fields returned (subject, participants, last message), so an agent knows exactly what collection this enumerates. It also pins the underlying endpoint (GET /conversations). It stops short of an explicit verb like 'list' — that is inferred from the paging/return-shape language — and there is no sibling list tool for conversations to differentiate against.

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 mode-selection guidance inside the tool: pass 'id' to read one record, use 'filters' for exact match versus 'query' for MongoDB-style operators. That tells the agent how to shape a call but not when this tool should be chosen over alternatives (e.g. list_comments or list_notes for adjacent content), so selection guidance is only 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the exact return envelope ({ count, next_skip, items }), the pagination protocol (pass next_skip as skip), and the underlying endpoint. It stops short of noting rate limits or default ordering.

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

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

Two very dense sentences with no filler, and the return shape is front-loaded right after the resource definition. The opening is a noun fragment rather than a verb phrase, which slightly weakens the front-loading, 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 takes on the job of explaining the return envelope and pagination, and it does so correctly. For a six-parameter, zero-required list tool this is close to sufficient; only a note on default sort/paging behaviour and query error handling 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 every parameter including id, skip, sort, limit, query and filters is already documented in the schema. The description restates the query ('MongoDB-style') and paging ('pass next_skip as skip') but adds no syntax or edge-case detail beyond what the schema already carries, 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?

The description names the resource ('custom field definitions') and enumerates the salient content (label, type, which records they apply to), plus the endpoint GET /custom-fields. The listing verb is only implied by the title and the paginated return shape, but an agent can tell this apart from sibling list tools by 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?

It hints at variants ('Pass id to read one record') and explains paging and filtering, which is useful selection guidance within the tool. However, it never says when an agent should reach for this tool versus something else, and no prerequisites or exclusions are stated.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: response shape { count, next_skip, items } and the next_skip-to-skip pagination loop. It does not mention auth or rate-limit considerations, keeping it below 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?

The description is compact and front-loaded: resource fields, return shape, pagination, id lookup, filtering, and endpoint are each stated once with 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?

For a no-output-schema list tool, the description supplies the missing return shape, pagination contract, and filtering modes. With annotations covering the read-only profile and the schema covering parameters, nothing essential is left ambiguous.

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 thoroughly. The description reinforces id, skip, filters, and query usage, but adds little beyond what the schema descriptions already say; the event field list is not parameter guidance.

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 identifies the resource (calendar events), lists representative fields, and states the HTTP operation (GET /events), so an agent can tell this is a list/read tool. It does not explicitly compare itself with siblings such as plutio_create_event or plutio_list_schedulers, 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?

It explains two key usage modes: pass id to read one record, or use filters/query to list. It also explains pagination flow, but it does not state when to choose this tool over adjacent list tools or when not to use the id mode.

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?

Adds two facts annotations cannot convey: file contents are not downloaded (metadata only) and the exact return shape { count, next_skip, items }, which is important since there is no output schema. Pagination mechanics are spelled out. It does not address scoping/visibility or error behavior, so 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?

Five short clauses, each carrying distinct information, with the most decision-relevant facts (no contents, return shape, paging) up front. No filler or restated 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?

Covers everything an agent needs for this 6-parameter, zero-required list tool: what is returned, how to page, how to fetch one record, and how to filter. With readOnly/openWorld annotations already present and no output schema, nothing material is left dangling.

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 earns extra by clarifying the pagination contract (next_skip -> skip) and framing the filters-vs-query split. It does not explain when to prefer filters over query, or whether id is mutually exclusive with the rest.

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 (file records) and enumerates the record fields (name, size, folder, sharing). The sibling tools are nearly all create/list, but this description never explicitly contrasts itself with plutio_list_folders, which an agent could plausibly confuse it with.

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

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

Gives concrete routing: 'Pass id to read one record' and 'Filter with exact-match fields or a MongoDB-style query', plus the paging loop via next_skip. It stops short of any exclusion or prerequisite (what happens if id and filters are combined, what permissions 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 already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the response envelope { count, next_skip, items }, the pagination contract (pass next_skip as skip), and the endpoint. It does not mention auth requirements or rate limits, but for a read-only list tool the added pagination and response-shape detail is substantive.

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

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

Six short clauses, zero filler, with the response shape and pagination rule front-loaded before filtering details. Every sentence carries operational 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 supplies the return shape and pagination cursor, and all six params are documented in the schema. Annotations cover the safety profile. Only the absence of any sibling-routing guidance or permission notes keeps it short of 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 every one of the six parameters is already documented in the schema with examples and constraints. The description's parameter mentions (id, skip/next_skip, filters, query) largely restate what the schema already says, so it lands at the baseline 3 rather than adding new semantics.

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

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

The description names the resource (file folders) and states the HTTP endpoint GET /file-folders, making the operation inferable. However, it never uses an explicit verb like "list" in the body and does not distinguish folders from the numerous sibling list tools (e.g. plutio_list_files, plutio_list_projects) beyond the resource 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?

It explicitly describes two usage modes — "Pass id to read one record" versus paged listing — and explains the two filtering strategies (exact-match fields vs MongoDB-style query). It gives clear operational context but offers no guidance on when to choose this tool over a sibling list tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the concrete return envelope { count, next_skip, items } and the pagination contract, which is real behavioral information the agent needs. It omits auth requirements and rate limits, and the GET endpoint line is context rather than 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?

Four tight sentences: the resource, the return shape, the paging rule, the single-record mode, and the filtering options, all front-loaded. Nothing is redundant or padded.

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 7 optional parameters, no output schema, and 100% schema coverage, the description supplies the missing return shape and paging workflow, which is what an agent most needs. Only the absence of any cue about how this relates to plutio_list_forms keeps it from being 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%, so every parameter including id, skip, sort, limit, query, formId, and filters is already well documented with examples. The description reinforces the two most decision-relevant paths (id for a single record, query/filters for narrowing) but adds no syntax or constraints 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?

The description names a specific resource and operation: 'Submitted responses to forms,' with a single-record mode noted via 'Pass id to read one record.' It is distinguishable from the sibling plutio_list_forms by naming responses rather than forms, though it never explicitly contrasts the two.

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 explains how to page ('pass next_skip as skip for the next page') and how to narrow results (exact-match fields vs. a MongoDB-style query), which covers operating modes. It says nothing about when this tool is preferable to plutio_list_forms or any other listing sibling, and there are no exclusions.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the description only needs to add operating detail — which it does by disclosing the return envelope ({ count, next_skip, items }), the pagination handoff, and the underlying GET /forms call. No auth, rate-limit, or scope caveats are mentioned, keeping it short of 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?

Five short clauses, front-loaded with the resource and fields, then return shape, then paging, then filtering. Nothing is redundant or padded.

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 six optional parameters, no output schema, and nested filter objects, the description supplies exactly the missing pieces: the response envelope, how to page with next_skip, and the two filtering modes. An agent can invoke it correctly from this text plus 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 coverage is 100% and every parameter is already documented (id, skip, sort, limit, query, filters). The description restates the skip/next_skip relationship and the id read behavior but adds no syntax or edge-case meaning 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 the resource concretely ('Forms (intake forms, questionnaires)') and what fields come back ('name and status'), which is enough to separate it from plutio_list_form_responses 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?

It gives operational guidance ('Pass id to read one record', 'Filter with exact-match fields or a MongoDB-style query') but never says when to use this over sibling list tools or what the filter paths exclude. Usage is implied through mechanics rather than stated as selection criteria.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the return shape { count, next_skip, items } and the pagination contract (pass next_skip as skip), which the annotations cannot convey. Missing details like auth or rate limits keep it below 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?

The description is dense and front-loaded: fields first, then return shape and paging, then id/query usage, then the endpoint. The leading field enumeration is somewhat list-like, but every sentence 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 present, the description usefully explains the response envelope and paging. All 7 parameters are covered by the schema (including the nested filters object), so the description is adequate for correct invocation. Deeper behavioral details (e.g., max page-size interplay with limit) are left implicit.

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 id, skip, sort, limit, query, status and filters. The description's notes on status values and MongoDB-style queries restate rather than extend 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?

The description names the resource and enumerates the fields an invoice carries (name, client, status, amount, dueDate, etc.), plus the endpoint GET /invoices, so the agent knows it is a read/list of invoice records. It does not explicitly distinguish itself from siblings such as plutio_list_invoice_subscriptions or plutio_create_invoice, which is what a 5 would require.

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?

'Pass id to read one record. Filter with exact-match fields or a MongoDB-style query' gives clear guidance on how to select records with the flexible parameters. There are no explicit when-not-to-use notes or named alternatives for other invoice operations.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it states the return shape ({ count, next_skip, items }) and explains the pagination convention of passing next_skip as skip, which is valuable because there is 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?

The description is compact and front-loads the resource and return shape before covering paging, single-record reads, filtering, and the endpoint. Every sentence contributes, though the terse field list at the start is slightly cryptic.

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 six-parameter read-only list tool with no output schema, the description covers the important gaps: return shape, pagination continuation, single-record access, filtering modes, and the underlying GET endpoint. It is not fully complete on sibling differentiation or auth/rate-limit context, but it gives an agent enough 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 coverage is 100%, and the schema already documents id, skip, sort, limit, query, and filters in detail. The description reinforces the main workflows (read one record, page with next_skip, exact-match filters or MongoDB-style query), but it largely restates schema-level information rather than adding new parameter semantics, so the baseline 3 is appropriate.

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

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

The description clearly identifies the resource as recurring invoice subscriptions and names key fields (client, schedule, amount). It does not explicitly distinguish this from the sibling plutio_list_invoices, but the recurring-subscription framing is specific enough to separate it from generic invoice listing.

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 operational guidance for reading one record, filtering, and paging, but it does not explicitly say when to use this tool versus plutio_list_invoices or other list tools. Usage is implied by the resource name rather than stated with alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: the exact response envelope ({ count, next_skip, items }), the paging contract ('pass next_skip as skip'), and the underlying endpoint GET /notes — exactly the context an agent needs to chain pages.

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 dense sentences, front-loaded with what the resource contains, then the return shape, then the parameter cheat-sheet. Every clause carries information; the telegraphic 'Notes: title, ...' opener is slightly terse but not wasteful.

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 correctly supplies the return envelope and pagination mechanism, and it explains the id-vs-filter branching for a 6-parameter optional-param tool. Only minor gaps remain — no mention of the default page size or sort behavior, both of which the schema covers.

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 id, skip, sort, limit, query and filters in detail. The description restates the same facts (id for single-record read, next_skip paging, exact-match vs MongoDB-style filtering) without adding syntax or precedence rules beyond the schema. Baseline 3 applies.

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

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

The description enumerates the resource's fields (title, descriptionHTML, entityType, entityId) and ends with 'GET /notes', making it unambiguous that this is a listing endpoint for notes. It is clearly distinct from siblings like plutio_list_comments or plutio_list_tasks, though it never explicitly states 'list notes' as a verb+resource phrase — that comes from the name/title.

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?

'Pass id to read one record' and 'Filter with exact-match fields or a MongoDB-style query' give operational guidance on how to use the parameters, but there is no statement of when to choose this tool over a sibling (e.g. notes vs comments) or any exclusion/precondition. Usage is implied by the schema rather than argued for.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered by structured data. The description still adds genuine unannotated behavior: the { count, next_skip, items } envelope, the 'pass next_skip as skip' paging contract, and the underlying GET /people endpoint. Extra credit for the return shape and pagination, but no detail on defaults, permissions, or rate limits.

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

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

Front-loaded with what people are, then mode selection, then paging, then filtering, then endpoint. Every clause carries information; nothing is repeated from the schema or annotations.

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 7 parameters, no output schema, and rich annotations, the description fills the important gaps: return envelope, paging loop, and filter strategies. It stops short of describing what an 'items' record actually contains or how 'filters' and 'query' interact, so 4 rather than 5.

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; the description goes beyond the schema by explaining the id-versus-list mode switch and the pagination handshake ('pass next_skip as skip'), which are cross-parameter behaviors the schema cannot express. It could additionally say whether 'query' and 'filters' can be combined, which keeps it at 4.

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?

Opens with a concrete verb-resource pair and immediately defines the resource's scope: clients plus own team members, with the fields carried (name, role, contactEmails, contactPhones, companies). This implicitly separates it from plutio_list_companies and plutio_create_person, though it never names those siblings explicitly, which keeps it just 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?

Gives clear mode selection: 'Pass id to read one record' versus bulk listing, and distinguishes exact-match filtering ('filters') from MongoDB-style predicates ('query'). It does not state when-not to use it or explicitly point at alternatives such as list_companies, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the return envelope { count, next_skip, items } and the paging contract, which is real behavioral value. It does not mention rate limits or whether openWorldHint=true implies unbounded result sets, but the paging contract mitigates that.

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, pagination and return shape front-loaded ahead of the filter notes. The opening field list ('name, client, status, dates, budget, billing rate') is telegraphic and slightly ambiguous as to whether those are fields or arguments.

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 8 optional parameters, no output schema, and nested filter objects, the description supplies exactly what the schema cannot: the response envelope, the paging loop, and the id-for-single-record shortcut. Nothing essential for a correct call 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 the baseline is 3. The description's parameter notes (id for a single record, next_skip for paging, query for MongoDB-style filtering) largely restate what the schema already documents, adding no format or precedence guidance beyond it.

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

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

The description names the resource (projects) and enumerates the fields it carries, plus the concrete endpoint 'GET /projects', which makes the read/list operation unambiguous against siblings like plutio_create_project. The verb is only implicit (the title supplies 'List'), so it stops short of a full verb+resource statement.

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?

'Pass id to read one record' and 'Filter with exact-match fields or a MongoDB-style query' clearly describe the available usage modes, and the pagination instruction ('pass next_skip as skip') is actionable. It stops short of saying when to prefer filters over query, or when to use this tool versus searching other resources.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description usefully adds the response envelope and the next_skip/skip paging contract, which annotations cannot express, but says nothing about whether archive/status filters change scope or about ordering defaults.

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?

Five short clauses, front-loaded with the resource and its fields, then paging, then filtering. The telegraphic style ('Proposals: name, client, status, amount') is efficient but slightly fragmented for a reader who does not already know the schema.

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

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

With no output schema, the description supplies exactly the missing piece: the { count, next_skip, items } envelope and how to page with it. Combined with the fully documented parameter schema and read-only annotations, an agent has everything needed to call this six-parameter, no-required-argument 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 coverage is 100% and most of the description's parameter notes ('pass next_skip as skip', 'pass id to read one record') restate the schema. The one genuine addition is the conceptual split between exact-match 'filters' and MongoDB-style 'query', but the schema already illustrates both with examples, so the marginal value is small.

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

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

Names the resource and its characteristic fields ('Proposals: name, client, status, amount'), and 'Returns { count, next_skip, items }' plus 'GET /proposals' makes the list operation unambiguous. It is distinguishable from nearby siblings like plutio_list_invoices only implicitly through the resource name, not through an explicit contrasting statement.

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 routing: document text lives elsewhere ('see plutio_get_document_blocks') and 'Pass id to read one record' tells the agent to use this same tool for single-record reads instead of looking for a get_proposal sibling. It does not state exclusions (e.g. when a search tool would be better), 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 already declare readOnlyHint and destructiveHint=false, so safety is covered. The description adds real behavioral context: the return shape ({ count, next_skip, items }), the pagination flow ('pass next_skip as skip'), the single-record read mode, and the backing endpoint GET /scheduler.

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 resource, then return shape, pagination, read mode, and filtering in tight telegraphic sentences. Dense but every clause carries information; minor loss of readability from the fragment style.

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 the description supplies the response envelope and pagination mechanics, and annotations cover the safety profile. For a 6-param, all-optional list tool this is nearly complete, missing only explicit alternative-routing guidance.

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%, establishing the baseline of 3, but the description adds genuine value beyond it: the id-as-read-single-record behavior and the pagination linkage between next_skip and skip are semantics not obvious from raw parameter docs.

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

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

States a specific resource ('Scheduling pages (booking links) and their settings') and the operation is clear from the name/description. The resource is distinct from all siblings, so an agent can tell it apart, though it never names an alternative tool by name.

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 explains two modes (list vs. 'Pass id to read one record') and two filtering mechanisms, which implies when to use each. However, it does not say when to prefer this over any sibling or state preconditions, leaving routing largely to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the return envelope { count, next_skip, items } and the pagination contract, which the agent needs to iterate correctly.

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 clauses, all front-loaded: resource and fields first, then return shape, then paging, then lookup/filter modes. Telegraphic style but every sentence carries information; nothing is repeated for padding.

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 six optional parameters, a nested filters object, and no output schema, the description covers the critical gaps: it describes the response envelope and the paging loop, which the schema cannot. Only the absence of filterable-field lists and sortable-field guidance keeps it short of full completeness.

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 every parameter is already documented, including the skip/next_skip linkage and the MongoDB-style query format. The description restates those points rather than adding new semantics such as which fields are sortable or which filter keys exist for statuses, 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?

Identifies the resource precisely (custom statuses for projects and similar records) and enumerates the key fields returned (title, type, entityType), plus the endpoint GET /statuses. It lacks an explicit verb like 'list' and doesn't name a confusable sibling, but the resource distinction against list_projects/list_custom_fields is clear.

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 operational guidance on how to use the modes it supports — pass id to read a single record, next_skip for the next page, exact-match filters vs a MongoDB-style query. It does not say when to prefer this over the other list tools (e.g., list_custom_fields or list_projects), so selection guidance is only implied by the resource 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the paging contract (pass next_skip as skip), the return envelope, and the fact that it maps to GET /task-boards. It doesn't discuss result sizes or rate limits, keeping it short of 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?

Five short sentences, front-loaded with the resource definition before paging and filtering mechanics. Nearly every sentence earns its place; the 'GET /task-boards' fragment and the slightly elliptical opening cost it a point.

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 7 parameters, no output schema, and a nested filters object, the description covers the essentials: what is returned, how to page, how to read one record, and the two filtering modes. It would be complete at 5 with a note on how query and filters combine or which fields are commonly filtered.

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 skip/next_skip loop and the query syntax. The description reinforces the paging usage and points at `id` for single-record reads, but adds no new syntax or constraint detail. Baseline 3 applies.

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

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

The description names the resource and adds domain context ('A project has one or more boards that hold tasks'), which distinguishes it from siblings like plutio_list_tasks and plutio_list_task_groups. The verb is only implied by the resource phrase rather than stated outright, but the return-shape sentence ('Returns { count, next_skip, items }') makes the list semantics unambiguous.

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

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

It gives operational guidance ('Pass id to read one record', filter via exact-match or MongoDB-style query) but never states when to prefer this tool over plutio_list_tasks, plutio_list_projects, or plutio_list_task_groups. Usage is implied by the projectId parameter and the board/task hierarchy sentence, not explicitly routed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral detail beyond that: the response shape { count, next_skip, items }, the pagination loop, and the GET /task-groups endpoint.

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

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

It is dense and front-loaded: identity, return shape, paging, single-record read, filtering, endpoint. The opening fragment 'Task groups (columns/lists on a task board)' is terse but purposeful; 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?

For a 7-parameter, no-output-schema list tool, the description supplies the return shape, the pagination loop, and both filter mechanisms. Combined with the annotations and full schema coverage, an agent has what it needs 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 baseline would be 3. The description earns extra by explaining the pagination contract ('pass next_skip as skip for the next page') and summarizing the two filtering modes (exact-match filters vs MongoDB-style query) that the schema documents in detail.

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

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

The description names the resource and clarifies it as 'columns/lists on a task board', so the agent knows exactly what entity is being listed. It's a clear list operation but doesn't explicitly contrast itself with siblings like plutio_list_task_boards or plutio_list_tasks.

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

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

It states concrete usage paths: 'Pass id to read one record' and 'Filter with exact-match fields or a MongoDB-style query', giving the agent clear invocation context. It stops short of stating when NOT to use it or naming an alternative sibling.

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

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

Annotations already cover readOnly/openWorld/non-destructive, and the description adds genuinely new behavior: the exact response shape { count, next_skip, items }, the pagination contract, and the single-record read path. It does not mention default page size (only the schema does) or error behavior, keeping it short of 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?

Extremely dense and front-loaded: fields first, then return shape, then paging, then filter strategy. The telegraphic 'Tasks: title, status (...)' opener is slightly cryptic but wastes no 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?

With 10 optional parameters, a nested filters object, and no output schema, the description does the important work: it explains the return shape, paging loop, and the two filtering mechanisms. Minor gaps remain around sort/limit and taskGroupId, but an agent can call this correctly from the description plus 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 the baseline is 3; the description earns extra credit by enumerating the filterable field names (title, dueDate, assignedTo, projectId, taskBoardId) and the status enum values, which helps an agent construct filters. It omits sort, limit, and taskGroupId semantics that the schema carries.

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

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

The description names the resource (Tasks), the filterable fields, and the endpoint (GET /tasks), so there is no ambiguity about what is returned. It implicitly separates itself from plutio_list_task_boards / plutio_list_task_groups by scoping to tasks, but never states that distinction 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?

It gives concrete usage modes: 'Pass id to read one record' versus 'Filter with exact-match fields or a MongoDB-style query', plus the paging loop (pass next_skip as skip). It does not say when to prefer this over siblings such as plutio_create_task or plutio_update_task, but for a read tool the operational guidance is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real behavioral context by specifying the return envelope { count, next_skip, items } and the chaining rule that next_skip becomes the next call's skip. It does not cover permissions, rate limits, or the cost of the openWorld query surface, so it falls short of 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 sentences, no filler, dense with usable information. It is slightly front-loaded on the field inventory rather than the action, which delays the agent's confirmation of what the tool does, 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 correctly supplies the response shape and pagination contract, and it explains both filtering modes for a tool with nine optional parameters and a nested filters object. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100%, so all nine parameters are already documented in structured data; this is the baseline case. The description only reinforces a few of them (id, skip chaining, filters vs query) and adds no syntax or format detail beyond what the schema carries.

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 identifies the resource (time entries), enumerates its meaningful fields, and reveals the endpoint GET /time-tracks, so an agent knows this is the time-entry listing tool. It doesn't name the natural sibling relationship, e.g. that plutio_log_time is the write counterpart, but the resource is unambiguous among siblings.

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

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

It gives operational routing inside the tool: 'Pass id to read one record' and 'Filter with exact-match fields or a MongoDB-style query', plus paging via next_skip. What's missing is when to prefer this over alternatives — there is no mention of when to use plutio_log_time instead, or of any exclusions.

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

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

Annotations already cover read-only safety, but the description adds genuinely useful behavior: the return envelope { count, next_skip, items } and the pagination contract of feeding next_skip back as skip. That is context an agent cannot get from 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?

Telegraphic fragments, but every clause carries information: fields, return shape, pagination step, single-record mode, filter modes, endpoint. Dense and front-loaded with no filler, though the fragment style costs a little readability.

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 steps in to explain the response envelope and paging, which is exactly what's needed for a paginated list tool. It leaves sort/limit details to the schema, which already documents them fully.

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 goes slightly beyond by naming concrete filterable fields (amount, currency, client, invoiceId, status, type, issueDate), which helps an agent choose filter keys rather than guessing.

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 the resource (transactions / GET /transactions) and scopes it to payments and expenses, then enumerates the fields available. It's clear what the tool returns, though it never explicitly says 'list' in prose and doesn't differentiate itself from the many other list_* siblings beyond naming the domain.

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

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

It gives implied usage: pass id to read a single record, use exact-match filters or a MongoDB-style query to filter. However it never states when to use this versus plutio_list_invoices or plutio_list_invoice_subscriptions, which is the main ambiguity in this sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the exact return shape { count, next_skip, items } and the pagination contract of feeding next_skip back as skip, which an agent cannot infer from annotations alone.

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 resource, then the return/pagination contract, then the filtering modes, then the endpoint. Every sentence carries distinct information and there is 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?

Although there is no output schema, the description supplies the return envelope and the pagination cursor rule, plus the single-record read path and both filtering modes. For a six-parameter, all-optional list tool with rich annotations, nothing an agent needs 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?

Schema description coverage is 100%, so all six parameters are already documented in the schema, and the description largely restates them (id for one record, exact-match filters, MongoDB-style query). It adds no syntax or format detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description names the specific resource (Plutio wiki / knowledge base pages) and pairs it with the underlying endpoint GET /wiki-entities, which makes the tool's scope unambiguous against siblings like plutio_list_projects or plutio_list_notes. It is a noun phrase rather than an explicit verb ('list'), but the title plus the endpoint resolve that, and no sibling covers the same resource.

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

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

It clearly separates the two usage modes: pass id to read one record versus listing with exact-match filters or a MongoDB-style query. There are no exclusions or 'when not to use' statements, but since no sibling tool overlaps with wiki pages, the main selection ambiguity is internal (single vs list), which is addressed.

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=false, destructiveHint=false, openWorldHint=true and idempotentHint=false; the description reinforces the write nature and adds the non-obvious referential constraint that projectId must match the task's project. It stops short of warning that retries will create duplicate entries, which the non-idempotent hint implies.

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

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

Three terse sentences, front-loaded with the WRITE marker and the resource, then the constraint, then the unit, then the endpoint. No filler sentence.

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 six-required-parameter mutation with no output schema, the definition covers the main failure mode (wrong projectId) and unit confusion. It omits whether startedAt/stoppedAt must be internally consistent with the time value, which would be a useful completeness addition.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by disambiguating the unit ('time is the length in seconds, 5400 = 1.5 hours') with a concrete conversion example and by flagging the cross-parameter constraint tying projectId to taskId. It says nothing about startedAt/stoppedAt relationship to time, leaving a small gap.

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

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

States a specific verb and resource ('record a time entry against a task') and prefixes it with 'WRITE:', making the mutation nature and the object unambiguous. An agent can immediately distinguish it from the read-only siblings like plutio_list_time_entries.

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

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

Gives a concrete precondition — read the task first, and use that task's own projectId — which steers the agent to a preceding lookup call. It does not explicitly name the sibling to read from or describe when not to use it, but the guidance is actionable.

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 and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-redundant behavior: partial-update semantics, that the updated record is returned, and the underlying PUT /tasks endpoint. It could still warn that overwriting descriptionHTML replaces the existing body, which is what makes a partial update destructive.

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 after a front-loaded "WRITE:" tag; the partial-update caveat and return value each carry weight and nothing is padded.

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

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

For a 5-parameter mutation with no output schema, it covers the mutation contract, partial semantics, and return shape adequately. The missing pieces are the required id and any overwrite warning for descriptionHTML.

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 60%, and the description largely restates what the schema already declares (title, status enum values, due date, description HTML). It does not mention the required `id` parameter at all, so it fails to compensate for the coverage gap on the one parameter without a schema explanation.

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?

"WRITE: change a task's title, status, due date or description" gives a specific mutation verb plus resource and enumerates the mutable fields, which is enough to separate it from plutio_create_task. It stops short of naming any sibling or stating the precondition (task must already exist), so it isn't fully 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?

"Only the fields you pass change" implies partial-update usage and steers the agent away from full-object replacement, which is real guidance. However there is no explicit when-to-use vs. plutio_create_task, no note that the task id must come from a list call, and no exclusion guidance.

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