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

The annotations already indicate destructiveHint=true, so the agent knows mutations are possible. The description adds useful behavioral context about how POST/PATCH bodies are handled (data vs body wrapping). It does not disclose other behaviors like rate limits or error handling, but given the annotations, the description provides reasonable transparency.

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 concise, consisting of two sentences with no wasted words. It is front-loaded with the main action and includes essential usage details efficiently.

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

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

Given the tool's complexity as an escape hatch with no output schema, the description provides adequate context: path format, body handling, and usage examples. It could mention response format or authentication but is sufficient for an advanced agent.

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 high (83%), but the description adds critical meaning: it explains that 'data' will be wrapped in { data: ... } while 'body' is sent verbatim, and that path is relative to the API root with examples. This goes beyond the schema's 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?

The description clearly states the tool issues arbitrary requests against the Clio v4 API, specifying it's for endpoints not yet wrapped. It distinguishes from dedicated sibling tools by explicitly advising to prefer 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?

The description explicitly says 'Prefer the dedicated tools — this exists for endpoints not yet wrapped' and lists examples of unwrapped endpoints (custom_fields, trust_requests, webhooks, etc.), providing strong guidance on when to use 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?

Discloses the OAuth flow and encrypted token persistence, adding value beyond annotations. However, it could mention if multiple authentications overwrite existing tokens.

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 purpose and key constraint. No wasted words.

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

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

Adequately covers purpose, constraints, and token handling. Lacks mention of post-auth behavior, but no output schema makes this acceptable.

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?

No parameters exist; baseline 4 per instructions. Description does not need to add parameter info since there are none.

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

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

The description clearly states the tool starts an OAuth 2.0 authorization-code flow and persists tokens, differentiating it from siblings by specifying transport constraints.

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 LOCAL STDIO TRANSPORT ONLY and explains unavailability on remote deployments, providing clear when-to-use and when-not-to-use guidance.

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

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

The readOnlyHint annotation signals no mutation; the description adds the session-type context, which is useful beyond annotations. No contradictions.

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 no wasted words. Front-loaded with purpose, followed by mode-specific nuance. Efficient and 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?

The description fully covers what the tool does, what it returns, and mode-dependent behavior. No output schema exists, but the description is sufficient.

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

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

Zero parameters, so schema coverage is 100%. The description doesn't need to explain parameters; baseline 4 is appropriate.

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

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

The description clearly states the tool reports credential availability, user ID, and token expiry. It distinguishes itself from siblings like clio_authenticate (which initiates auth) and clio_who_am_i (which lacks token details).

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

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

The description explains when to use the tool (check auth status) and clarifies behavioral differences between remote connector (per-user session) and local/static mode (shared account). No explicit exclusions, but context is sufficient.

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

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

The description adds value beyond the annotations by specifying the all-day event behavior (all_day=true, date-only timestamps). Annotations already indicate it's a write (readOnlyHint=false) and non-idempotent, and the description confirms that. This additional context aids correct usage.

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 concise, consisting of two sentences with no extraneous information. It front-loads the core purpose and then adds a critical usage tip, making it efficient and easily scannable.

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 the tool has 9 parameters, no output schema, and minimal annotations, the description is insufficient. It lacks information on return values, error handling, parameter dependencies (e.g., calendar_id defaulting), and other behavioral nuances needed for an AI agent to invoke it confidently.

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

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

With only 33% schema description coverage, the description provides essential guidance for the all_day parameter and related timestamp format for start_at/end_at. However, it fails to explain the remaining six parameters (description, location, calendar_id, matter_id, event_type_id), 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?

The description clearly states 'Creates a calendar entry,' using a specific verb and resource name. This distinguishes it from sibling tools like clio_list_calendar_entries and other create tools for different entities.

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 provides a specific guideline for all-day events (setting all_day=true and using date-only timestamps), which is helpful. However, it does not explicitly state when not to use this tool or compare to alternatives, though the resource name itself makes the intent clear.

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

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

Annotations already indicate readOnlyHint=false, and the description adds no behavioral details beyond stating creation. No mention of authorization, idempotency, or error conditions.

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?

Single sentence, no extra words. Front-loaded with action and resource. Could be slightly more informative without losing conciseness.

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, no description of return value, duplicate handling, or validation. Given 4 parameters and no annotation enrichment, the description is incomplete for safe 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 coverage is 25% (only name has description). The tool description adds no parameter details. For parameters like addresses and phone_numbers, semantics are left to schema alone, which is insufficient.

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

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

The description clearly states the verb 'Creates' and the resource 'company (entity) contact' with examples of entity types (Inc., LLC, Ltd.). This distinguishes it from sibling tools like clio_create_person_contact.

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

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

No guidance on when to use this tool over alternatives like clio_create_person_contact or any prerequisites. The description does not address selection criteria or context.

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

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

Annotations indicate it's a write operation (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds behavioral context by explaining the total calculation and that quantity is usually 1 for flat-fee, which goes beyond what annotations provide. However, it doesn't mention side effects like creation of multiple entries on repeat calls.

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 main action, and every sentence adds value. No unnecessary text.

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

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

With 8 parameters, no output schema, and only basic annotations, the description is incomplete. It lacks explanations for many required and optional fields (e.g., expense_category_id, non_billable) and does not describe return values or behavior for repeated calls.

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

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

Schema description coverage is only 38% (3 of 8 parameters have descriptions). The description adds meaning for quantity (usually 1) and price (per-unit cost), but fails to explain other parameters like matter_id, user_id, expense_category_id, non_billable, and note. This leaves significant gaps for an agent to understand the full input.

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

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

The description clearly states it creates an ExpenseEntry and includes flat-fee line items. It uses a specific verb (creates) and resource (ExpenseEntry), and distinguishes from siblings like clio_create_time_entry by explicitly mentioning the calculation formula (quantity × price vs. rate × hours).

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 explicitly tells when to use this tool versus the time entry tool by stating 'total = quantity × price (not rate × hours)'. This provides clear guidance on usage context.

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

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

The description discloses the flat_rate quirk (the two-step process and ignored billing_method), which is beyond annotations. However, it omits other behavioral details like auth needs, idempotency (annotations false but not elaborated), and side effects.

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

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

The description is very concise (two sentences) with front-loaded purpose. Every word adds value, especially the critical flat-rate detail. No wasted 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?

Given the tool's complexity (11 parameters, creation, no output schema), the description covers the core purpose and one quirk but lacks error handling, return value hints, and differentiation from similar creation tools. It leaves 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 coverage is 64%, and the description adds meaningful detail for flat_rate_amount by explaining the PATCH behavior. For other parameters, it restates schema info or adds nothing new. Overall, adds moderate value beyond the schema.

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

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

The description clearly states it creates a new matter and specifies the required client_id. However, it does not differentiate from the sibling tool clio_open_new_matter, leaving ambiguity about which to use.

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 for creating matters but provides no guidance on when to use this tool versus alternatives like clio_open_new_matter, nor does it specify prerequisites or context.

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

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

Beyond the annotations (non-read-only, non-idempotent), the description adds valuable behavioral context: notes 'appear in Clio's matter timeline and survive indefinitely,' indicating persistence and visibility. No contradictions with annotations.

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

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

The description is two sentences, highly concise, and front-loads the core action. Every word adds value, with no filler or redundancy.

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

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

For a tool with 5 parameters and no output schema, the description covers purpose and usage context but omits return value behavior and details on optional parameters. Adequate but 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?

With 60% schema coverage, the description adds minimal parameter context beyond the schema. It implies that matter_id or contact_id should be used ('on a matter or contact'), but does not clarify if one is required or what happens if both are omitted. The schema already covers subject, detail, and date well.

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

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

The description clearly states it 'Creates a note on a matter or contact,' specifying the resource and action. It distinguishes from sibling tools like clio_create_task or clio_create_calendar_entry by focusing on notes and even provides use-case context: 'memorializing client conversations and AI-generated summaries.'

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 clear when-to-use guidance ('appropriate for memorializing client conversations and AI-generated summaries') but does not explicitly mention when not to use or directly compare with sibling tools.

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

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

Annotations indicate it is not read-only and not idempotent, which is consistent with 'Creates'. However, the description adds no additional behavioral context such as required permissions, duplicate handling, or response structure. For a write operation, this is insufficient.

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 succinct sentence, but it is too brief for a tool with 10 parameters. It sacrifices informative content for brevity.

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 the complexity (10 parameters, no output schema, no parameter descriptions), the description is severely incomplete. It fails to explain what the tool returns, how to handle errors, or provide any usage context beyond the basic action.

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%, meaning most parameters lack descriptions in the schema. The tool description adds no parameter-level information, leaving the agent to infer meanings from names alone. This is a critical 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?

The description clearly states the tool creates a person (individual) contact in Clio, using a specific verb and resource. It distinguishes from the sibling tool 'clio_create_company_contact' by specifying 'person' vs 'company'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, error conditions, or when to prefer 'clio_create_company_contact' or other contact-related tools.

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

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

Annotations already indicate a non-read-only, non-idempotent mutation. Description adds no extra behavioral details beyond confirming creation, missing side effects or permission requirements.

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

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

One short sentence front-loads the action, but for a 7-parameter tool, it may be overly concise at the cost of completeness.

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?

Despite no output schema and low param coverage, the description does not elaborate on return values, exact parameter usage (e.g., due_at format), or behavior constraints, leaving gaps for agent understanding.

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

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

With only 29% schema coverage, the description minimally clarifies matter_id and assignee_id but fails to explain other parameters like task_type_id, description, or priority beyond what's 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?

The description clearly states the action ('Creates') and resource ('a task'), with optional scoping to matter and/or assignee, distinguishing it from read, update, and list sibling 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?

Provides context for optional parameters (matter_id, assignee_id) but lacks explicit when-not-to-use or alternative tools like clio_create_note or clio_create_calendar_entry.

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

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

Annotations indicate read-write, non-idempotent. Describes the total calculation formula, which adds value. However, lacks disclosure of side effects, required permissions, or return behavior (e.g., what object is returned on success).

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-loading purpose and key formula. No wasted words.

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

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

Given 8 parameters and no output schema, description covers core logic but does not explain return values, error conditions, or mention the activity_description_id parameter. Adequate but not comprehensive.

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?

Adds meaning beyond schema by explaining the relationship between quantity_in_hours and rate via total formula. Also clarifies billable vs non-billable. Schema coverage is 63%, and description compensates moderately.

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?

Clearly states 'Logs billable or non-billable time on a matter' which is a specific verb-resource combination. Distinguished from siblings like create_expense_entry, create_calendar_entry by focusing on time entry.

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

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

No guidance on when to use this tool versus alternatives (e.g., create_expense_entry for expenses, create_calendar_entry for calendar events). Does not provide when-not or alternative tool references.

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

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

Annotations already mark destructiveHint. Description adds value by disclosing the environment variable gate and specific conflict errors, which are beyond annotations.

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

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

Three short sentences, front-loaded with purpose, then conditions, then errors. No wasted words.

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

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

For a simple delete tool with one param and no output schema, the description covers prerequisites, error scenarios, and operation. No 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 has one parameter (contact_id) with no description. The tool description does not explain what contact_id is or how to obtain it, failing to compensate for the 0% schema coverage.

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

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

The description clearly states it deletes a contact, matching the tool name and distinguishing it from other contact tools like update_contact.

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 includes a prerequisite (environment variable requirement) and error conditions (409, 422), which guide when not to use. However, it does not explicitly contrast with alternatives like soft-delete via update.

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?

Discloses soft-delete behavior, which aligns with destructiveHint=true. The idempotentHint is supported by describing that a second delete attempt returns 404. The description adds context about dependency checks (422) beyond what annotations provide.

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 succinct sentences: action, prerequisite, return statuses. No unnecessary information, every sentence adds 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?

Given the simple parameter set and good annotations, the description covers success, failure, and dependencies. It lacks explanation of what 'soft-delete' implies (e.g., reversibility), but overall it's sufficient 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 0%, but the single integer parameter 'matter_id' is self-explanatory. Description does not add extra semantics beyond the schema, so baseline score is appropriate for a simple parameter.

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?

Description clearly states 'Soft-deletes a matter' with a specific verb and resource. It distinguishes from sibling tools like clio_create_matter, clio_update_matter, and clio_get_matter by focusing on deletion.

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?

Description notes that the tool is disabled unless CLIO_ALLOW_DESTRUCTIVE=true, providing a clear prerequisite. It also mentions error codes for already deleted (404) and dependencies (422). However, it does not explicitly state when to use alternatives or when not to use this tool.

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

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

The description adds behavioral context beyond annotations by noting that the default response is only 'id + etag' and that specific fields must be requested. This supplements the readOnlyHint and idempotentHint annotations without contradiction.

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 concise with two sentences. The first sentence states the purpose, and the second adds a crucial usage requirement. No unnecessary 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 simple read-only tool with two parameters and no output schema, the description covers the essential behavior and a critical constraint (field requirement). It is largely complete, though it could optionally detail the format of the 'fields' parameter.

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

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

With schema description coverage at 0%, the description provides minimal additional meaning. It mentions that specific fields must be requested, which hints at the importance of the 'fields' parameter, but does not explain its format or the 'activity_id' parameter beyond what the schema already shows.

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

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

The description clearly states 'Returns a single activity', specifying the verb and resource. It distinguishes itself from sibling tools like 'clio_list_activities' which returns multiple activities.

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 includes an important usage requirement: 'You MUST request specific fields', which guides the agent on how to use the tool effectively. However, it does not explicitly state when to use this tool versus alternatives, such as when a single activity versus a list is needed.

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

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

Annotations already declare the tool as read-only and idempotent. The description does not contradict these and adds basic safety context. No extra behavioral details, but the bar is lowered due to annotations.

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

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

The description is a single, compact sentence with no wasted words. It conveys the essential information efficiently.

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

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

With only one required parameter and no output schema, the description is mostly adequate. However, it could mention what fields are returned or if the bill is fully expanded.

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 only says 'by id' without clarifying the format or constraints of the bill_id parameter. This is insufficient for an agent to construct the parameter correctly.

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

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

The description clearly states the action ('Returns') and the resource ('a single bill') with the required parameter ('by id'). It distinguishes from sibling list tools like clio_list_bills.

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

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

No explicit guidance on when to use this tool versus alternatives. Context signals suggest siblings like clio_list_bills and clio_get_billing_summary, but no when-to-use or when-not-to-use information.

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?

Description adds context beyond readOnlyHint and idempotentHint annotations by detailing the aggregated fields returned. No contradictions; behavioral traits are clear.

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?

Single sentence that front-loads the purpose and lists specific outputs. No superfluous information; every word 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 read-only tool with one parameter and no output schema, the description fully explains what the tool returns. No gaps remain.

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%, but the single parameter 'matter_id' (integer, required) is self-explanatory given the tool name. Description does not add extra meaning but the parameter is simple enough to not require further elaboration.

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?

Description uses specific verb 'aggregates totals' and lists exact return fields: total billed, total paid, outstanding balance, date of most-recently-issued bill. Clearly distinguishes from sibling tools like clio_get_bill (individual bill) and clio_list_bills (listing bills).

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

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

Implies usage for obtaining a financial summary of a matter, but no explicit guidance on when to use vs alternatives or when not to use. Sibling tools list is extensive but no differentiation mentioned.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's mention of 'Returns full detail' aligns but adds no new behavioral context beyond confirming the return type. No mention of performance, rate limits, or other 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?

The description is a single sentence of 15 words, front-loading the key purpose and included data. No redundant phrases.

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 retrieve tool with no output schema, the description provides core information about what is returned. However, it could mention additional details like the full response structure (e.g., custom fields) or error conditions. Still, it is fairly complete given the tool's simplicity.

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%, meaning the parameters have no descriptions. The tool description does not explain the contact_id (implied but not explicit) or the fields parameter (its purpose or valid values). The description fails to compensate for the lack of parameter documentation.

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

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

The description clearly states that the tool returns full detail for a contact, specifying included data (emails, phone numbers, addresses). It distinguishes from sibling tools like search (returns list) and update (modifies). The verb 'Returns' and resource 'full detail for a contact' are specific.

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 for retrieving full details of a single contact, but does not explicitly state when to use this tool over alternatives such as clio_search_contacts for searches or clio_get_matter for matter-specific contacts. No exclusionary guidance is provided.

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

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

Annotations provide readOnlyHint and idempotentHint, so the description adds no extra behavioral context. It doesn't disclose error handling or return value details, but the annotations cover the safety profile adequately.

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

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

Extremely concise (3 words). For a simple get tool, this is efficient and front-loaded. Could add slight detail without bloat, but it's not wasteful.

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

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

Missing details about what document metadata includes, how to handle errors, or any return format. Despite good annotations, the description doesn't fully inform the agent about the tool's 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 0%, and the description does not explain the 'document_id' parameter. The description adds no meaning beyond what the schema provides; for a single required param, it should at least mention it.

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

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

Clearly states 'Returns document metadata' with a specific verb and resource. Distinguishes from siblings like clio_get_document_download_url (download URL) and clio_list_documents (list).

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

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

No guidance on when to use this tool vs alternatives such as clio_get_document_download_url or clio_list_documents. No context on prerequisites or conditions.

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

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

Annotations already indicate readOnly and idempotent. The description adds that it returns a redirect target (not the bytes), the URL is short-lived, and bytes are not proxied. This goes beyond annotations, though it could mention TTL or access scope.

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 no redundancy. Each sentence adds value: first explains the endpoint and return type, second clarifies what is not done. Front-loaded with action verb 'Resolves'.

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 tool with one parameter, annotations, and no output schema, the description covers the core behavior (what is returned, what is not proxied) sufficiently. No major gaps for an agent to misuse the tool.

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

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

Schema coverage is 0% and the description does not explain the parameter 'document_id' beyond hinting at its role in the URL path. It does not clarify expected format, required permissions, or that it is the Clio document ID. Minimal compensation for missing 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?

The description clearly states it resolves a specific endpoint ('GET /documents/{id}/download.json') and returns a redirect target (short-lived signed URL). This distinguishes it from sibling tools like clio_get_document, which likely returns metadata, and other generic 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 description implies usage for obtaining a download URL but does not explicitly state when to use this over alternatives like clio_api_request or clio_get_document. No exclusions or context about prerequisites (e.g., authentication, document access) are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds little behavioral context beyond stating 'full detail'. It does not contradict annotations; no annotation contradiction.

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 sentence of 8 words, no filler, and front-loads the key action and resource. Every word 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?

Given the tool's simplicity (2 params, no output schema, clear annotations), the description adequately conveys the purpose. Could explicitly mention that it returns a full matter object, but not essential for a get-by-id 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 100% (both parameters have descriptions). The description adds minimal value beyond the schema ('by id' reiterates the required parameter). Baseline 3 is appropriate.

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

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

The description 'Returns full detail for a single matter by id' uses a specific verb ('returns') and resource ('single matter') with a clear identifier ('by id'), distinguishing it from sibling tools like clio_list_matters (list multiple) and clio_update_matter (update).

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 when you have a specific matter ID, but does not explicitly state when to use this tool over alternatives like clio_list_matters or clio_search_contacts. No exclusions or when-not-to-use guidance is provided.

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?

Description adds no behavioral information beyond annotations (readOnlyHint, idempotentHint). It does not contradict annotations but provides no extra insight into side effects or 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?

Single sentence, directly to the point with no superfluous words. Perfectly concise.

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?

Simple tool with annotations covering safety and idempotency. Description is adequate for a single-resource retrieval, though could mention error cases or response structure. Minor gap.

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

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

Schema has 1 parameter (task_id) with 0% description coverage. Description clarifies it is the identifier but adds no format or constraints, which is minimal but acceptable for a straightforward parameter.

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?

Description clearly states verb 'Returns', resource 'task', and criteria 'by id'. Distinguishes from sibling 'clio_list_tasks' which lists multiple tasks.

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

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

Usage is implicitly clear given sibling tools; explicitly states it returns a single task by id. No explicit alternatives but context suffices for a simple function.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds no behavioral context beyond restating the function; minimal additional value.

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 concise sentence with no wasted words, front-loaded with the key action and resource.

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 get-by-id tool with annotations, the description is minimally adequate but lacks details on return fields or edge cases, which would be helpful without an output schema.

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

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

There is only one parameter (user_id) with 0% schema description coverage, and the description does not explain its usage, format, or semantics, requiring the agent to infer from the schema alone.

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

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

The description clearly states the verb 'Returns' and the resource 'a single user by id', distinguishing it from sibling tools like clio_list_users which return multiple users.

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 use when needing a specific user but does not explicitly state when to use this tool over alternatives or exclude other tools, providing only implicit guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that default fields avoid bare ID+etag response, warns about matter_id misuse. Does not cover pagination, but adds non-trivial behavior beyond annotations.

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

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

Two focused sentences: first states purpose, second explains a key behavior. No wasted words; information is front-loaded 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?

No output schema, and description does not explain return format, pagination, or default fields beyond mentioning 'useful field set.' For a list endpoint with many parameters, more detail would improve completeness.

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

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

Schema coverage is 50%, but description only mentions filters generically without detailing parameter syntax or semantics beyond what schema provides. Could compensate by explaining fields parameter or date formats, but does not.

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?

Clearly describes the tool as listing time entries and expenses, specifies filtering options by matter, user, date range, or type, and distinguishes from sibling tools like clio_get_activity or create 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?

States when to use default field set, and filtering conditions are clear. Lacks explicit guidance on when not to use or alternatives, but context from sibling names implies appropriate use.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds no further behavioral context (e.g., pagination, rate limits). Does not contradict annotations.

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

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

Single concise sentence effectively communicates core functionality without 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?

Describes main filters but omits pagination parameters and return value expectations. No output schema, so more detail on response could be helpful.

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% with descriptions for issued_since, limit, page_size. Description groups four filter parameters but doesn't add details beyond schema for those with descriptions or cover limit/page_size.

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?

Description clearly states the verb 'Lists' and resource 'bills' with specific filter options (matter, client, state, issued-date). Distinguishes from sibling clio_get_bill for single bill retrieval.

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

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

No guidance on when to use this tool vs alternatives like clio_get_bill. Does not mention when not to use or provide context for selection among siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. The description adds date format context, but beyond that, no behavioral traits (e.g., pagination, return format) are disclosed. Adequate but not rich.

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

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

The description is a single sentence of 9 words, efficiently stating the purpose and a key format rule. No wasted 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?

The description is minimal for a tool with 6 parameters and no output schema. Missing information about pagination, return value structure, and behavior beyond date range. Relies heavily on schema annotations.

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 67% (4 of 6 parameters described). The description adds 'ISO dates (YYYY-MM-DD)' which is already covered by schema descriptions for 'from' and 'to'. It does not compensate for undocumented parameters (calendar_id, matter_id). Marginal addition.

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 'Lists calendar entries within a date range' uses a specific verb and resource, clearly distinguishing from siblings like clio_list_calendars (which lists calendars) and clio_create_calendar_entry.

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

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

The description provides a basic guideline on date format ('Use ISO dates (YYYY-MM-DD)'), but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage is implied.

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

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

Annotations already declare readOnlyHint and idempotentHint, indicating safe repeated reads. The description adds no additional behavioral context beyond stating it lists calendars.

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, clear sentence with no unnecessary words, perfectly concise.

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 the lack of output schema and pagination details, the description is adequate but does not explain return format or how pagination works with limit/page_size.

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% – both limit and page_size are already described in the schema. The tool description does not add further meaning about 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?

The description uses a specific verb 'Lists' and resource 'calendars available to the current user', clearly distinguishing it from sibling tools like clio_list_calendar_entries (which lists entries within a calendar).

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 guidance on when to use this tool versus alternatives. While the name and description are self-explanatory, it does not mention context or exclude other list tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it is safe. The description correctly identifies the action but adds no further behavioral context (e.g., pagination, ordering, or that matter_id/parent_id may be needed). No contradiction with annotations.

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

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

The description is very concise at 8 words, front-loading the core function. While it could benefit from slight expansion (e.g., mentioning pagination), every word is earned and there is no redundancy.

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

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

With no output schema, the description should hint at what the list contains (document objects). It covers the basic context but omits that query and pagination are supported, relying on the schema. Adequate for a simple list tool but 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 80%, with descriptions for most parameters. The tool description adds no parameter-level information beyond what the schema provides. Baseline of 3 is appropriate as 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?

The description clearly states it lists documents within a matter or folder. The verb 'lists' and resource 'documents' are specific, and the scope ('in a matter or folder') distinguishes it from tools like clio_get_document (single) and clio_list_folders, though not explicitly.

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

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

No guidance on when to use this tool versus alternatives such as clio_list_folders for folders or clio_get_document for a single document. The description does not mention prerequisites or filtering options beyond the schema.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining the parent-child behavioral nuance. It does not contradict annotations.

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

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

The description is a single, efficient sentence with no wasted words. It conveys the essential information concisely.

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 no output schema and 50% schema coverage, the description covers the core behavior but omits details about matter_id usage. It is sufficient for a simple list operation but could be more 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 50% (limit and page_size described). The description adds meaning for parent_id (optionality and effect) but does not mention matter_id. Baseline at 3 because coverage is not low but 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?

The description clearly states that it lists folders under a parent or top-level if no parent_id given. It uses a specific verb ('Lists') and resource ('folders'), and distinguishes itself from sibling tools like clio_list_documents or clio_list_calendars.

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 provides clear context on when to use this tool: when listing folders, with behavior dependent on parent_id. However, it does not explicitly mention when not to use it or suggest alternatives, though among siblings, no other folder-listing tool exists.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that it returns the client and related parties, but does not mention pagination behavior or default limits.

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

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

A single, front-loaded sentence with no extraneous words. Every word adds 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 simple list tool with 3 parameters and no output schema, the description is fairly complete, stating what is returned. It could mention pagination or lack of filtering, but overall adequate.

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 has 67% description coverage (limit and page_size described). The description provides no additional parameter semantics, leaving matter_id undocumented. With coverage below 80%, description should compensate but does not.

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

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

The description clearly states the tool returns related contacts for a given matter, specifying it includes the client and related parties. This distinguishes it from sibling tools like clio_search_contacts or clio_list_users.

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 implicitly suggests using this tool when needing contacts associated with a specific matter, but it does not explicitly state when not to use it or compare it with alternatives like clio_search_contacts.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: case-sensitive enums, pagination caps, default fields. No contradictions.

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: first states core purpose, second provides actionable parameter guidance. No wasted words, front-loaded with key intent.

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 9 parameters, high schema coverage, no output schema, and annotations, the description covers filtering, pagination, and case-sensitivity. It could mention output is a list, but implied. Complete enough for a read-only list tool.

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

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

Schema coverage is high (78%). The description explains the purpose of key parameters (query, client_id, status) and mentions case-sensitivity, adding value beyond schema. Some parameters like practice_area_id are not explained.

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

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

The description uses a specific verb-resource pair ('Lists matters') and distinguishes from siblings like clio_get_matter. It lists optional filtering parameters, clearly indicating the scope.

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 provides explicit guidance on when to use certain parameters (query, client_id, status) but does not contrast with sibling tools like clio_get_matter or clio_search_contacts. It implies usage for listing matters with filters.

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

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

Annotations already indicate readOnlyHint: true and idempotentHint: true, so the description doesn't need to repeat safety. However, it adds no further behavioral context (e.g., pagination details, behavior when both matter_id and contact_id are provided). With annotations covering safety, a 3 is appropriate.

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

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

Single sentence with no waste. Front-loaded action and scope. Every word 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?

Given the tool's simplicity (list notes with read-only and idempotent annotations, no output schema), the description provides the minimum. It lacks details on ordering, default behavior, or error conditions when no parameters are provided. Could be more complete but meets basic needs.

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?

Input schema includes 4 parameters (matter_id, contact_id, limit, page_size) with 50% description coverage (limit and page_size have descriptions). The description does not add meaning beyond the schema; it does not explain how to use the parameters together or provide examples. Baseline 3 for adequate compensation.

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?

Description explicitly states 'Lists notes attached to a matter or contact,' clearly identifying the action and scope. It distinguishes from sibling tools like clio_create_note (create) and other list tools by specifying the resource (notes) and filtering context.

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 guidance on when to use this tool versus alternatives (e.g., clio_search_contacts for broader search). Usage is implied (for listing notes on a matter or contact) but not clarified with when-not scenarios or recommended 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?

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds no further behavioral details (e.g., pagination behavior, ordering, or caching), but it does not contradict the annotations.

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

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

A single, concise sentence that efficiently communicates the tool's function with no wasted words. It is front-loaded 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 simple list tool with no output schema and well-documented parameters, the description provides the minimum viable information. However, it lacks details about the return format or potential filtering, which would be helpful for 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?

Input schema coverage is 100%, so both limit and page_size are already well-documented. The description adds no extra semantics or usage context beyond what the schema provides, resulting in a baseline score.

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

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

The description clearly states the verb 'Lists' and the resource 'practice areas', making the tool's purpose immediately obvious. It distinguishes itself from sibling tools by naming a specific entity, though it could be more precise about what 'configured on the firm' entails.

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

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

No guidance is provided on when to use this tool versus alternatives like clio_list_matters or clio_search_contacts. There is no mention of prerequisites, optimal conditions, or exclusions, leaving the agent without context for selection.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the description does not need to repeat safety information. However, the description adds no additional behavioral context beyond the filter list, missing details like pagination behavior (covered in schema but not enhanced), default ordering, or response format.

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 sentence that front-loads the verb and resource, lists filters efficiently, and contains no superfluous 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?

Given 8 optional parameters and no output schema, the description covers the filtering intent but lacks information about default behavior (e.g., what happens when no filters are applied), pagination details, and return format. It is minimally adequate but leaves 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?

With 50% schema description coverage, the description compensates by explicitly listing the filter parameters (matter, status, priority, due date range, assignee), which maps to 6 of 8 parameters. It does not mention limit and page_size, which are documented in the schema, so overall it adds meaningful semantic grouping but misses two 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?

Description clearly states the verb 'Lists' and the resource 'tasks', and specifies optional filters (matter, status, priority, due date range, assignee). This distinguishes it from sibling tools like clio_get_task (single task retrieval) and clio_create_task (creation).

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

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

Usage context is implied via the list of optional filters, but there is no explicit guidance on when to use this tool versus alternatives (e.g., clio_get_task for a specific task). The description does not state when not to use it or mention any prerequisites.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not restate them. However, the description adds no extra behavioral context (e.g., pagination behavior, rate limits, or that it returns all users by default). It is adequate but not improved beyond annotations.

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

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

The description is extremely concise: 'Lists firm users.' This single sentence is necessary and sufficient for a simple list tool, with no wasted words. It is front-loaded and 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?

Given the tool has 3 optional parameters and no output schema, the description is too sparse. It does not explain how parameters affect the listing (e.g., filtering by enabled), does not mention pagination, and does not indicate return structure. The schema partially compensates, but the description lacks 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 67%, with 'limit' and 'page_size' explained in the schema. The description does not mention any parameters, especially 'enabled', which has no schema description. While the parameter names are somewhat self-explanatory, the description adds no value beyond the schema.

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

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

The description clearly states the verb 'lists' and resource 'firm users', making the purpose straightforward. However, it does not differentiate from sibling tools like clio_get_user or other list tools, though the resource name is distinctive enough.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., clio_get_user for a single user, or other list tools). There is no mention of prerequisites, context, or exclusions.

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

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

Annotations indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true). Description adds context: it only deletes the local token file, not affecting remote sessions or revoking the token. No contradictions with annotations.

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

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

Three sentences, each serving a purpose: first states core action and scope, second clarifies a critical limitation, third addresses additional context for remote connector. Front-loaded, no fluff.

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 no parameters, no output schema, and annotations, the description fully covers what the tool does, its limitations, and when to use alternatives. Complete for a simple logout 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?

Tool has 0 parameters, so schema coverage is 100%. With no parameters to document, the description need not add parameter details. Baseline score 4 for zero-parameter tools.

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 title 'Clear stored Clio credentials' and description 'Deletes the encrypted token file for the shared account' clearly state the specific action and resource. Among siblings like clio_authenticate and clio_auth_status, it unambiguously serves as the logout counterpart.

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

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

Explicitly states when to use (to clear local credentials) and when not: it does not revoke the token on Clio's side and does not clear remote per-user sessions. Provides alternatives: use Clio's Developer Applications screen for full revocation, or disconnect the connector in Claude for remote sessions.

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

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

Annotations provide readOnly=false and idempotent=false. The description adds that it creates multiple entities and returns a summary, which is valuable behavioral context beyond annotations.

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

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

Two sentences, zero waste. Efficiently communicates the core purpose and optional features.

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 the complexity (15 parameters, no output schema), the description is too brief. It omits parameter semantics, prerequisites, and error conditions, leaving an agent underinformed for reliable 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 coverage is only 33% (5 of 15 params described). The description does not compensate by detailing parameters; it merely mentions optional note and task. Most parameters lack explanation.

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

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

The description clearly states the end-to-end intake workflow: creates/uses client, opens matter, optionally adds note and task. It distinguishes this composite tool from simpler siblings like clio_create_matter.

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 implicitly indicates this is for full intake, handling both new and existing clients. However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds no extra behavioral context beyond stating the search functionality; it does not disclose pagination behavior, rate limits, or permissions. With annotations present, a score of 3 is appropriate.

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

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

The description is two sentences, front-loading the purpose and efficiently directing to the alternative. Every word earns its place with no redundancy.

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

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

For a search tool with no output schema, the description does not explain the return format (e.g., list of contacts with IDs, pagination handling). While parameters cover pagination, the lack of output context leaves a gap. Adequate but not complete.

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

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

Schema description coverage is 75%, and the description does not add meaning beyond what the schema provides. The description mentions matching fields, but those are already covered in the schema's query parameter description. Baseline of 3 is suitable.

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

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

The description clearly states the verb 'search' and the resource 'contacts', specifying matching fields (name, email, company) and explicitly directs to clio_get_contact for full detail, distinguishing it from its sibling tool.

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

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

The description provides clear context for when to use this tool (free-text search) and explicitly names an alternative (clio_get_contact for full detail), but does not include exclusions or when-not-to-use scenarios.

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

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

Annotations already indicate a mutation (readOnlyHint=false). The description adds that it's a PATCH, which is a standard HTTP verb for partial updates. However, it does not disclose potential side effects, authorization needs, or response behavior. For a mutation tool, this is minimal but not contradictory.

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

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

The description is two short sentences, front-loaded with the action ('PATCH a contact'), and contains no fluff. Every word 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?

The tool has 5 parameters, no output schema, and minimal annotations. The description does not explain return values, required contact_id, or the distinction between company and person contact fields. It is insufficient for an agent to fully understand behavior without additional information.

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?

Parameter schema coverage is only 20% (one parameter described). The description reinforces the PATCH semantics ('pass only fields to change') but adds no per-parameter meaning. The baseline is 3 given low coverage, and the description does not compensate for missing parameter 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?

The description clearly states it updates a contact via PATCH. It distinguishes from create and delete siblings by using 'update' and the PATCH verb, making the purpose unmistakable.

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 'Pass only the fields you want to change,' which implies partial updates. It provides clear context but lacks explicit when-not-to-use or alternative tool references. Given siblings include create and delete, the usage is 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?

Annotations already indicate the tool is not read-only and not idempotent. The description adds that it uses PATCH semantics, which conveys idempotency implications. However, it does not disclose other behaviors such as return values, side effects, or rate limits, leaving a gap beyond what annotations provide.

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 very short and front-loaded with the action 'PATCH a matter', making it efficient. However, it could be more structured by including key parameter guidance without becoming verbose. It is appropriately sized but misses some 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 tool with 9 parameters (1 required) and no output schema, the description is insufficient. It does not explain the update behavior, return type, error handling, or any constraints. The context signals indicate high complexity, yet the description adds minimal 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 0%, so the description must compensate for missing parameter information. The description only advises to pass changed fields but does not explain any parameter meanings, formats, or constraints (e.g., status enum values, date format for open_date). This fails to add significant value over the raw 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?

Clearly states the verb (PATCH) and resource (matter). Distinguishes from sibling tools like clio_create_matter (create) and clio_get_matter (read) by specifying it is an update operation. The phrase 'Pass only the fields you want to change' indicates a partial update pattern.

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 for updating existing matters and specifies that only changed fields need to be passed. However, it does not explicitly state when to use this tool versus alternatives like clio_open_new_matter or clio_delete_matter, nor does it mention prerequisites or permissions.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, which align with the PATCH operation. The description adds the common use case but no further behavioral details (e.g., error behavior, partial update semantics).

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 very short (two sentences) and front-loads the action and a practical example. It is concise without wasted words, though it could be slightly more informative.

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 the 7 parameters, 2 enums, and no output schema, the description lacks completeness. It does not cover most parameters, response format, or potential errors, leaving significant gaps 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?

With 0% schema coverage, the description should explain parameters. It only mentions the 'status' parameter and its 'Complete' value, ignoring the other 6 parameters (name, description, priority, due_at, assignee_id) and their semantics.

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

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

The description states 'PATCH a task' which clearly indicates the action and resource. It adds a common use case 'mark complete by setting status=Complete', but does not explicitly differentiate from sibling tools like clio_create_task or clio_get_task, though it is implied.

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 provides a concrete example usage (marking a task complete) but does not specify when not to use this tool or mention alternatives such as creating or deleting tasks.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description primarily confirms it's a GET call. It adds value by specifying the exact endpoint and the return of user data, with no contradictions.

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 front-loads the API call and purpose, with no extraneous words. Excellent conciseness.

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 authentication check with one optional parameter and no output schema, the description is sufficient. Minor omission: no mention of error responses, but not critical for this tool's simplicity.

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 only parameter (fields) is fully documented in the schema with defaults. The description adds no new information about parameters, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly identifies the tool's purpose: calling the GET /users/who_am_i endpoint to confirm credentials and return the current user. It distinguishes itself from siblings like clio_get_user and clio_list_users by focusing on the authenticated user.

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 use after authentication to verify credentials, providing clear context. However, it lacks explicit when-not-to-use or comparisons with sibling tools, though the intended use case is obvious.

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