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

No annotations exist, so the description carries the full behavioral burden. It discloses the shape of the returned data (types plus default rate), but says nothing about pagination, auth requirements, or read-only guarantees beyond the implied 'Lists'. Adequate but incomplete for a zero-annotation 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?

A single sentence with the purpose front-loaded and no filler. The parenthetical is dense but earns its place by defining the resource. Efficient, though slightly packed.

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 low-complexity zero-required-parameter list tool with full schema coverage and no output schema, the description supplies the purpose, the resource definition, and the downstream use case. It is nearly complete, missing only return/pagination expectations.

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 query, flat_rate, and matter_id. The description adds no filter syntax or meaning beyond the schema, which is the baseline 3 case.

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

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

States a specific verb and resource (Lists ActivityDescriptions) and immediately defines the resource behaviorally: activity/expense types with their default rate. That definition alone distinguishes it from siblings like clio_time_entries_list. It stops short of naming an alternative 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?

Gives a clear usage context: needed to fill in activity_description_id correctly when recording time, which implicitly routes the agent to clio_time_entry_create. No exclusions or explicit alternatives are stated, so it falls just 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?

No annotations are provided, so the description carries the full burden. It does disclose two genuine behavioral facts: the entry must be unbilled, and the write is gated behind a preview/confirm flow. It still omits permission/auth requirements, reversibility, and what happens to fields left unspecified.

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

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

Two tight sentences with the precondition and field list front-loaded, and the write-safety workflow second. No filler; the only cost is that the compression leaves parameters like matter_id and quantity out entirely.

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

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

For an 11-parameter mutation tool with no annotations, no output schema, and 36% schema coverage, the description covers the essential confirm/preview contract and the billed constraint but leaves too many parameters and side effects unaddressed to be called 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 only 36%, so the description must compensate, and it partially does by naming date, hours, note, rate, activity description, and billable/non-billable. However, it never explains matter_id (move to another matter) or quantity (expenses), leaving meaningful parameters 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 ('Updates an existing entry') and enumerates the mutable fields, plus a key precondition ('as long as it has not been billed'). It is clearly distinguishable from creation siblings like clio_time_entry_create, 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?

Gives a concrete invocation workflow ('preview first, then confirm with the token from the preview'), which is real guidance on how to call it. It does not say when to update versus create a new entry, nor name the sibling tools, so usage selection is only implied.

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

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

No annotations, so the description carries the full burden and does so: it discloses the DELETE prohibition, catalog validation semantics (unknown path=error, unknown params=warning), the auto-wrapping of bodies in {"data": ...}, the preview→confirm handshake with token semantics, and the GET field-default behavior. These are non-obvious traits an agent could not infer from schema 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 dense sentences, each adding non-redundant information, with the method/scope statement front-loaded. Slightly overstuffed but 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 generic dispatcher with no output schema and no annotations, the description covers method restrictions, validation, body wrapping, field selection, and the write-confirmation protocol. It could still note failure modes (rate limits, auth) but is comfortably sufficient to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter, setting the baseline at 3. The description adds some real value (path is relative to /api/v4 or a full next-page URL; GET requires query.fields; body is wrapped in data), but does not re-explain method enum or confirm beyond what the schema says.

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 (performs GET/POST/PATCH) and resource (any Clio API v4 endpoint), plus the excluded method (DELETE). It distinguishes itself from siblings because it is the explicit escape hatch for arbitrary endpoints when no dedicated tool (e.g. clio_matter_get) fits.

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 operating constraints (no DELETE, validation against catalog, GET needs query.fields, writes need preview→confirm) but never says when to prefer this generic tool over the dozens of dedicated siblings like clio_matter_create or clio_contact_update. Routing guidance is implied, not stated.

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

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

With no annotations provided, the description carries the full burden and does so: it discloses the async nature (returns URL before auth completes), the browser-open attempt with a manual fallback, the user-approval step, and that tokens are stored encrypted locally. This is the kind of non-obvious behavioral context an agent needs to sequence the flow 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?

Front-loaded with the core behavior (returns URL immediately), followed by operating instructions, then verification and usage trigger. No filler sentences; each clause adds operational value.

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-parameter-required auth tool with no output schema, the description covers the return value ('the sign-in URL'), the interaction model, where tokens are stored, and how to confirm success. Nothing essential to correct invocation is missing.

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

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

The single optional 'force' parameter is fully described in the schema (100% coverage), including its cancel-and-restart semantics. The description adds no meaning beyond that, which is the expected baseline when the schema does the work.

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 ('Starts the Clio Manage sign-in (OAuth 2.0)') and immediately clarifies the return behavior ('IMMEDIATELY returns the sign-in URL'). This clearly separates it from clio_auth_status, clio_who_am_i, and clio_logout, which are verification/termination siblings rather than initiation.

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 says when to use it ('on first run or whenever another tool reports that you are not signed in') and names the follow-up/verification tools (clio_auth_status, clio_who_am_i). Both the trigger condition and the alternative path 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the check reads a locally stored token and reports owner/expiry plus any in-progress sign-in, which implies a safe read. It does not state whether it makes network calls (that is only in the schema's 'verify' param), nor what happens on failure or how results are returned.

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

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

A single dense sentence that front-loads the core check and enumerates the returned facts without filler. Every clause earns its place.

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

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

For a simple, no-annotation, no-output-schema, single-optional-param tool, the description adequately covers what is reported (validity, owner, expiry, in-progress state). The main gap is the absence of guidance on the verify parameter's network implication, which is only partially recovered by the schema.

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

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

There is one optional parameter ('verify') and schema description coverage is 100%, so the schema already explains that true triggers a /users/who_am_i call. The description adds nothing about this parameter, 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?

Specific verb ('Checks') plus resource (stored Clio token / sign-in state) with enumerated outputs: validity, owner, expiry, and in-progress sign-in state. It is distinguishable from siblings like clio_who_am_i or clio_authenticate, though the description never explicitly contrasts them.

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

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

No when-to-use guidance is given, nor any mention of the closely related siblings (clio_authenticate, clio_logout, clio_who_am_i, clio_diagnostics). An agent must infer from the name alone that this is the pre-flight status check. Usage is implied at best.

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

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

With no annotations, the description must carry the behavioral burden; the verb 'Lists' implies a read-only retrieval, and it discloses the filtered dataset (unbilled time). It says nothing about pagination behavior, ordering, result size, or rate limits for an 8-parameter list 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?

Two compact sentences, front-loaded with the core behavior and the billing use case; no filler. It is efficient, though it could spend one more clause on the undocumented filters.

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

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

For an 8-parameter list tool with no annotations and no output schema, the description is thin: it omits most filter parameters, says nothing about pagination or the shape of returned matter records, and gives no prerequisite/permission 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 description coverage is 0% across 8 parameters, so the description must compensate. It only accounts for the period (start_date/end_date) and client filters, leaving matter_id, responsible_attorney_id, query, limit, and page_token entirely undocumented anywhere.

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 ('Lists matters with unbilled hours/amounts') plus the business purpose ('basis for preparing bills'), which meaningfully separates it from clio_bills_list and clio_matter_search. It does not, however, name any sibling or explicitly contrast its scope with them.

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

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

'Intended for monthly billing' and the optional period/client scoping imply the usage context, but there is no explicit when-to-use vs. when-not guidance and no routing to alternatives like clio_bills_list or clio_outstanding_balances.

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

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

With no annotations, the description carries the full behavioral burden. It helpfully implies a read-only fetch and discloses the return shape (line-item fields plus optional pre-rendered HTML), which is real added value given there is no output schema. However, it says nothing about permissions/authentication, error behavior for an invalid bill_id, or whether the HTML is expensive to generate.

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

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

Two tight sentences with the core return content front-loaded and the optional HTML mentioned last. Every clause earns its place; nothing is redundant with 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?

Because no output schema exists, the description usefully sketches the return payload (date, description, quantity, price, total, time-entry link), which is exactly what the agent needs. It remains thin on how bill_id is sourced and on error/permission behavior, so it is not fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains include_html meaningfully ('Optionally also the pre-rendered HTML of the bill'), which resolves the only non-obvious parameter, but bill_id is left entirely to inference. One of two parameters is covered, so this is partially compensating.

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 ('Returns the bill detail and its line items') and even enumerates the line-item fields, so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling clio_bills_list (list vs. single fetch) or clio_line_item_update, leaving that separation implicit.

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

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

There is no when-to-use guidance, no mention of how to obtain the required bill_id (presumably from clio_bills_list), and no exclusions relative to siblings like clio_bills_list or clio_outstanding_balances. The agent must infer the retrieval workflow from the name 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the Clio-specific semantic that a bill is the basis for an invoice, which is useful, but says nothing about pagination (page_token exists), the limit cap of 200, result ordering, or read-only/safe-to-call 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?

A single efficient sentence with the core purpose front-loaded and filters following. No padding or redundancy, though it is a bit cramped and the parenthetical interrupts the filter list.

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, zero-required, no-output-schema, no-annotation tool, the description covers the filtering axes but leaves type, limit, query, pagination, and result shape unaddressed. Adequate to attempt a call, but not complete enough to call it confidently without opening 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 only 10% across 10 parameters, so the description must compensate and it only partly does: it names state, client, matter, issue period, and overdue filtering, but omits type (revenue/trust), limit, query, and page_token. Worse, it lists five states while the schema enum includes a sixth, 'deleted', so the enumeration is incomplete and potentially misleading.

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 ('Lists bills') and names the filterable dimensions (state, client, matter, issue period, overdue). The parenthetical clarifying that a Clio bill is the basis for the actual invoice adds genuine domain meaning. It does not explicitly contrast with clio_bill_get or clio_outstanding_balances, but 'list' vs 'get' is inferable.

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 enumerates possible filters but never says when to choose this tool over siblings like clio_bill_get, clio_outstanding_balances, or clio_billable_matters_list. No prerequisites, no exclusions, no workflow context — the agent must infer usage entirely.

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

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

With no annotations, the description carries the full burden. It usefully discloses the write mechanics (preview produces a token, confirm consumes it) and adds a real caveat that the connector does not send bills to clients. It omits permissions/auth requirements, whether state changes are validated or reversible, and what happens to unspecified fields, so the safety picture is incomplete.

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 with the updated fields front-loaded, followed by the write workflow and a caveat. Every sentence adds information 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 mutation tool with no annotations, no output schema, and eight low-coverage parameters, the description covers the core fields, the confirm flow, and one important behavioral caveat. It still leaves gaps around the number parameter, the date formats, valid state transitions, and error/validation behavior.

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 only 13%, so the description must compensate. It names five of the eight parameters (subject, memo, issue/due dates, state) and clarifies that state is a workflow transition, but it never mentions the number parameter, gives no date format guidance, and only illustrates two of the five enum values.

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 (updates the bill header) and enumerates the affected fields (subject, memo, issue date, due date, state). It is clearly distinguishable from read-only siblings like clio_bill_get and clio_bills_list, so an agent can route correctly without opening the schema.

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

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

It flags the operation as a write and outlines a preview-then-confirm flow, which is genuine usage context. However, it states 'preview first, then confirm' as a rule, while the schema's own confirm description says to call with confirm=true directly when the request is complete — a mild conflict that could cause an agent to run an unnecessary preview round-trip.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the default (the signed-in user's calendars) which is genuine behavioral context, but says nothing about pagination (limit/page_token are present in the schema) or result size constraints.

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 sentence with the core resource and scoping constraint front-loaded, followed by the default behavior. No wasted words, though the compression comes partly at the cost of the undocumented parameters.

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 list tool with 7 parameters, no output schema, and no annotations, the description is minimum-viable: it explains period and default scope but omits pagination and search (query) semantics that an agent needs to call it correctly across pages.

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 only 29%, so the description must compensate. It conveys that from/to define the period and that matter_id and calendar_id act as optional filters, adding meaning to 4 of 7 parameters, but leaves limit, query, and page_token entirely unaddressed in both schema and description.

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 ('Lists calendar entries') plus its scope (a from–to period, optionally filtered by matter or calendar). This distinguishes it from clio_calendars_list (which lists calendars, not entries) and from clio_calendar_entry_create/update, though it does not explicitly name those 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?

The description implies usage via the period requirement and the optional matter/calendar filters, and states the default scope, but it never says when to prefer this over clio_calendars_list or how to scope by user/calendar recovered from another tool. Usage is inferable, not explicit, and no exclusions are given.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the write nature and the two-step preview/confirm workflow, which is genuinely useful. But it omits permissions/auth requirements, side effects, and failure behavior, and its 'token from the preview' phrasing is unclear and partially conflicts with the schema's boolean confirm=true, leaving real ambiguity.

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 core action and scoping, then the write/preview caveat. No filler, though the second sentence's 'token from the preview' phrase adds ambiguity rather than value.

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 13-parameter mutation tool with 46% schema coverage, no annotations, and no output schema, the description is thin. It covers the basic shape but leaves most parameters and any notion of the returned result (there is no output schema to defer to) unaddressed.

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

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

Schema coverage is only 46%, below the 50% threshold, so the description must compensate and largely does not. It touches only calendar defaulting, optional matter linkage, attendees, and event type, while leaving end_at, all_day, location, description, send_email_notification, and the distinction between attendee_contact_ids and attendee_calendar_ids unexplained across 13 parameters.

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 ('Creates a calendar entry ... in the user's calendar') and enumerates entry kinds (hearing, deadline, meeting), so the agent knows exactly what is produced. It does not explicitly differentiate from the sibling write/list tools (clio_calendar_entry_update, clio_calendar_entries_list), 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 concrete operational context: 'Write operation – preview first, then confirm with the token from the preview.' This tells the agent how to sequence the call. However it names no alternative tool and gives no explicit when-not-to-use guidance, and its 'always preview first' framing sits in mild tension with the schema's advice to call with confirm=true directly when the request is complete.

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?

No annotations exist, so the description carries full behavioral burden. It does disclose the write nature and the two-step preview/confirm safety flow, which is valuable. However, it does not address permissions, reversibility, what happens to unspecified fields, or return behavior.

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

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

Two concise sentences, front-loaded with the purpose then the workflow hint. No wasted words, though it could be slightly more explicit about the confirm parameter mechanics.

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 annotations, no output schema, and extremely low schema coverage, the description leaves major gaps. It does not document parameters or behavioral details needed 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 description coverage is 11% with 9 parameters, and the description only names a few fields (title, time, location, description, matter). It does not compensate for the near-total lack of per-parameter documentation in the schema.

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

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

States a specific verb (Updates) and resource (calendar entry) and enumerates the updatable fields (title, time, location, description, matter). Distinguishes itself from the read-only sibling clio_calendar_entries_list by the write verb.

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?

Adds workflow guidance: 'preview first, then confirm with the token from the preview,' which sets the calling pattern for this mutation tool. Does not explicitly name alternatives or when-not-to-use, but the flow 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?

No annotations are provided, so the description carries the full burden. It does add real behavioral context by disclosing what is returned (calendar IDs and event types), but says nothing about pagination, result ordering, or auth/permission scope. For a zero-param read tool the risk is low, but the disclosure is only partial.

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

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

A single front-loaded sentence with no filler, though the trailing parenthetical slightly interrupts the core 'lists calendars' statement. Everything present 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, the description does the necessary work of naming the return contents (calendar IDs, event types). Combined with zero parameters and no annotations, an agent has enough to call it correctly, though pagination and permission behavior remain unstated.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to compensate for. No parameter-level meaning is needed or missing.

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 ('Lists the calendars available to the signed-in user') and clarifies the payload's purpose (ids for creating calendar entries) plus the event-type enumeration. It is clearly a calendar-level listing, distinct from clio_calendar_entries_list, though it never names that sibling to sharpen the distinction.

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 parenthetical 'ids for creating calendar entries' implies the downstream use case (populate a calendar ID before calling clio_calendar_entry_create), but there is no explicit when-to-use statement, no when-not, and no routing to clio_calendar_entries_list for entry-level data. Usage must be inferred.

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?

No annotations are supplied, so the description carries the full burden. It does disclose that this is a write operation with a two-phase preview/confirm flow, which is useful behavioral context, but it omits permissions, side effects, reversibility, and what the preview returns.

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

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

Two tight sentences, front-loaded with the core action and followed by the write-flow caveat. Minor imprecision in 'the token from the preview' when the schema shows confirm accepts a boolean or string.

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

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

For an 8-parameter write tool with no annotations, no output schema, and half the parameters undocumented, the description covers the essential flow but leaves gaps around required identifiers, the type enum, and preview/error behavior.

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 50%, and the description maps several fields in prose (subject, body, date, sender/receiver = user or contact), partially compensating for direction/contact_id/received_at. It does not explain matter_id or the PhoneCommunication/EmailCommunication enum values, which the schema leaves undocumented.

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 ('logs') and resource ('a record of a phone call or an e-mail to a matter') and enumerates the covered fields. It is distinguishable from the sibling clio_communications_list (read) and clio_note_create, though it never names those siblings explicitly.

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

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

It gives a workflow ('preview first, then confirm with the token'), which is real usage guidance, but it does not name alternatives or say when this is preferable to clio_note_create or clio_communications_list. It also mildly tensions with the schema's own guidance that confirm=true should be used directly when the request is complete.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose result ordering (newest first), but says nothing about pagination behavior despite a page_token parameter, default page size, permission requirements, or the fact that only logged (not live) comms are returned.

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

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

A single dense sentence with the verb and resource front-loaded and the optional filters trailing. No wasted words, though the semicolon clause packs several ideas together.

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, 0% schema coverage, no annotations, and no output schema, the description leaves the agent guessing on pagination, limits, the type enum, and how this differs from the sibling log tool. It is materially under-specified for a tool of this breadth.

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 0%, so the description must compensate, yet it only alludes to two of seven parameters (query via 'text', received_since via 'period') and the matter/contact scoping. The type enum, limit, and page_token are entirely unexplained anywhere.

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 (lists) and resource (logged communications) and names the two subtypes (EmailCommunication, PhoneCommunication) plus the scoping entity (matter or contact). It stops short of distinguishing itself from the sibling clio_communication_log, so it is clear but not sibling-differentiating.

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 implies the retrieval context (comms of a matter or contact) but never says when to use this versus clio_communication_log or clio_contact_get, and gives no prerequisites or exclusions. The agent must infer routing from the name 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?

With no annotations, the description carries the burden and does disclose the key trait: this is a write operation requiring a preview-then-confirm handshake using a returned token. It doesn't cover permission requirements or what the create returns, but the confirmation mechanism is meaningful behavioral context.

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

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

Two tightly packed sentences, front-loaded with the create action and immediately followed by the write-flow constraint. The parenthetical field lists are dense but every element maps to a real parameter.

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 14-parameter tool with nested objects, no annotations, and no output schema, the description is adequate but leaves gaps: it doesn't clarify the required-field rules beyond the type enum, explain custom_field_values, or indicate the return shape. A bit more coverage would be needed for a 4-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 low (36%), so the description must compensate, and it does for the core params: it explains the person (first_name + last_name) vs company (name) distinction and names email, phone, address, sales_tax_number, and company link. It still omits title, prefix, date_of_birth, and custom_field_values, leaving some parameters undocumented.

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 (creates) plus the resource and its two subtypes (person vs company), and spells out the field set involved. An agent can distinguish this from contact_update/contact_get/contact_search by verb 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?

Gives clear context for the two-step write flow ('preview first, then confirm with the token from the preview'), which tells the agent how to sequence calls. It does not name alternatives or exclusions (e.g., when to prefer contact_update), so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. 'Returns' implies a safe read and the description usefully scopes what data comes back plus an optional expansion, but it omits error behavior (invalid/missing contact_id), permission requirements, and whether the matters list is paginated.

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

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

A single front-loaded sentence that delivers the return scope first, with the optional expansion flagged at the end via 'optionally also'. No wasted words, though the semicolon clause could be split for scanability.

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 no annotations, the description does a fair job enumerating returned fields, which is the key missing structured data. However, it leaves out not-found/error behavior and whether pagination applies to the optional matters list—gaps an agent may hit at call time.

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 0%, so the description must compensate. It does explain include_matters ('optionally also the list of the contact's matters') and implies contact_id selects the contact, but gives no format or id-typing detail for contact_id beyond the schema's integer type.

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 ('Returns contact detail') and enumerates the contents (e-mail addresses, phone numbers, addresses, custom fields). It distinguishes itself from contact_search/create/update via the 'get by id' semantics, though it doesn't explicitly name those 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?

No explicit when-to-use guidance, prerequisites, or alternatives are given. The only hint is 'optionally also the list of the contact's matters', which implies when to set include_matters but never says so directly or points to clio_contact_search for discovery.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing beyond the query semantics. It never says that all six parameters are optional (a query-less call presumably returns an unfiltered list), nor does it mention pagination, result caps, or ordering. 'Searches' weakly implies a read, but that is inference, not disclosure.

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

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

A single compact sentence with the primary search fields front-loaded and the optional filters trailing. Nothing is wasted, though the semicolon construction is slightly dense.

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

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

With no annotations, no output schema, six parameters at 17% schema coverage, and no required parameters, the description should do far more work. An agent still cannot tell what an empty-query call returns, how paging works, or whether ids is an alternative lookup path.

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 only 17%, so the description must compensate; it does explain query, type, and client_only, but leaves ids, limit, and page_token completely unaddressed in both schema and description. Partial compensation for a low-coverage schema lands at the baseline 3.

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

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

States a specific verb and resource ('Searches people and companies') plus the searchable fields (name, e-mail, phone), which clearly separates it from clio_contact_get and clio_contact_create. It does not explicitly name the sibling tools, 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 description notes that results can be narrowed to clients or to Person/Company, but that is parameter behavior, not usage guidance. There is no statement of when to use this search versus clio_contact_get, and no prerequisites 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?

With no annotations, the description carries the full burden, and it does disclose the important mutation traits: it is a write operation, it requires a two-step preview/confirm flow using a token, and the add_* fields are additive because 'existing ones are kept'. It omits authorization requirements, what happens to unspecified fields, and error/return behavior.

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

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

Two tight sentences: purpose and scope first, write workflow second. Every clause carries information (what is updated, what is appended, that the operation is gated), with no filler or 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?

For a 13-parameter nested mutation with no annotations and no output schema, the description covers the critical preview/confirm gate and additive semantics but supplies no parameter-level guidance, no permission requirements, and no indication of where the confirm token comes from. The most important behavior is present, yet the description is thin for the tool's 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 8% (only confirm is documented), so the description must compensate. It hints at only a few parameters ('basic details' for name/title, add_email/add_phone/add_address), leaving contact_id, company_id, first_name/last_name/prefix, sales_tax_number, custom_field_values, and the nested address object entirely unexplained.

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

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

States a specific verb (Updates) and resource (a contact's basic details), and enumerates the add-* behaviors (e-mail, phone, address) with the retention rule. It does not distinguish itself from adjacent tools like clio_contact_create or clio_contact_get, so there is no sibling routing, but the function itself is unambiguous.

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

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

Explicitly describes the write workflow: preview first, then confirm with the token from the preview, which tells an agent how to sequence calls. It does not say when to prefer this over clio_contact_create or how to scope partial updates, and 'preview first' sits in mild tension with the schema's note that confirm=true should be used directly when the request is complete.

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

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

With no annotations, the description carries the full behavioral burden. The verb 'Lists' implies a non-mutating read and the parenthetical discloses the shape of what comes back, which is useful. But it says nothing about pagination, result size, authentication/permission requirements, or behavior when parent_type is omitted.

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

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

A single front-loaded sentence with a compact parenthetical for return fields and an em-dash clause for the downstream purpose. 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?

For a one-parameter read tool with no output schema, the description supplies the key missing pieces: what is returned and why an agent would call it. Remaining gaps (omitted-parameter behavior, pagination, result limits) are minor for a simple list operation.

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 0%, so the description must compensate. 'For matters or contacts' restates the Matter/Contact enum for parent_type in natural language, which is helpful, but it does not explain what happens when the optional parameter is omitted (both types returned? error?) or how the enum maps to downstream usage.

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 ('Lists custom fields for matters or contacts') and even enumerates the returned definition fields (id, name, type, picklist options), so the agent knows this returns field definitions rather than values. No sibling tool covers custom fields, so confusion is unlikely, though the description does not explicitly contrast itself with any 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?

'Required to fill in custom_field_values' gives a real usage cue: call this first to obtain field IDs needed by value-setting operations. However, it names no alternative tool, no explicit when-not condition, and does not say whether the call is needed before creating vs. updating records.

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

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

With no annotations, the description carries the full burden, and it does disclose that this is a read-only discovery operation returning parameters, request-body fields, and response fields. It stops short of stating auth requirements, pagination behavior, or rate limits, which for a catalog-lookup tool is a minor rather than serious 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?

Two sentences, zero waste. The two operating modes (keyword search vs. specific endpoint) are stated first, and the routing advice is front-loaded before any schema-level 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?

No output schema exists, and the description compensates by explaining what is returned (parameters, request-body fields, response fields usable in the fields parameter). For a read-only, zero-required-parameter discovery tool this is nearly complete; only auth and result-limit behavior are unaddressed.

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

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

Schema description coverage is 100%, so all five parameters (path, limit, query, method, schema) are already documented in the schema. The description adds illustrative keyword examples ('matters', 'time entry', 'bills line items') and the path/method pairing, which is marginal value beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource: searches Clio API v4 endpoints by keyword, or describes a specific endpoint by method + path. This clearly separates it from the many curated sibling tools like clio_matter_get and clio_bills_list, which do not require an API catalog lookup.

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: 'Use it before clio_api_request when no curated tool exists.' It names the alternative (clio_api_request) and the condition that selects this tool (no curated tool available), leaving nothing 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?

With no annotations, the description carries the full burden. It does add a useful security qualifier ('without secrets') and implies a safe read via 'Returns', but it doesn't state read-only status explicitly, whether the call has side effects, or any latency/rate considerations.

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

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

A single front-loaded sentence with the security qualifier placed early; every enumerated item earns its place by telling the agent what the response contains.

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

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

For a zero-parameter, no-output-schema read tool, enumerating the returned fields compensates well for the missing output schema. Only the absence of usage context 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate.

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 ('Returns') plus resource ('server configuration') with an enumerated list of what comes back (region, URLs, ports, file paths, work folder, Node version, token storage). This clearly distinguishes it from sibling identity tools like clio_who_am_i and clio_auth_status, though it never explicitly names them.

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

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

No when-to-use guidance, no mention of alternatives, and no indication of when a diagnostics call is warranted (e.g. troubleshooting connectivity vs. verifying configuration). The agent must infer usage entirely.

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

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

With no annotations, the description carries the full burden and handles the most important trait: it is an explicit 'Write operation' with a preview-then-confirm gate, plus a note that the comment is 'visible in Clio next to the document'. It does not cover auth/permission requirements or error behavior, so it stops 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?

Two tight sentences, front-loaded with the operation and its effect, followed by the operational constraint. No filler; the only mild inefficiency is the 'token from the preview' phrasing that implies a parameter that isn't defined.

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-parameter mutation tool with no annotations and no output schema, the description supplies the critical missing context — that it is a write with a preview/confirm flow and where the result appears. Remaining gaps (permission needs, behavior of message/document_id, return shape) are secondary for this operation.

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 only 33%: confirm is documented but document_id and message are not. The description implies document_id targets a document and message is the comment text, and it reinforces the confirm semantics, but it doesn't fully compensate for the two undocumented parameters, so this lands at the minimum-viable level.

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 — 'adds a comment' to a 'document' — and narrows the scope to 'the current version', which cleanly distinguishes it from siblings like clio_document_write, clio_document_upload, and clio_document_comment (there is no ambiguity about what operation is performed).

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?

Clearly frames the two-step workflow: 'preview first, then confirm', which tells the agent when this write should be performed and how to stage it. It stops short of naming alternatives or exclusions, and it references a 'token from the preview' that has no matching parameter, adding slight friction.

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

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

With no annotations, the description carries the whole burden and does well: it discloses the preview-then-confirm token flow, the upload destination ('Claude' folder in the matter), that content triggers the server-side letterhead fill, and the local-copy behavior. It does not cover permission requirements or failure modes, so not quite 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?

Front-loaded with the core action and the recommended approach, and the content-format list is genuinely necessary detail. It is dense and long for one tool, with a couple of parenthetical asides that could be trimmed.

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 and no annotations, the description covers mode selection, template resolution order, content format, and filename policy well. Remaining gaps are relatively minor: no mention of what the preview returns or permission prerequisites.

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 baseline is 3, but the description adds real value beyond it by defining the markdown-lite content grammar (headings, bold, numbered paragraphs, page breaks, alignment) and the filename convention that the schema does not spell out.

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 ('Creates a new document in a matter from a letterhead / template') and immediately distinguishes itself from sibling write tools by explaining the letterhead/template-fill mechanism. An agent can tell it apart from clio_document_upload and clio_document_write.

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 between modes ('download' only for manual editing in a connected folder; 'automation' to let Clio generate) and against the no-template path (without_letterhead=true). It also states a negative condition: do not create empty documents, ask before calling if text/type/addressee are missing.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the side effect (a file is written to the work folder), the default location (default /root/Documents/Clio MCP, subfolder per matter), and the return value. It says nothing about overwrite behavior, file-size limits, permissions/auth needs, or what happens on a partial download, leaving notable gaps.

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 core action and destination, and the second sentence handles intent and the follow-up tool. Slightly dense with path details, but no wasted sentences.

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 tool with no output schema, the description covers the key return value (the file path) and the intended workflow including the follow-up upload tool. Auth requirements and error/edge-case behavior are absent, but the essential information for correct invocation is present.

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 67%, with target_dir and document_version_id already documented in the schema. The description adds the default behaviors (latest version, default work folder with subfolder per matter) which reinforces the schema, but the neglected document_id parameter has no schema description and the description doesn't explain it beyond 'a document'.

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 ('Downloads a document (or a specific version) from Clio to the work folder on the PC') plus the destination and the returned value (the file path). It also clarifies scope ('or a specific version'), so an agent can immediately tell what operation this performs.

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

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

It gives a clear purpose-driven context ('Intended for opening and editing the document with Claude') and routes the follow-up action to a named sibling ('upload the edited file back as a new version with clio_document_upload_version'). It does not, however, state when NOT to use it versus siblings like clio_document_read or clio_document_get, so exclusions are missing.

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?

No annotations are provided, so the description carries the full burden. It does disclose the shape of the return (metadata plus version id, number, size, author, date) and one important negative (no download URL), but says nothing about authorization requirements, behavior on an invalid or inaccessible document_id, or pagination/limits on version history.

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, zero filler, and the positive scope is front-loaded ahead of the exclusion. Every clause 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, the description sensibly enumerates the returned fields, which is the main thing an agent needs. It falls slightly short on auth/error behavior for a document-scoped read, but is otherwise adequate for a one-parameter lookup 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 0% and the description never mentions document_id or its format, so it does not compensate for the schema gap. The parameter is a single, self-evident integer identifier, which keeps the cost low, but nothing beyond the schema is added.

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 ('Returns document metadata and the version history') and enumerates the returned fields, making the scope concrete. It also explicitly carves itself out from the closest sibling, clio_document_download, so an agent can distinguish them without opening either schema.

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

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

Explicitly names the alternative and the condition for choosing it: no download URL here, use clio_document_download for that. It does not address how it relates to clio_document_read or clio_document_search, so routing is clear for one sibling but not the full family.

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

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

With no annotations, the description carries the burden and does well: it discloses the return modality per format, that output is inline (no disk write), pagination via offset/max_chars, and a hard cap of max 4 image pages per call. It omits auth/permission prerequisites and read-only confirmation, 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?

Front-loaded with the core action and the key differentiator, then flows into format/mode/pagination details with an arrow-mapping style that is efficient. It is somewhat dense and would read better as short bullets, but nearly every clause carries 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 dual-mode (text vs. visual OCR) tool with 8 parameters and no output schema, the description covers format routing, mode semantics, pagination, page limits, and input source options. Remaining gaps (document_version_id meaning, permissions/inline-size implications) are modest.

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 63%, and the description compensates by explaining mode's three values, the pagination role of offset/max_chars, the page_from/page_to page-image selection with the 4-page limit, and that document_id or file_path is accepted. document_version_id and document_id remain undescribed in both schema and description, a minor 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 ('Returns the content of a Clio document') and immediately scopes it with 'directly in the response – no disk access needed,' which is the key distinction from sibling tools like clio_document_download. An agent can tell exactly what it gets back versus a download or search 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?

Provides clear context for when each mode is appropriate, including a concrete example ('images – e.g. for stamps, signatures, tables') and format routing (text layer vs. scanned/image). It stops short of explicitly naming a sibling alternative to avoid, so it's strong context without full when-not guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose meaningful traits: the returned metadata fields (id, name, size, version, location) and that results paginate via page_token. It omits read-only confirmation, auth requirements, rate limits, and behavior when no filters are supplied, but the return-shape and pagination disclosure is strong for a search 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 tight sentences with the core action front-loaded, followed by return shape, pagination, and a usage tip. Every sentence earns its place 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 9-parameter, zero-required search tool with no output schema and no annotations, the description covers filters, return fields, pagination, and folder-scope behavior adequately. Minor gaps remain around default/no-filter behavior and auth, but nothing critical to calling 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 coverage is 67%, and the description maps filters to parameters (matter_id, parent_id, contact, query for name) and names 'category' for the otherwise undocumented document_category_id. It reinforces scope semantics, adding meaning beyond the raw schema descriptions.

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

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

States a specific verb (Searches) and resource (documents in Clio) and enumerates the exact filter dimensions (matter_id, parent_id, contact, query, category), so the agent can tell it apart from clio_document_read/download/get. It does not name any sibling explicitly, so the differentiation is implicit rather than stated.

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

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

The final sentence ('For the contents of a folder use parent_id + scope=children') gives concrete when-to-use guidance for a specific scenario, which is genuinely actionable. However, there is no guidance on when NOT to use it or when to prefer clio_document_get, clio_document_read, or clio_folder_list 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?

No annotations, so the description must carry the full behavioral burden. It discloses the write nature and a preview/confirm workflow, but the instruction 'preview first, then confirm with the token' slightly conflicts with the schema's statement that confirm=true can be used directly when the request is complete. It also omits permission requirements and error behavior.

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

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

Front-loaded with the core action, and every sentence earns its place by covering the default folder, the sibling tool to use for letterheads, and the write/confirm workflow. 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?

Given a write tool with six parameters, no output schema, and no annotations, the description covers the essential workflow and default folder behavior. It still leaves permission requirements and failure-mode context unstated.

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

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

Schema coverage is 67%, and the description adds meaningful detail for folder_id beyond the schema: the 'Claude' folder is created if it does not exist. However, it does not explain the name or document_category_id parameters.

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 'Uploads' and resource 'local file as a new document into a matter'. It differentiates itself from clio_document_create_from_letterhead by explicitly directing that use case elsewhere.

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 names the alternative tool for letters/filings, explains the default folder behavior when folder_id is omitted, and describes the preview/confirm flow. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: it is a write operation, it is non-destructive to prior data ('previous versions stay in the history'), and it uses a two-step preview/confirm flow. It still omits auth/permission requirements and failure behavior, but the mutation semantics are well covered.

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, no padding, with the core action front-loaded and the write-workflow caveat following immediately. Every clause earns its place.

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

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

For a 4-parameter write tool with no annotations and no output schema, the description supplies the essential action, mutation nature, and preview/confirm protocol. It is close to complete, with only permission/error-handling context 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 75%, so most parameters (document_id, file_path, name) are already documented in the schema, and the description adds no format or path syntax detail. The preview/confirm mention loosely maps to the confirm parameter but does not clarify the boolean-vs-string (token) duality.

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 ('Uploads a local file as a new version of an existing document in Clio') and adds the scope qualifier '(previous versions stay in the history)'. The phrase 'new version of an existing document' cleanly separates it from the sibling clio_document_upload, which creates a new document.

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

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

Gives an explicit workflow: 'preview first, then confirm with the token from the preview', which tells the agent how to sequence calls. It does not compare itself against siblings like clio_document_upload or clio_document_write, and the 'token from the preview' wording is not fully reconciled with the schema's confirm=true boolean, leaving a small ambiguity.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the body is REPLACED (destructive scope), that header/footer/styles are preserved, the template/base semantics, and the two-step preview/confirm requirement. However, 'preview first, then confirm with the token from the preview' is at odds with the schema's confirm description ('use it directly when the user's request contains everything needed'), leaving the mandatory-vs-optional nature of the preview slightly ambiguous.

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 core action and destruction semantics, then layers the alternative and write-flow guidance. Dense but every sentence carries information; the trailing preview/confirm sentence is the only part that could be tightened and is where the ambiguity lives.

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 mutation tool with no annotations and no output schema, the description covers destruction semantics, preserved elements, and the confirm flow well. It does not say what the call returns (e.g. new version identifier or number), which an agent would want after a version-creating write.

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 75%, and the description adds real meaning on top: it explains the base='letterhead' vs template=document distinction, specifies that content uses markdown-lite (same format as create_from_letterhead), and implies document_id targets an existing document. It adds context beyond the raw enum/property 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 (creates a new version / rewrites) and resource (existing DOCX document in Clio), and explicitly contrasts with the sibling clio_document_create_from_letterhead by referencing its markdown-lite format. An agent can distinguish it from clio_document_upload_version and create_from_letterhead without opening schemas.

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 both when-to-use ('suitable for fixing documents created by Claude') and when-not with a named alternative ('for third-party documents with complex formatting prefer downloading and editing in Cowork'). It also routes the agent through the preview-then-confirm flow, leaving little 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?

With no annotations, the description carries the full burden. It does disclose the two-phase preview/confirm write flow and the notion of a returned token, which is genuinely useful. But it omits permissions required, reversibility, what happens on failure, and return shape — significant gaps for a mutation tool.

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

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

Two tightly packed sentences with the operation type front-loaded and no filler. The 'amount (price × quantity)' aside is the only mildly ambiguous phrasing, since no 'amount' parameter exists.

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

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

For an 8-parameter mutation tool with no annotations or output schema and only 38% schema coverage, the description is thin. It covers the preview/confirm mechanism and field list but says nothing about prerequisites, side effects, or returned data, leaving the agent under-informed on a write operation.

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 only 38%, so the description must compensate. It usefully clarifies that amount = price × quantity and that expense category is optional, and hints that matter_id identifies the matter. It leaves matter_id, non_billable, and the token semantics of confirm undocumented, so compensation is partial.

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 ('Records'), the resource ('an expense (ExpenseEntry)'), and its scope ('on a matter'), then enumerates the key fields. An agent knows exactly what this tool produces without opening the schema. No competing expense sibling exists, so differentiation is untested but not needed.

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

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

It gives a procedural flow ('Write operation – preview first, then confirm with the token from the preview'), which is some guidance. However, this conflicts with the schema's confirm parameter, which says confirm=true may be used directly when the request is complete — so the 'preview first' framing is only partially aligned with the actual contract. No alternatives or exclusion criteria are offered.

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

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

With no annotations, the description carries the full burden and does disclose the essential 'Write operation' nature plus a two-step preview/confirm flow. However, it omits permission/auth requirements, conflict/error behavior (e.g. duplicate names), and reversibility, and its 'token from the preview' phrasing is at odds with the schema's boolean confirm.

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, front-loaded with the core purpose before the workflow note; little waste. The second sentence is slightly muddled by the 'token from the preview' wording that doesn't match the schema.

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

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

For a mutation tool with no annotations, no output schema, and 25% schema coverage, the description covers purpose, parenting, and the preview/confirm flow but leaves auth/permission needs, error handling, and return behavior unaddressed.

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

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

Schema coverage is only 25%, so the description must compensate, and it does by mapping the two undocumented integer params to their meaning: 'parent = Matter' (matter_id) and 'inside another folder' (parent_folder_id). The 'name' param is self-evident; only the confirm token phrasing adds confusion rather than clarity.

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

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

The description names a specific verb+resource ('Creates a folder') and precisely scopes it with the two valid parent contexts (a matter or another folder). It is clearly distinguishable from the read-side clio_folder_list by operation, though it never explicitly names or contrasts a sibling.

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

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

It offers workflow guidance ('preview first, then confirm with the token from the preview'), which is usage-relevant, but this framing actually conflicts with the schema's confirm description ('confirm=true performs the write... use it directly when the request contains everything needed'). It gives no guidance on choosing this tool versus alternatives.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Lists' implies a read operation and it discloses that documents can optionally be included, but it says nothing about permissions, what happens when neither matter_id nor parent_id is supplied, pagination, or defaults for limit.

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 sentence that leads with the core action and scope before the purpose clause. Every element earns its place and nothing is redundant.

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

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

With no output schema and no annotations, the description should ideally cover return shape and the behavior when optional scope parameters are omitted. It covers the basic intent adequately for a list tool but leaves meaningful behavioral questions unanswered.

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 50%: parent_id and include_documents are documented in the schema, while matter_id and limit are not. The description conceptually maps three parameters ('in a matter' = matter_id, 'under a given folder' = parent_id, 'optionally documents' = include_documents), but adds no detail on limit or defaults, so it only partially compensates.

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 ('Lists the folders') and clarifies scope ('in a matter or under a given folder'), which distinguishes it from clio_folder_create and the document tools. It stops short of naming a sibling explicitly, so it is clear but not fully self-differentiating.

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 trailing clause 'to find out where to store a document' gives a concrete use case, which is useful implied guidance. However, it names no alternative tool (e.g., clio_document_search) and gives no when-not-to-use conditions or prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden. The verb 'Lists' strongly implies a safe read-only operation, and it adds useful context that the output indicates default templates for the signed-in user and internal documents. It still omits auth requirements, pagination behavior, or explicit confirmation of no side effects, leaving some gaps.

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 that states the action and key output detail without any filler. Every phrase earns its place, and the structure makes the core purpose immediately clear.

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 zero-parameter list tool with no output schema, the description tells the agent what is returned (document templates including letterheads, plus default usage information). It is nearly complete, though it could explicitly note that no input is required or mention authentication, which are minor gaps for such a straightforward operation.

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

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

The tool takes zero parameters, and schema description coverage is 100% for the empty input schema. Per the rubric, a 0-parameter tool with no parameter semantics to explain receives a baseline of 4. The description adds no parameter details because none are needed.

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 ('Lists') and resource ('document templates in Clio including letterheads'), making the tool's purpose clear. It also notes the useful output detail about which template is used for the signed-in user and internal documents. However, it does not explicitly distinguish this list tool from sibling tools like clio_document_create_from_letterhead, so a 4 rather than 5.

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

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

The description only explains what the tool does, not when or why an agent should choose it over alternatives. There is no mention of prerequisites, exclusions, or related sibling tools such as clio_document_create_from_letterhead. This falls short of even implied usage 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?

With no annotations, the description carries the full burden and does well: it flags this as a write operation, describes the two-step preview/confirm protocol, and discloses the non-obvious side effect that update_original_record=true writes back to the original time entry. It stops short of covering permissions, reversibility, or preview-token lifetime.

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, front-loaded with the core mutation and followed immediately by the write-back caveat and the preview/confirm protocol. 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 an 8-parameter write tool with no annotations and no output schema, the description covers purpose, side effects, and the safety workflow. Remaining gaps are minor: what the preview returns and any permission requirements are not stated.

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 only 25%, so the description must compensate, and it does: it names description, quantity, price, date, note, and update_original_record and explains the confirm flow. It still leaves the meaning of the confirm token and the price/quantity units partly to inference.

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 ('Updates a bill line item') and enumerates the mutable fields, so the agent knows exactly what is being changed versus clio_bill_update. It does not explicitly name or differentiate itself from any sibling tool, which keeps it 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 description gives an explicit workflow: preview first, then confirm with the token from the preview, and the confirm parameter adds when to skip the preview. That is clear usage context, but there are no stated exclusions or named alternatives.

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

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

With no annotations, the description carries the full burden and does disclose the two distinct effects: local token deletion and, with revoke=true, server-side invalidation. It does not state whether the user must re-authenticate afterwards or whether local config survives, which would be useful for a sign-out tool, so it falls short of fully transparent.

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, the primary local effect front-loaded, the optional revoke behavior second. No filler or 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?

For a one-parameter, no-output-schema tool this covers the essentials. Minor gaps remain around post-logout state (next call will need re-authentication, whether anything else is cleared), but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already explains revoke (default false, server-side invalidation), so the description's restatement of the same behavior adds little. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: deleting locally stored tokens, plus optional server-side invalidation. That is unambiguous and naturally distinct from the data-CRUD siblings and from clio_authenticate/clio_auth_status. It does not explicitly name any sibling, but none is close enough to be confused.

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 title and description make the intended use (signing out) implied rather than stated, and there is no when/when-not guidance or comparison to clio_authenticate. For a self-evident terminal action this is workable, but the agent gets no explicit routing 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?

With no annotations, the description carries the full burden, and it does disclose that this is a write operation, that a preview/confirm cycle exists, and that responsible_attorney_id defaults to the signed-in user. However, it says nothing about required permissions, side effects, or failure modes for a mutation tool, and its confirm mechanism description contradicts 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 tight sentences, front-loaded with the action and affected fields. Every clause carries information, though the trailing confirm instruction is both terse and inconsistent with the schema.

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

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

For a 13-parameter mutation tool with no annotations and no output schema, the description covers the main fields and the safety flow but leaves several parameters undocumented and never addresses return values or permissions. The conflicting confirm guidance further undercuts 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 description coverage is only 8%, so the description must compensate; it names roughly half the fields (client_id, description, status, billing_method, responsible attorney, practice area, custom fields) and notes one default. It omits billable, location, open_date, client_reference, and originating_attorney_id, and adds no format or enum detail beyond what the schema already supplies.

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 ('Creates a new matter') and enumerates the fields being set, so an agent can distinguish it from clio_matter_update/get/search. It stops short of explicitly naming those siblings as alternatives, so it lands at 4 rather than 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 only usage guidance is 'preview first, then confirm with the token from the preview', which actually conflicts with the schema's confirm parameter ('confirm=true performs the write. Use it directly when the user's request contains everything needed'). This points the agent toward the opposite workflow the schema recommends, making the guidance misleading rather than merely thin.

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

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

With no annotations, the description carries the full behavioral burden; it does imply read-only via 'Returns' and discloses the exact payload, including that the unbilled-time summary is conditional. It omits auth/permission needs, error behavior, and any rate or paywalled-field caveats.

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, front-loaded with the returned fields and ending with the optional extra; there is essentially no filler. Slightly dense wording but well-structured.

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 no annotations, the description does useful work by enumerating the returned fields, so an agent knows roughly what comes back. However, it leaves the two boolean flags and the matter_id format ambiguous, which is a real gap for a 3-parameter tool at 0% schema coverage.

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 0%, so the description must carry all parameter meaning. The phrase 'Optionally also a summary of unbilled time' hints at include_unbilled, but include_related_contacts and the format/expectation for matter_id are left undocumented in both schema and description.

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 ('Returns matter detail') and enumerates the payload contents (client, custom fields, account balances, statute of limitations, relationships, related contacts), so an agent can distinguish it from clio_matter_search or clio_matter_update. It does not explicitly name the sibling alternatives, which keeps it from a 5.

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

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

There is no guidance on when to use this over clio_matter_search (to find a matter) or clio_billable_matters_list. The presence of a required matter_id implies a by-ID lookup, but the description never says so or states prerequisites.

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

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

With no annotations, the description carries the full burden. It discloses the shape of the return ('basic details including the matter id'), but says nothing about read-only safety, pagination behavior despite a page_token param, default/max limits, or permission requirements. Useful workflow context, but substantial behavioral gaps remain for a 9-param 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?

Two dense sentences with zero filler; the searchable dimensions are front-loaded and the return value follows. Nothing needs trimming.

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 search tool with no annotations and no output schema, the description covers the core filtering story but omits pagination, ordering, limit defaults, and incremental-sync semantics (updated_since). Adequate, 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 only 44%, and the description compensates for the documented subset (query text fields, status values, client, attorney, practice area). But limit, order, page_token, and updated_since are undocumented in both schema and description, so the coverage gap is only partially filled.

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 (Searches) plus resource (matters) and enumerates the filter dimensions: text, client, status, responsible attorney, practice area. It also flags the return payload's key field (matter id). It doesn't explicitly name a sibling like clio_matter_get, so the agent must infer the search-vs-fetch split, but the purpose itself is unambiguous.

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

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

'the matter id needed by the other tools' implies a search-first workflow, which is useful routing context. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., use clio_matter_get when you already have the id). Usage 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?

With no annotations, the description carries the full behavioral burden; it does disclose that this is a write operation and that a preview/confirm flow guards it, which is valuable. However, it says nothing about permission requirements, whether omitted fields are preserved or cleared, or partial-update semantics for an 11-parameter mutation.

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 operation and its safety workflow front-loaded; little waste. The 'etc.' ending is slightly loose but does not bloat the 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?

For a mutation tool with no annotations, no output schema, and 11 parameters at 9% coverage, the description covers the core workflow but leaves most field semantics and update behavior unstated. It is adequate as a minimum viable definition but leaves real gaps for an agent to guess at.

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 only 9%, so the description must compensate, and it only names about half the parameters (description, status, attorney, practice area, custom fields, close date). Fields like billable, location, client_reference, and matter_id get no explanation, and the 'token from the preview' wording conflicts with the schema's confirm boolean/string definition, adding confusion rather than clarity.

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 ('Updates a matter') and enumerates the mutable fields, so the agent knows exactly what operation this is. It does not distinguish itself from siblings like clio_matter_create or clio_matter_get, but the purpose itself is unambiguous.

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

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

'Write operation – preview first, then confirm' gives an explicit two-step workflow that tells the agent when to preview versus when to commit. It stops short of naming an alternative tool or stating when not to use this one, 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?

With no annotations, the description carries the full burden; it does disclose the important traits that this is a write operation and that a preview/confirm handshake is involved. However, it omits permissions/authentication needs, whether notes are immutable or editable, and what the preview returns, so the disclosure is partial.

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

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

Two compact sentences, front-loaded with the action and target before the workflow caveat. No filler and 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 six-parameter mutation tool with no annotations and no output schema, the definition covers the essential two-step flow but leaves gaps an agent must guess at: mutual exclusivity of matter_id/contact_id, the date format, and what the preview call returns. Adequate but incomplete.

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 only 17% (six parameters, one described), so the description must compensate and only partly does: it maps 'subject + text' to subject/detail and hints at matter vs contact targeting. It never clarifies that exactly one of matter_id/contact_id is needed, nor explains the date pattern or the preview-token mechanics for confirm.

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

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

Names a specific verb and resource ('Adds a note') and scopes the target to 'a matter or a contact', plus the payload fields (subject + text). It is clearly distinguishable from the read-side sibling clio_notes_list, though it does not name 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?

Gives actionable workflow guidance: 'Write operation – preview first, then confirm with the token from the preview,' which tells the agent how to sequence calls. It stops short of naming alternatives or stating exclusions (e.g., when to prefer clio_communication_log instead), so it is clear context without 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose one genuine trait, the 'newest first' ordering, but says nothing about pagination (despite a page_token parameter), the default/maximum page size, or permission requirements for reading matter/contact notes.

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

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

A single short sentence with no filler, and the resource is front-loaded before the sort-order detail. It is tight, though arguably too terse given how much is left unsaid.

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 annotations, no output schema, and 5 undocumented parameters, the description is too thin. It omits pagination semantics, the mutual exclusivity of matter_id vs contact_id, the meaning of query, and any indication of return shape.

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 0% across 5 parameters, so the description must compensate. It only hints at matter_id and contact_id via 'of a matter or a contact'; limit, query (presumably a text filter), and page_token are entirely unexplained in both schema and description.

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 (lists), resource (notes), and scope (of a matter or a contact), plus a sort order. It is clearly distinguishable from the sibling clio_note_create, though it does not explicitly name or differentiate from other 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?

The phrase 'of a matter or a contact' implies the agent must supply matter_id or contact_id to scope the call, which is useful since the schema marks zero parameters as required. However, there is no explicit when-to-use/when-not guidance, no statement of mutual exclusivity between the two ID modes, and no named alternatives.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the shape of the returned data, but says nothing about pagination (despite a page_token parameter), whether results are scoped to all clients or a filtered subset, what permissions are needed, or how 'outstanding' is determined.

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

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

One compact sentence, front-loaded with the verb and resource, and every clause adds information about the returned fields. It is a sentence fragment rather than prose, but there is no waste.

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

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

No output schema or annotations exist, so the description must stand alone; it covers the returned fields but omits pagination, scope, and permissions for a two-parameter list tool. Adequate for the core purpose, incomplete for correct invocation.

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

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

Schema description coverage is 0% for both parameters, so the description would need to compensate — and it does not mention limit or page_token at all. The agent gets no clue about page size caps, pagination semantics, or what happens when the result set exceeds one page.

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 — 'Lists clients with outstanding bills' — and enumerates the returned fields (total owed, last payment, newest due date, outstanding bills), so the agent knows exactly what the tool produces. It does not explicitly contrast itself with close siblings like clio_bills_list or clio_billable_matters_list, 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?

There is no when-to-use guidance, no exclusions, and no named alternative. An agent must infer from the word 'outstanding' alone that this is the A/R aging view rather than the general clio_bills_list, and nothing tells it which 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?

No annotations are provided, so the description carries the burden, but 'Lists' communicates a read-only retrieval. Beyond that it says nothing about pagination, caching, or whether results are tenant-scoped, though for a zero-argument enumeration call the behavioral surface is small.

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

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

A single front-loaded sentence with no filler; the resource is named before the qualifier. It is efficient, though extremely terse relative to other Clio definitions.

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-parameter list tool with no output schema, the description covers what is returned but not how the two collections (practice areas vs. matter stages) are shaped or related in the response. No output schema exists to fill that gap, so a small ambiguity remains.

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 there is nothing for the description to clarify; the baseline for zero-param tools is 4. The description correctly does not invent any input 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?

States a specific verb (Lists) and the two resources returned (practice areas and matter stages), which is unambiguous. It does not explicitly contrast itself with any sibling, but the resource is distinctive enough 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 parenthetical '(for creating/updating matters)' implies the downstream use case, so an agent can infer this is reference data to fetch before clio_matter_create or clio_matter_update. There is no explicit when-to-use/when-not statement or named alternative, so the guidance stays at an implied level.

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

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

With no annotations, the description carries full disclosure burden. It usefully states this is a write operation, that the assignee defaults to the signed-in user, and that there is a two-phase preview/confirm flow. However, much of the confirm workflow is already documented in the schema's confirm parameter, and it omits permissions, idempotency, side effects, and notification behavior.

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

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

Two sentences with the purpose front-loaded and no filler. The second sentence is slightly redundant with the schema's confirm description, but the overall structure is tight and easy to parse.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the core purpose and a few key defaults but leaves many parameters and behavioral aspects unexplained. It is adequate to start a call but not complete enough to guarantee correct invocation in edge cases.

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 only 30%, so the description must compensate. It adds genuinely useful semantics not in the schema: the assignee defaults to the signed-in user, and the matter is optional. But it leaves name, description, task_type_id, notify_assignee, and statute_of_limitations undocumented, so coverage of the 10-param surface is incomplete.

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 ('Creates a task') plus scope ('for a matter (or a general one)'), so an agent can immediately distinguish it from read tools like clio_task_list. It does not explicitly name the sibling it differs from (clio_task_update), which is the only thing keeping it from a 5.

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

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

The description gives workflow guidance ('preview first, then confirm'), which is a form of when-to-use, but it names no alternative tool and offers no exclusion conditions (e.g., use clio_task_update to edit an existing task). The 'preview first' instruction also sits in mild tension with the schema's 'use confirm=true directly' guidance, leaving the agent to reconcile them.

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?

No annotations are provided, so the description carries the burden. It discloses the default behavior and sorting, which is useful. However, it does not mention pagination (despite a page_token param), rate limits, or whose auth is required beyond 'signed-in user'.

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

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

Two compact sentences, front-loaded with the filterable dimensions followed by the default. Zero wasted words.

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

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

For a 10-parameter list tool with no annotations and no output schema, the description covers the primary filters and defaults but omits pagination flow and output shape. Adequate but with clear gaps given the parameter count.

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 30%, so the description must compensate. It names the filter dimensions (matter, assignee, status, due date from–to, text) and clarifies the default assignee/incomplete behavior, mapping to several params. But it does not explain limit, page_token, or all_assignees semantics, leaving significant gaps.

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 (Lists) and resource (tasks), and enumerates the filterable dimensions (matter, assignee, status, due date, text). It distinguishes itself from siblings like clio_task_create/update by being the read/list counterpart, though it does not name a sibling 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?

Gives a clear default context ('the signed-in user's incomplete tasks sorted by due date'), which implies when to rely on defaults, but offers no explicit exclusions or guidance on when to use a different listing tool. Usage is implied 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?

With no annotations, the description carries the full burden and does disclose the key trait: this is a write operation gated by a preview/confirm step. However, it does not state permission requirements, whether unspecified fields are preserved or cleared, or whether the status change is reversible — meaningful gaps for a mutation tool.

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

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

Two short sentences, front-loaded with the mutation scope followed by the status semantics and write-workflow note. No filler. The only weakness is the slightly misleading 'token from the preview' phrasing, which does not match the schema's confirm=true mechanism.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the field set and the write workflow but omits return values, partial-update behavior, and permission/prerequisite context. Adequate but with clear gaps.

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 only 13%, so the description must compensate, and it does: it names six of the eight parameters (name, description, due date, priority, assignee, status) and clarifies the semantics of the status enum value 'complete'. Only task_id and confirm lack added meaning, and confirm is already 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?

States a specific verb and resource ('Updates a task') and enumerates the mutable fields (name, description, due date, priority, assignee) plus the status change semantics ('status=complete marks the task as done'). An agent can clearly tell this mutates an existing task rather than creating one, though it never names clio_task_create or other siblings explicitly.

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

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

Provides workflow guidance ('preview first, then confirm'), but this conflicts with the schema's confirm parameter, which says confirm=true can be used directly when the request contains everything needed. It gives no guidance on when to choose this over clio_task_create or clio_activity_update, and the always-preview-first framing may mislead an agent into an unnecessary extra call.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Lists' implies a read-only operation, but there is no disclosure of pagination, result limits, permissions, or whether the query filters server-side. For an unannotated tool this is a significant 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?

A single efficient sentence that is front-loaded with the verb and resource and wastes no words. It is appropriately sized for a simple list tool, though it could carry slightly more information without becoming bloated.

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

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

For a simple read-only list tool with no output schema, the core purpose is conveyed, but the sole parameter's meaning and the return shape (fields, pagination) are unaddressed. An agent can call it, but cannot confidently use the query filter or anticipate results.

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?

There is a single 'query' parameter with 0% schema description coverage, and the description never mentions it or explains its matching behavior. With low coverage the description is expected to compensate, and it does not, leaving the only parameter entirely opaque.

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 ('Lists') and resource ('your firm's text snippets') and adds a clarifying gloss that these are reusable phrases/shortcuts, which distinguishes it from siblings like clio_notes_list or clio_letterheads_list. It does not explicitly name a sibling it differs from, 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?

The description says only what the tool returns, with no guidance on when to call it, when to prefer an alternative, or any prerequisites such as authentication or firm scoping. Nothing tells the agent how this list tool relates to the many other list tools available.

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?

No annotations are provided, so the description carries the full disclosure burden. It helpfully reveals the default firm-wide scope and the returned page-level summary, but omits permissions, rate limits, and the shape of the returned entry list.

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

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

Three sentences, front-loaded with purpose followed by scope behavior and pagination advice. Efficient with no filler, though the third sentence could be tightened slightly.

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 tool with no annotations and no output schema, the description is only partially complete: it hints at a summary return value but does not describe the returned entry structure or pagination response fields that an agent would need.

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 70%, and the description adds real meaning beyond the schema by explaining the behavior when matter_id/user_id are absent and by naming the billing status values used for filtering. It does not, however, clarify ambiguous params like all_types or the type/status interaction.

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 ('Lists') and resource ('time entries and optionally expenses'), and enumerates the primary filter axes. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling clio_time_summary, which also returns aggregate hours/amounts.

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

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

Gives useful operational guidance: without matter_id and user_id it returns firm-wide results, and for large periods to use limit and page_token. However, it never states when to prefer this over alternatives like clio_time_summary or clio_time_entry_create, leaving the main routing decision to inference.

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