Clio MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, and the "WRITE:" prefix is consistent with them. Beyond that the description adds little behavior: it does not mention that setting send_email_notification will email attendees, nor any duplicate-creation risk implied by non-idempotency. Useful but not rich context on top of the annotations.

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

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

Front-loads the operation type and resource in the first clause, then the calendar_id resolution hint. The trailing "Clio: POST /calendar_entries.json" is of marginal value to an agent choosing the tool, but overall the definition is tight 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 10-parameter create tool with no output schema, the description covers what is created, where, and how to resolve the required calendar_id; the remaining fields are fully documented in the schema. Only the side effects of send_email_notification and any confirmation/return shape are 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?

Schema coverage is 100%, so the baseline is 3; the description earns a point by explaining where calendar_id comes from (default_calendar_id via clio_who_am_i), which the schema only calls "the calendar's numeric Clio id." The matter linkage is also mentioned, though summary/start_at/end_at/all_day/fields are left entirely to the schema.

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

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

States a specific verb and resource ("Put an event on a Clio calendar") and immediately scopes it with concrete examples (hearing, meeting, deadline) plus the optional matter link. This clearly separates it from sibling creation tools like clio_create_task or clio_create_note without needing to name them.

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

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

Gives an actionable prerequisite: calendar_id defaults to the token user's default_calendar_id from clio_who_am_i, which tells the agent how to obtain the required value before calling. It stops short of explicit exclusions or alternatives (e.g., check clio_list_calendar_entries for duplicates, or use clio_create_task for to-dos), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the mutation profile is covered. The description adds value beyond them by spelling out which identifier fields are needed per contact type, reducing the chance of a rejected or malformed create. It stops short of warning about duplicate creation despite idempotentHint=false.

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

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

A single dense sentence with the write intent and the person/company split front-loaded — no wasted preamble. The trailing 'Clio: POST /contacts.json' endpoint note adds little for an agent and is the only filler.

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

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

With 12 parameters but 100% schema coverage and a full annotation set, the description only needs to cover the create semantics, which it does. No output schema exists, yet the 'fields' override parameter is left unexplained in the description — minor, since the schema documents it.

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

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

Schema description coverage is 100%, and the schema already documents each field including the person/company distinction for 'name'. The description restates that same person-vs-company mapping for the required fields but adds no syntax, format, or default details beyond the schema, 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 ('Create a contact') and immediately clarifies the two shapes it can take — person via first_name/last_name, company via name. The 'WRITE:' prefix distinguishes it from the read-oriented siblings like clio_get_contact and clio_list_contacts, though no sibling 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?

Gives conditional guidance for the two input modes (person vs company) and says email/phone are optional, which is useful. But it never says when to prefer this over alternatives such as updating an existing contact or searching first to avoid duplicates, leaving the agent to infer that.

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 the write, non-idempotent, open-world and destructive profile. The description adds the useful prerequisite that the client contact must exist and the Clio endpoint, but it does not explain duplicate-creation risk or side effects beyond what annotations cover.

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?

Very short and front-loaded, with the WRITE marker and core action first. Every sentence contributes necessary calling context without repetition.

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?

Adequate for invocation because the schema documents all 11 parameters and annotations cover safety traits. However, for a create tool with no output schema, the description omits what the call returns and does not warn about duplicate matters.

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 parameters are already documented in the input schema. The description only restates the two required parameters (client_id and description) and adds no format or optional-field guidance beyond the schema.

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

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

States a specific verb and resource: opening a new matter for an existing client contact. It distinguishes creation from the get/list matter siblings implicitly through 'new matter', but does not explicitly name alternatives.

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 clear context that the client contact must already exist and names the two required inputs. It does not state when not to use it or explicitly point to get/list alternatives, but the create-vs-retrieve distinction 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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the agent knows the safety profile. The description adds the 'WRITE:' intent marker and the underlying endpoint (POST /notes.json), but says nothing about permissions/scope requirements, whether the created note is returned, or error behavior when the id is missing.

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 dense sentences with the action verb front-loaded and the branching rule immediately after. Nothing is wasted and 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 straightforward create operation with fully described parameters and annotations covering safety, the description is nearly sufficient. The only real gap is that no output schema exists and the description never says what a successful call returns, though the 'fields' parameter implies a note object comes back.

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

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

Schema coverage is 100% across all 7 parameters, so the schema already documents type, detail, date, subject, fields, and the conditional id fields. The description's contribution is restating the conditional type→id pairing in one compact rule, which is useful but largely duplicative of the schema's own per-field descriptions.

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

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

States a specific verb and resource ('Add a note') and immediately disambiguates the two target modes with the exact parameter pairing required for each (type Matter + matter_id / type Contact + contact_id). An agent can distinguish this from clio_list_notes or clio_create_task without opening any schema.

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

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

Gives clear conditional guidance for choosing the matter vs. contact variant, which is the main decision point for this tool. It does not mention read-side alternatives or exclusions, but the selection context is unambiguous.

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=true, openWorldHint=true and idempotentHint=false, so the safety profile is known. The description adds the "WRITE:" framing and the underlying endpoint (POST /tasks.json), which is modest added context. It says nothing about side effects an agent would care about—notably that notify_assignee can trigger an email to the assignee, or what permissions are required.

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

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

Two short sentences with the operation type front-loaded and no wasted prose. The trailing "Clio: POST /tasks.json" is mildly redundant with openWorldHint but is compact and harmless.

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

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

For a 12-parameter mutation tool with no output schema, the description covers intent and the main optional axes but omits what the call returns (presumably the created task object) and says nothing about the four required fields or the notify side effect. Adequate given the fully documented schema, but not complete.

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

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

Schema description coverage is 100% with enums documented, so the schema carries the parameter burden and a 3 is the baseline. The description adds light semantics beyond that—assignee may be a User or Contact and matter linkage is optional—but does not explain required fields or the interaction between assignee_type and assignee_id.

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

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

States a specific verb+resource ("Create a task") plus the key scoping facts: assignee can be a firm user or contact, matter attachment is optional, due date and priority are supported. It is clearly distinguishable from siblings like clio_create_calendar_entry or clio_create_note by resource, though it never names an alternative 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?

No guidance on when to use this versus alternatives (e.g. clio_create_note for non-assigned work items) and no exclusions or preconditions. The only usage signal is the implicit "create" verb, leaving the agent to infer context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description earns credit by adding the unit transformation (hours decimal converted to seconds before sending) and the default-resolution rules for price and user_id, which are genuine behavioral facts not in the annotations. It doesn't explain why the tool is flagged destructive (billing impact, reversibility), leaving a small gap.

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

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

Front-loaded with the 'WRITE:' marker, then three dense sentences covering semantics, unit conversion, and defaults, ending with the API mapping. No filler, though the endpoint reference is only marginally useful to an agent.

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

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

It covers inputs, units, and defaults well, but with 9 parameters, a mutation, no output schema, and destructive annotation, it should say more about what's returned (the presence of a 'fields' override implies a shaped response) and about the destructive/billing consequence. Adequate but with clear gaps for a write tool.

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

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

Schema description coverage is 100%, so each parameter is already documented, including the same price and user_id default notes that appear in the description. The only meaning added beyond the schema is the hours conversion ('1.5 = 90 minutes; it is sent to Clio as seconds'), which is useful but marginal, so the baseline of 3 applies.

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

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

The description leads with a specific verb+resource ('Record ... time on a matter') and even names the underlying endpoint (POST /activities.json with type TimeEntry). It doesn't explicitly differentiate from sibling creators (calendar entry, note, task), but the resource is unambiguous enough that an agent can distinguish it 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?

Clear context and useful defaults are stated: omitting price applies the firm's rate hierarchy, omitting user_id records for the token's user. It does not, however, address when to use this versus listing/updating activities, or any prerequisites beyond the implied matter_id requirement.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the returned bill components, but does not add auth, error, or rate-limit context beyond 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?

The description is two short sentences with no wasted text. The core action and scope are front-loaded, and the endpoint reference is a compact supporting detail.

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?

This is a simple read-by-id tool, annotations cover its safety profile, and the schema fully documents both parameters. Although there is no output schema, the description lists the main returned components (state, totals, balance, client, matters), which is enough for an agent to understand what it gets back.

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 bill_id and fields are already documented in the input schema. The description reinforces that lookup is by id but does not add syntax or semantics beyond what the schema provides, making the baseline score of 3 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 states a specific verb and resource: fetch a single bill by id. It also names the returned components and the underlying endpoint, and 'single bill by id' distinguishes it from the sibling list_bills 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?

The phrase 'by id' implies the tool is used when a specific bill id is known, but it does not explicitly say when to use this versus clio_list_bills or state any preconditions. Usage is therefore implied rather than fully 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?

Annotations already declare readOnly, idempotent, non-destructive, and openWorld behavior, so the safety profile is covered. The description adds useful behavioral context by disclosing exactly which related data is returned (emails, phones, addresses, web sites, custom fields) and noting that picklist values are option ids requiring clio_list_custom_fields. It does not mention error behavior (e.g., 404 for missing contacts) or permission requirements.

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

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

The description is two compact sentences with zero waste. The primary purpose and return scope are front-loaded, followed by the implementation endpoint reference.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so by enumerating the included sub-resources and the custom field value format. For a simple read-by-id tool with full annotation coverage and complete parameter documentation, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both contact_id and the optional fields override. The description adds meaning beyond the schema by explaining that custom field values come back as field_name + value and that picklist values are option ids, which helps the agent interpret results. It does not add detail about the fields parameter, but the schema handles that adequately.

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 (Fetch), resource (a single contact), and lookup key (by id), clearly distinguishing it from sibling list/create tools such as clio_list_contacts and clio_create_contact. It also enumerates the returned sub-resources, making the tool's scope 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?

The phrase 'by id' implicitly directs the agent away from list/search tools when the numeric id is known, and it explicitly points to clio_list_custom_fields for interpreting picklist values. However, it does not explicitly state when not to use this tool (e.g., when the id is unknown and clio_list_contacts should be used instead).

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, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds value beyond that by disclosing which related resources are expanded and warning that picklist custom-field values are option ids requiring a lookup — a real behavioral caveat an agent would otherwise hit at runtime.

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

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

Two tight clauses plus the endpoint reference; the core action and scope come first and every element carries information. Nothing is padding, even the picklist parenthetical.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does name the major fields and the custom-field value encoding. It does not describe the full response envelope or how attorneys/practice area are nested, leaving a small gap for a read tool with an openWorld annotation.

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

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

Schema coverage is 100% and both parameters are documented, so the baseline is 3. The description still adds meaning by enumerating what the default response shape contains, which effectively explains the consequence of omitting the `fields` override, and by qualifying the domain of matter_id as a Clio numeric id.

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

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

States a specific verb and resource ("Fetch a single matter by id") and enumerates the returned sub-resources (client, practice area, stage, attorneys, custom field values), which cleanly separates it from the sibling clio_list_matters. An agent can pick it out without opening the schema.

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

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

The "single matter by id" framing makes the list-vs-get split clear, and it explicitly routes the agent to clio_list_custom_fields to interpret picklist values. It stops short of an explicit "for many matters use clio_list_matters" exclusion, so it is clear context rather than 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the distinction between `quantity` (seconds) and `quantity_in_hours` (hours), which is a real trap in the returned data, plus the underlying endpoint. It stops short of noting pagination caps 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?

Three compact sentences with no filler: what it lists and returns, what you can filter on, and one unit caveat. The core purpose is front-loaded and everything after it earns its place.

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

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

With no output schema and 13 optional parameters, the description plus the fully-described schema gives an agent everything needed to call it. The only minor gap is that pagination behavior (page_token/offset interplay, the 10,000-record cap) is left entirely to schema descriptions rather than surfaced in the prose.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is already documented with enums, defaults, and bounds. The description restates the filterable dimensions but adds no formatting or constraint detail beyond the schema; the seconds/hours note concerns return fields, not parameters. Baseline 3 applies.

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

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

States a specific verb and resource ('List activities') and enumerates the three kinds of records returned (time entries, expense entries, fixed fees) along with the fields surfaced (hours, rate, total, billing status). This clearly separates it from write-side siblings such as clio_create_time_entry and from clio_list_bills.

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 sentence 'Filter by matter, user, type, status or date range' implies how the tool is used, but it never says when to pick this tool over alternatives (e.g., clio_list_bills for billing data, or clio_get_matter for a single matter's context). Usage is inferable but no exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds only the underlying endpoint and the shape of returned data — useful because there is no output schema — but says nothing about rate limits, page caps, or default page size behavior beyond what the schema already documents.

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 purpose and filters, ending with the endpoint. No redundant or filler text.

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 15 optional parameters and no output schema, the description usefully names the fields returned and the available filter axes, and pagination/ordering details are fully covered in schema descriptions. Only the choice between offset and page_token and sibling routing 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% and every parameter (type, state, order, date bounds, overdue_only, page_token, offset, fields) carries its own documentation with enums and formats. The description only restates the filter dimensions at a high level, adding no syntax or semantics beyond the schema.

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

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

States a specific verb and resource ('List bills (invoices)') and enumerates both the returned data (state, totals, amount due, dates) and the filter dimensions. It is clearly distinguishable from clio_get_bill by plurality, though it never names that sibling explicitly.

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

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

The filter list implies when to use it (narrow by client, matter, state, overdue, dates), but there is no explicit 'use clio_get_bill when you know the ID' routing or any statement of when not to use it. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered and the description does not contradict it. The description adds the recurrence-expansion behavior and a pointer to the underlying REST call, which is light added value but nothing on permissions, pagination loop behavior, or result shape beyond what the schema already says.

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

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

Three compact sentences: purpose and scope first, then the recurring-event flag, then the API reference. Every clause earns its place and nothing is buried or repeated.

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

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

For a 12-parameter, optional-only list tool with no output schema, the description gives the agent enough to select it and understand the primary filters and the recurrence mode. It could say more about paging workflow and what a returned entry contains, but the schema carries the per-parameter burden well.

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 12 parameters, including the from/to window semantics and offset/page_token distinction, is already documented in structured form. The description merely re-surfaces 'expanded' and the matter/calendar filters without adding format, precedence, or interaction detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('List calendar entries'), concretely illustrates the domain objects ('hearings, meetings, deadlines'), and states the core scoping dimension (a time window) plus the optional drill-downs (one matter or calendar). Nothing about it could be confused with the create_* siblings or any other list tool in the set.

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

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

It clearly frames the usage context — 'in a time window, optionally for one matter or calendar' — and explains when to flip a mode flag ('Set expanded=true to get each occurrence of recurring events'). It stops short of naming alternatives or exclusions (e.g., when to reach for create_calendar_entry or a differently filtered list), 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 declare readOnly/idempotent/non-destructive and openWorld, so safety is covered. The description adds genuinely useful context beyond that: what records are being listed, which fields come back by default, and the underlying Clio endpoint (GET /communications.json), which helps an agent reason about scope. It stops short of describing pagination behavior or result caps.

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

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

Two tight sentences: the first front-loads what is listed and what comes back, the second covers filtering and search. No filler, no redundancy with 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 usefully names the returned fields, and annotations already cover the safety profile. For a 14-parameter list tool, the main remaining gap is that pagination and ordering workflow (page_token vs offset, the 10,000-record cap) is left entirely to the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in-schema. The description only restates the filter categories in prose without adding syntax, defaults, or interaction details (e.g. how query combines with type). Baseline 3 is appropriate 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 a specific verb and resource ('List logged communications — phone calls and emails recorded on matters') and enumerates the returned content (subject, body, date, senders, receivers). It implicitly contrasts with the write sibling clio_log_communication, but never names an alternative listing tool or clarifies scope boundaries explicitly.

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

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

The description lists the available filter dimensions (matter, contact, user, type, date range, subject/body search), which implies how to narrow results. However, it gives no explicit when-to-use versus when-not guidance, no mention of pagination workflow despite 14 params including page_token/offset, and no routing to a 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile carries itself. The description adds the wildcard-match scope and the custom-field filtering behavior, but says nothing about result volume, pagination expectations, or the 10,000-record cap beyond what the schema states.

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

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

Three tight sentences: the resource scope first, then the two non-obvious filtering mechanisms, then the underlying endpoint. 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 14 optional parameters and no output schema, the description covers the resource scope and the two search mechanisms well enough to invoke correctly. It leaves the shape of a returned contact record unaddressed, which is a minor gap given there is no output schema to fall back 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 coverage is 100%, so the schema already documents all 14 parameters in detail. The description reframes `query` and the custom_field_id/custom_field_value pairing in prose, but adds no syntax or format detail beyond the schema, 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 ('Search and list contacts') and enumerates the record categories covered (clients, prospective clients, companies, opposing parties, co-counsel). The list-vs-get distinction against clio_get_contact is inferable but never stated explicitly, so sibling routing is left to the agent.

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

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

The description explains two mechanisms (wildcard `query` and the custom-field pair) but never says when to prefer this tool over clio_get_contact or how to page through large result sets. Usage is implied by the parameter mechanics rather than stated as guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description adds the underlying endpoint (GET /custom_fields.json) and the return shape, which is useful context but not essential behavior. Pagination behavior (next_page tokens via page_token/offset) is left entirely to the schema.

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

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

Two compact sentences, front-loaded with purpose and return contents before the usage hint and endpoint. The middle clause is dense but every clause earns its place; no filler.

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

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

For a 10-parameter, no-output-schema list tool, the description covers purpose, returned fields, and how results chain into siblings — enough to call it correctly. Pagination semantics and default field set are only implied by the schema, so it falls just 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 coverage is 100% with three enums documented inline, so the schema carries all parameter meaning. The description adds nothing about limit, order, deleted, field_type, or parent_type, 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?

Specific verb (list) plus resource (the firm's custom fields), plus explicit scope (matters or contacts) and the concrete payload (name, type, required, picklist option id + text). An agent can distinguish this from clio_list_matters or clio_list_contacts without opening any schema.

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

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

Explicitly states the downstream use: the ids feed clio_list_matters / clio_list_contacts filters and decode values returned by clio_get_matter / clio_get_contact. That is real routing guidance, though it never says when NOT to call it or what alternative to prefer.

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, idempotentHint, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond them: results are metadata only, not document bodies, and it enumerates the metadata fields returned. It does not mention pagination behavior or auth/permission requirements, but those are partly covered by the schema's page_token/offset params.

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

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

Two compact sentences, with the resource and the metadata-only caveat front-loaded before the scoping options. The trailing 'Clio: GET /documents.json' is minor traceability that doesn't help an agent act, but it costs little.

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

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

For a 12-parameter, all-optional list tool with a fully documented schema and no output schema, the description covers what the tool does, how it can be scoped, and what kind of data comes back. Sorting, paging and enum semantics are left entirely to the schema, which is rich enough to carry them.

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 every one of the 12 parameters is documented in the schema, so baseline 3 applies. The description only echoes the schema's framing — name search and matter/contact/folder scoping — without adding format, interaction (e.g. scope only applies with parent_id) 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?

States a specific verb and resource ('List documents') plus the exact scoping axes (matter, contact, folder, or name search) and the output shape ('metadata only: name, file name, type, size, category, dates'). An agent knows precisely what this returns and what it does not (no file contents), with no sibling document tool to 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?

The description makes clear the contexts in which the tool applies — listing documents attached to a matter, a contact, a folder, or searching by name — which maps directly onto the matter_id/contact_id/parent_id/query parameters. It offers no exclusions or guidance about when a different tool would be preferable, but there is no competing document tool among the siblings, so the practical gap is small.

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds the underlying endpoint (GET /matters.json) and the wildcard nature of `query`, but says nothing about paging behavior (page_token vs offset, the 10,000-record offset cap) or result size, which are real behavioral considerations for a 16-parameter list tool.

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

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

Three dense sentences, front-loaded with purpose before narrowing to the two non-obvious filter mechanisms. The trailing "Clio: GET /matters.json" is marginally useful for mapping to vendor docs but is the only element that is not strictly load-bearing.

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 0 required parameters and full schema documentation, the description covers purpose, the two search modes, and the shape of records returned, which is enough to call the tool correctly. It leaves paging strategy (cursor default vs offset with custom orders) entirely to the schema, which is acceptable given the schema documents it thoroughly and there is no output schema to explain.

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 the extra point by tying the pair together operationally — `custom_field_id` + `custom_field_value` filter one custom field, with a concrete motivating example (a court case number) — which is genuinely useful framing the schema lists but does not synthesize.

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 ("Search and list matters") and parenthetically defines the domain term for non-legal users ("the firm's cases"), plus names the enrichments returned (client, practice area, responsible attorney, status). It is clearly distinguishable from clio_get_matter and clio_create_matter by the search/list verb, though it never names a sibling explicitly.

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

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

Usage is implied by the verb (browse/search rather than fetch one record) and the custom-field example hints at a use case, but there is no explicit "use this when… / use clio_get_matter instead when…" routing and no stated prerequisites. An agent must infer the boundary from the sibling naming convention alone.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds the endpoint reference and the type requirement, but nothing about pagination limits or response shape that isn't already in the schema.

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

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

Three short sentences, front-loaded with the resource and scope, then the required constraint, then the endpoint. Nothing redundant.

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

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

For a 10-parameter read tool with no output schema, it covers scope, the required type, and which fields come back. Pagination (page_token, offset) and ordering are left entirely to the schema, which is acceptable but slightly thin for a paginated list.

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 type/matter_id/contact_id relationship is already stated in the property descriptions. The description only restates that pairing, adding no formats, defaults or examples beyond the schema.

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

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

Specific verb and resource ('List notes on a matter or a contact'), plus the returned attributes (subject, body, date, author) and the underlying endpoint. It is clearly distinguishable from the sibling write tool clio_create_note.

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?

States the hard constraint that Clio requires type and tells the agent to narrow scope with matter_id or contact_id. It does not name an explicit alternative for searching notes without a matter/contact, 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds only the underlying endpoint (GET /tasks.json); it says nothing about pagination caps, default ordering, or result shape beyond the field list, which the schema largely supplies anyway.

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

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

Two sentences, front-loaded with the resource and returned fields, followed by the filtering capability and a usage example. No filler; the endpoint reference is the only marginal 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 16-parameter, zero-required list tool with no output schema, the description conveys the returned fields and the main filter dimensions, and the schema fills in pagination and formatting. It does not discuss paging strategy or default limits, a minor gap given the offset/page_token complexity.

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

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

Schema description coverage is 100% with 16 well-documented parameters, including enums and format hints, so the baseline is 3. The description restates the filter axes (matter, assignee, status, priority, due-date range) but adds no syntax or constraint detail beyond what the schema already provides.

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

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

States a specific verb and resource ('List tasks') plus the fields it surfaces (status, priority, due date, matter, assignee), which is enough to distinguish it from clio_create_task and clio_update_task without opening either schema. The filterable dimensions are 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?

Gives clear usage context with a concrete scenario ('e.g. what is due this week') and names the filter axes that drive selection. It does not explicitly exclude or route to an alternative tool, but among the siblings the verb makes the division of labor obvious.

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, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds useful context beyond that: the scope is limited to this firm's users, and the returned ids are foreign keys consumed by other operations. It says nothing about result volume or rate limits, keeping it short of exhaustive.

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

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

A single compact sentence plus the underlying endpoint. The identifying purpose and the downstream-use hint are both front-loaded, and 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?

With seven optional parameters, all schema-documented, and no output schema, the description covers what an agent needs to select and call it. It omits any mention of the paginated response shape (next_page.page_token), though the schema's page_token description largely compensates.

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%, including enum values for role and subscription_type and pagination semantics for page_token and limit. The description adds no parameter-level detail, which is acceptable given the schema does the heavy lifting, but it earns no credit above baseline.

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

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

States a specific verb (list) and resource (the firm's Clio users), and clarifies the population as attorneys and staff, which disambiguates from generic 'users'. It does not name any sibling for contrast, but the resource is distinct enough from the other list_* tools that confusion is unlikely.

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 clause 'use their ids for responsible attorneys, time entries and task assignees' tells the agent exactly why and when to reach for this tool — before create_matter, create_time_entry, or create_task that need an assignee id. It stops short of stating exclusions or naming alternatives, so it is strong 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 declare destructiveHint=true and idempotentHint=false, and the description adds real behavioral context beyond them: it clarifies nothing is actually sent to the recipient and that recording is separate from billing. It does not warn that repeated calls create duplicate records (non-idempotency) or describe permission requirements.

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

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

Three short sentences with zero filler; the mutation marker and the core resource statement are front-loaded, and each following sentence adds a distinct fact (no send, billing alternative, 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?

No output schema exists, but the fields parameter is self-describing and the description covers purpose, side-effect semantics, and the billing companion. It omits duplicate-creation risk and return shape, minor gaps for an 8-parameter create tool.

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

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

Schema description coverage is 100%, so body, subject, type, received_at, senders, receivers, and matter_id are all self-documented, and the description's 'optionally on a matter, with who it was from and to' only cursorily echoes them. Baseline 3 is appropriate 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?

States a specific verb (Record) and resource (phone call or email on Clio's communication log) with the 'WRITE:' prefix flagging mutation. The description clearly separates it from clio_list_communications and other list-style siblings without needing 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?

Explicitly clarifies 'This only records it: Clio sends nothing' and routes time-billing to clio_create_time_entry, which is a genuine when-to-use-this-vs-alternative pointer. It stops short of saying when to prefer clio_create_note or how to avoid duplicate records, so it's strong but not exhaustive.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: this is a sparse PATCH where omitted fields are left intact, and it names the exact API endpoint. It does not mention auth/permission requirements or whether completing a task has side effects.

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, with the WRITE marker and the verb/resource front-loaded ahead of the field enumeration and endpoint detail.

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

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

For a 9-parameter mutation tool with no output schema, the description covers scope, sparse-update semantics and the underlying endpoint. Minor gaps: what the call returns and how to source task_id/assignee_id are left to the schema and siblings.

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

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

Schema description coverage is 100% with enums on status, priority and assignee_type, so the schema does the heavy lifting. The description restates the field list (status, due date, priority, name, description, reassignment) without adding format or constraint details 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?

States a specific verb (update) plus resource (task), enumerates the mutable fields, and pins the underlying operation (Clio PATCH /tasks/{id}.json). This clearly separates it from clio_create_task and the read-only clio_list_tasks sibling.

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

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

The clause 'Only the fields given are changed' communicates partial-update semantics, which is useful usage context, but there is no explicit guidance on when to prefer this over alternatives (e.g., obtaining task_id via clio_list_tasks first, or using clio_create_task for new tasks). Usage is implied rather than directed.

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, idempotent, openWorld and non-destructive, so safety is covered. The description adds value beyond that by disclosing what is returned, that the call is inexpensive, and that the token's region is implicitly validated — context an agent cannot get from the 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?

Three compact clauses with the core purpose front-loaded, then the cost/verification rationale, then the endpoint reference. No sentence is padding and nothing important is buried.

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

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

No output schema exists, so the description correctly enumerates the return payload and ties one field to a downstream write tool. The remaining gap is that it does not mention the optional 'fields' override, but the schema carries that detail 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% and the single 'fields' parameter is documented thoroughly in the schema with a nested-resource example. The description never mentions field selection at all, so it adds nothing on top of 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?

States a specific verb and resource — 'Fetch the Clio user this access token belongs to' — and enumerates the returned fields (name, email, subscription type, time zone, default_calendar_id). This clearly separates it from the sibling clio_list_users, which lists many users rather than identifying the token owner.

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?

'A cheap way to confirm the token and region are right' gives an explicit usage context, and the note that default_calendar_id is 'needed to create calendar entries' points the agent forward to clio_create_calendar_entry. It stops short of naming an alternative or stating when not to use it, so it falls just below a 5.

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