Lawcus MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, lowering the bar. The description adds real value beyond them: the 'WRITE:' prefix, the side-effect disclaimer ('does not send anything to the contact'), and the non-obvious conditional field requirements that differ from the schema's single required 'type'.

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

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

Three short sentences with the operation mode front-loaded ('WRITE:'), followed by side-effect clarification and then the validation rules. No filler and no repetition of schema-only details.

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

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

For a 14-parameter mutation with no output schema, the description covers the critical decision points: what it creates, that it has no outreach side effect, and the type-dependent required fields. It omits what the tool returns (e.g., the new contact's ID) and how duplicate conflicts are surfaced, which an agent would still need to discover empirically.

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 29% across 14 parameters, so the description must compensate. It correctly fills the most consequential gap by explaining the conditional requirements per type ('Person needs first_name and last_name; Company needs name'), which the schema only hints at via scattered per-field notes. Remaining address/contact fields are left undocumented but are largely self-explanatory.

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

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

States a specific verb and resource ('create a new contact in Lawcus') plus a scope qualifier ('a person or a company'), which immediately separates it from lawcus_get_contact and lawcus_list_contacts. An agent knows exactly what this tool produces without opening the schema.

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

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

Explicitly routes the agent to lawcus_list_contacts first to avoid duplicates, which is a concrete precondition rather than vague advice. It does not state when not to use it (e.g., updating an existing contact), so it stops short of full when/when-not coverage.

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

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

Annotations already declare that this is a non-read-only, non-idempotent, open-world write operation. The description adds useful behavioral context beyond annotations by disclosing that Lawcus may email or SMS assignees if reminders are set, and clarifies that this tool itself does not set reminders.

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 tight sentences, front-loaded with the write designation and core action. Every sentence contributes either purpose, optional relations, or important side-effect information, with no waste.

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

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

For a create mutation with annotations covering safety traits, the description supplies the critical side-effect caveat about notifications and clarifies optional associations. It still leaves some parameter semantics and return behavior unstated, but the schema and annotations carry the remaining structural burden.

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 60%, and the description adds meaning for matter_id and assignee_uuids by explaining that the task can optionally be attached to a matter and assigned to team members. However, it does not add information about the required name, due_date, or description parameters, leaving the partial schema coverage as the primary source.

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 and resource ('create a task in Lawcus') and marks it as a write operation up front. It also distinguishes this from the sibling list/get tools by clearly stating the creation scope, including optional matter attachment and assignee assignment.

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

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

It gives clear contextual guidance for when to use the tool: creating a task, optionally tied to a matter and assigned to team members. It does not explicitly state when not to use it or name any alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the returned sub-resources (addresses, phones, emails, custom fields) in the absence of an output schema, but says nothing about missing-contact behavior or permissions.

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

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

A single compact sentence that front-loads the namespace, the operation and the identifier, then lists returns. No filler.

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

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

For a one-parameter read tool where annotations carry the safety profile and no output schema exists, the description adequately covers both what is fetched and what comes back. Only error/not-found behavior is unmentioned, which is minor.

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?

Only one parameter and schema coverage is 0%, so the description has to compensate. Saying "by UUID" conveys the identifier's semantic origin, but the schema's regex pattern already fixes the format, so little is added beyond that.

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

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

States a specific verb (get), resource (contact), and scope (one, by UUID), plus the payload shape (addresses, phones, emails, custom fields). "One contact by UUID" implicitly separates it from lawcus_list_contacts and lawcus_search, though no sibling is named.

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

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

Usage is only implied: needing a single contact identified by UUID. There is no explicit statement of when to prefer this over lawcus_list_contacts or lawcus_search, nor what to do when the UUID is unknown.

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 openWorldHint=true, so the safety profile is covered. The description adds which fields are returned, which is useful given there is no output schema, but it does not mention authentication requirements, rate limits, or what happens if no firm is associated.

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 lists the resource and its returned fields without filler. The 'Lawcus:' prefix is slightly redundant but does not harm readability.

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

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

For a zero-parameter read tool with no output schema, the description supplies the missing return-value summary by listing the fields. The main gap is that it does not clarify how this differs from related identity/team tools, which could cause an agent to hesitate between siblings.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument call that returns the current firm context.

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 resource retrieved (the firm/team details) and enumerates the fields returned (name, address, currency, locale, phone numbers). It does not differentiate from similar siblings like lawcus_get_me or lawcus_list_team_members, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus lawcus_get_me or lawcus_list_team_members, nor any stated prerequisites. The usage is only implied by the tool name and the word 'firm'.

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 openWorldHint=true, so the safety profile is covered, but the description adds nothing beyond that — no mention of not-found behavior, whether the lead is fetched live from the external Lawcus instance, or permission scoping.

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

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

Four words are certainly front-loaded and waste nothing, but the terseness crosses into under-specification rather than efficiency; a single clause on return content or failure mode would cost little and add much.

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

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

For a single-record fetch with no output schema, the description gives no indication of what a lead record contains or how the caller should handle a miss. Annotations cover the read-only safety question, but the retrieval contract itself is left entirely implicit.

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

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

Schema coverage is 0%, so the description must carry the load; "by UUID" does identify the single parameter's meaning and confirms it is a lead identifier. However it adds no detail beyond the regex already visible in the schema — no note on where a lead_uuid is obtained.

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?

"One lead by UUID" implies a single-record retrieval and distinguishes it from the sibling lawcus_list_leads by singularity, but it never uses an explicit verb (get/fetch/retrieve), so the operation type must be inferred from the tool name rather than the description.

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

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

There is no statement of when to use this versus lawcus_list_leads or lawcus_search, no prerequisites, and no note about what happens when the UUID is unknown. The agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful value by disclosing the shape of the returned record (client, stage, billing settings, balances, custom fields), but says nothing about behavior on a missing/invalid UUID or about the freshness of live external data implied by openWorldHint.

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

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

A single sentence with zero filler; the unique-key qualifier ('one matter by UUID') is front-loaded and the payload listing follows. Nothing could be cut without losing information.

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

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

For a one-parameter read-only fetch with no output schema, the description carries the important part: what the returned record contains. Annotations cover safety, and the remaining gap (error behavior for unknown UUIDs) is minor for this tool class.

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

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

Schema description coverage is 0% for the single required parameter, so the description must compensate; 'by UUID' does clarify that matter_uuid is a UUID identifier rather than a numeric id or slug. It does not state where to obtain that UUID, which is the one piece of semantic guidance missing.

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

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

The noun phrase 'one matter by UUID' plus the enumerated payload (client, workflow stage, billing settings, balances, custom fields) makes clear this is a single-matter fetch, implicitly contrasted with lawcus_list_matters. The verb itself is carried only by the name/title, so it is clear but not maximally explicit.

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

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

The 'by UUID' phrasing implies the prerequisite that the agent must already hold a matter identifier (from lawcus_list_matters or lawcus_search), which is the only usage signal. There is no explicit when/when-not statement, no naming of alternatives, and nothing about resolution when the UUID is unknown.

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 openWorldHint=true, so the safety profile is covered. The description adds that it is token-scoped and returns role values such as OWNER/ADMIN/MEMBER, giving the agent useful context about what the response will contain without claiming anything that conflicts with 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 compact sentence that front-loads the resource identity and then the payload fields. The 'Lawcus:' prefix is mildly redundant given the tool namespace, but nothing else is wasted.

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

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

With no output schema, the description carries the burden of describing the return payload and does so by listing the key fields. For a zero-parameter identity lookup this is close to complete; only the exact shape of the role/timezone values is left unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4. The description correctly implies no input is needed.

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

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

The description states the resource precisely — the user the API token belongs to — and enumerates the returned fields (id, uuid, name, timezone, role), which lets an agent distinguish it from sibling reads like lawcus_get_firm or lawcus_list_team_members. The verb is only implied by the 'get me' framing rather than stated.

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

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

Usage is implied: this identifies the caller behind the token, which is the natural fit for 'who am I / what role do I have' questions. However, no explicit when-to-use or when-not guidance is given, and no alternative (e.g. lawcus_list_team_members for other users) is named.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds real behavioral context beyond them: results carry payment details and the call also returns time totals for today/week/month/year, an extra output an agent would not predict. It omits ordering and truncation behavior (the limit schema note is not echoed here).

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

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

Two dense sentences, front-loaded with what is listed, followed by the notable secondary output. The 'Lawcus:' brand prefix is minor noise but nothing else is wasted.

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

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

With 9 optional parameters, no output schema, and no required filters, the description needs to carry the return-shape burden; it names payment details and time totals but says nothing about ordering, default limit, or what happens when no filters are supplied. Adequate to call correctly, but gaps remain for an agent reasoning about results.

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

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

Schema coverage is only 44%, so the description has to compensate, and it largely does by enumerating the filter dimensions (date range, user, practice area, matter, client, invoiced state) that map to the undocumented *_id and is_invoiced parameters. It leaves out 'kind' and 'limit' semantics and does not say how the id filters combine, so it is not fully compensating.

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

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

States a specific verb and resource: lists billable activity covering time entries, expenses and flat fees, with payment details. An agent knows immediately what it returns. It stops short of differentiating from the overlapping siblings lawcus_list_time_entries and lawcus_list_expenses, which also surface subsets of this data.

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

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

Usage is only implied: the phrase 'with payment details' and the cross-kind coverage suggest this is the combined/aggregated view, but the description never says when to pick it over lawcus_list_time_entries or lawcus_list_expenses, nor any prerequisite (e.g. invoiced vs uninvoiced use cases). No exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that results are paged with skip/take and that clients are contacts, but it does not provide additional behavioral context such as return shape, default ordering, or pagination 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 wasted text. The scope clarification and paging behavior are packed efficiently without burying the main action.

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

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

For a read-only list tool with 9 optional parameters and no output schema, the description covers the core purpose and common filters but omits guidance on advanced filter objects and sorting. It is minimally adequate but not complete enough to fully guide complex usage.

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 56%, so the description must compensate and it partially does by naming name, email, type, and update-date filtering plus paging. It leaves advanced 'filters', sort_by, and sort_order unexplained, so parameter meaning is only partially enriched.

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

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

States a specific verb and resource ('list contacts') and clarifies scope by including people, companies, and clients. It does not explicitly distinguish itself from siblings like lawcus_search or lawcus_list_leads, so it stops short of a 5.

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

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

Gives implied usage through filterable fields and paging, which helps an agent know how to narrow results. However, it does not say when to use this tool instead of lawcus_search, lawcus_get_contact, or lawcus_list_leads, so there is no explicit alternative routing.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: the API returns all expenses, filtering happens client-side here, and the reply is truncated at `limit` and announces that truncation — exactly the kind of detail an agent needs to interpret a short result list.

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

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

Two compact sentences that front-load the resource identity and then the filtering/truncation behavior. No filler, and the most decision-relevant fact (filtering is local, not server-side) is stated early.

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

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

For a read-only list tool with no output schema, the definition covers scope, filtering, and truncation signaling adequately. Return record fields are unspecified, but that is a minor gap for a listing endpoint whose sibling list tools behave similarly.

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

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

Schema coverage is 75%, and the one undocumented parameter, `matter_id`, is given meaning by the phrase 'filter here by matter'. The date filters and `limit` are already explained in the schema, so the description modestly but meaningfully extends the structured data.

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

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

The description names the resource precisely ('expenses logged against matters') and states what the call returns, which no sibling tool covers. It is clear but does not explicitly contrast with other list tools, relying on the unique resource to differentiate.

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

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

It indicates when to use the local filters ('filter here by matter and date range') versus the unfiltered API result, which is a useful cue. However, there are no explicit exclusions, prerequisites, or named alternatives beyond the implicit 'no filtering is done server-side' note.

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 openWorldHint=true, so the safety profile is covered. The description adds that results are paged via skip/paginate, which is useful operational context, but is silent on result ordering, total counts, and whether filters combine (e.g. types AND direction).

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

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

Two compact sentences with the resource scope front-loaded and pagination noted second. No filler, though the telegraphic phrasing makes it read more like a schema comment than a description.

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

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

For a read-only list tool with no output schema, the description covers the domain well but leaves the agent guessing about what a record looks like, whether results are newest-first, and how skip interacts with paginate. Adequate as a minimum, incomplete for confident 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 50%: types and paginate are documented in the schema, while skip and direction have no descriptions anywhere. The description's parenthetical '(emails, calls, secure messages)' maps usefully onto the types enum, but skip's offset semantics and direction's INBOUND/OUTBOUND behavior are left entirely unexplained.

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

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

Names a specific resource (logged client interactions) and enumerates the kinds covered (emails, calls, secure messages) plus the entities they attach to (subject, matter, contact). An agent can distinguish it from list_tasks or list_matters, though it never explicitly contrasts with the similarly-scoped lawcus_search.

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 what the tool contains but never states when to choose it over lawcus_search or another list tool, nor any prerequisite or filtering strategy. 'Paged with skip/paginate' is operational, not usage guidance.

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

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

readOnlyHint=true already declares the safe-read profile, and openWorldHint=true signals firm-scoped data. The description adds that results carry contact details and pipeline stage, and that responses are paged, but says nothing about page-size limits, ordering defaults, or total-count behavior beyond the schema.

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

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

Two short sentences, front-loaded with what the tool returns, no filler. The 'Paged with skip/take' clause is mildly redundant with the schema but earns its place as a pagination cue.

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

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

For a 9-parameter listing tool with no output schema, the description omits any mention of the filtering, sorting, and stage/source-id narrowing capabilities, which are the main decision points for an agent. Adequate for a basic list call, incomplete for the surface the schema exposes.

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

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

Schema coverage is 67%, so the schema documents most params (skip/take/filters/stage_id/lead_source_id). The description only echoes pagination via skip/take and adds no meaning for the filter array, sort_by/sort_order, or name_contains; baseline 3 is appropriate given coverage but no extra value.

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

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

States a specific verb and resource ('list leads') and clarifies the domain term with '(prospective matters)', plus what comes back ('client contact details and pipeline stage'). It does not contrast with the closest sibling lawcus_get_lead or lawcus_search, so it falls short of a 5.

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

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

No statement of when to call this vs lawcus_get_lead (single lead), lawcus_search (query across entities), or how filtering should be routed between named params and the 'filters' array. Only an implied read-all-listing usage is conveyed.

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 openWorldHint=true, so the safety profile is covered. The description adds useful context about the kind of values returned and how IDs are consumed, but it does not describe return format, ordering, or any other behavioral detail beyond that.

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

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

Two short sentences with no wasted wording; the resource and its practical use are front-loaded.

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

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

For a simple no-parameter list tool with annotations covering read-only behavior, the description supplies enough context: what is listed, example values, and how the IDs are used. It could mention whether all sources are returned or how they are ordered, but the essentials are present.

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

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

The tool has zero parameters, so the baseline is 4. The empty schema is consistent with the description, and no parameter semantics are needed.

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

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

The description names the specific resource (the firm's lead sources) and gives concrete examples (Website, Referral, Google), making it clear this is not the same as listing leads. It lacks an explicit verb and does not directly name the sibling it contrasts with, so it is clear but not fully sibling-differentiating.

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

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

It implies usage by explaining that resulting IDs go into lead and contact filters, which tells an agent why to call it. However, it gives no explicit when-to-use guidance or alternatives versus related tools such as lawcus_list_leads.

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 openWorldHint, so the safety profile is covered; the description adds real value by disclosing that the reply carries trust/retainer balances and opened/closed counts, and that results are paged with skip/take. It stops short of describing default page size or sort-order behavior, which the schema covers instead.

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

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

Three tight sentences with no filler: what it returns first, filters second, paging and reply metadata last. Every clause carries information an agent can act on.

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

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

With no output schema, the description usefully sketches the return payload (balances, counts) and paging contract, which is enough for a read-only list tool. Only sorting behavior and the interplay of top-level shortcuts with the advanced filters array go unaddressed, and the schema carries those.

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

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

Schema coverage is 75%, so most parameters are already documented, and the description only restates the obvious filter axes. It adds no meaning for sort_by, sort_order, responsible_attorney_id or the advanced filters array beyond what the schema provides, so it sits at the baseline.

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

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

States a specific verb and resource (list matters/cases) plus the notable fields each record carries (status, client, billing type, trust and retainer balances), which distinguishes it from a bare listing. It does not explicitly contrast with lawcus_get_matter or lawcus_search, so sibling differentiation is left implicit.

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

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

The filter dimensions (status, name, number, client, dates) and paging behavior imply when to reach for this tool, but there is no explicit when-not guidance or a named alternative such as lawcus_get_matter for single-record retrieval. Usage is inferable rather than stated.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context by warning that the API returns the whole list and the reply is truncated to `limit`, which is important for interpreting results.

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

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

The description is two compact clauses with zero waste, and the core operation plus filtering scope are front-loaded. The truncation caveat follows logically without padding.

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

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

For a read-only list tool with no output schema and fully described parameters, the description covers purpose, filters, and truncation behavior. It could mention pagination or result shape more explicitly, but the essential calling context is present.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description summarizes the available filters but adds no syntax, defaults, or edge-case behavior beyond what the schema provides; the delegated parameter is not mentioned.

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 gives a specific verb and resource ('list tasks') and scopes it with optional filters. It distinguishes the operation from sibling mutation tools like lawcus_create_task, but does not explicitly contrast with lawcus_search.

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

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

It mentions optional filtering by completion, assignee, matter, or tag, which implies when to use the tool. However, it gives no explicit guidance on when to prefer this over search or other list tools, nor any when-not 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?

readOnlyHint=true and openWorldHint=true already establish that this is a safe external read, so the description needn't restate safety. It contributes the returned field set, which matters because there is no output schema, but says nothing about pagination, ordering, or whether inactive members are included.

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

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

Two tight sentences with the payoff (filter ids) placed after the content description where it belongs. The 'Lawcus:' prefix is minor filler but the rest earns its space.

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

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

For a zero-parameter read with no output schema, the description covers what the tool returns and why it is useful. The only real gap is the absence of any note on result size or whether the list is complete versus paginated.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline applies. The description correctly does not invent inputs that the empty schema would reject.

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

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

The description names the resource ('the people on the firm's team') and enumerates the fields returned (id, uuid, name, role, hourly rate), which clearly separates it from contact/lead list tools. It stops short of a verb-first statement like 'List all firm team members', but the intent is unambiguous.

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

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

The second sentence supplies a concrete use case: team-member ids feed matter, task and report filters. That gives the agent a clear reason to call this tool, though it offers no explicit exclusions or guidance against siblings such as lawcus_get_me.

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 openWorldHint, so safety is covered; the description adds the non-obvious point that filtering happens client-side after the API returns everything, and that the reply signals when results were cut by limit. It omits pagination/offset behavior and whether filtering is inclusive at the boundaries.

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

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

Two compact sentences, with the resource identification first and the filtering/truncation constraint immediately after. Nothing is padded.

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

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

With no output schema and a shallow five-parameter read tool, the description covers the main gotchas: client-side filtering and truncated replies. Only the undocumented user_id parameter keeps it from being fully self-sufficient.

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

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

Schema coverage is 60%; limit and the two date parameters are documented in the schema, but user_id has no description anywhere. The description adds the semantics of matter_id and date range (client-side filtering) but never explains user_id, leaving a genuine 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?

Names the specific resource (time entries) and enumerates what each record carries (hours, rate, total, matter, invoiced status), which is more than the title restated. It does not, however, distinguish itself from the sibling lawcus_report_time_entries, so an agent must guess which of the two to pick for time-related questions.

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 API returns all entries; filter here by matter and date range' gives real context for when this tool is appropriate, and the limit note explains truncation. There is no explicit when-not guidance and no routing to the alternative reporting tool that clearly overlaps.

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 openWorldHint=true, so the safety profile is covered. The description adds a modest amount beyond them: it explains the domain concept (workflows are matter and lead pipelines) and states that ids are returned. It says nothing about ordering, pagination, or whether inactive pipelines are included, but for a simple list read the annotations carry most of the burden.

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

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

It is short, but it is a sentence fragment rather than a front-loaded statement of purpose, and the 'Lawcus:' vendor prefix is pure waste on a tool whose server is already implicit. The remaining words do earn their place by defining 'workflow', but the structure is awkward.

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

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

For a zero-parameter read with no output schema, the description should at minimum say what an agent gets back and how it pairs with the stages tool. It covers the concept and the presence of ids, which is the core, but leaves the natural next step (lawcus_list_workflow_stages) and the returned fields other than id unexplained.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The schema is empty and closed, consistent with the description.

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

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

The description identifies the resource ('the workflows') and usefully glosses it as 'matter and lead pipelines', which an agent could not otherwise infer. But it is a noun-phrase fragment with no verb, and it does not differentiate the tool from the sibling lawcus_list_workflow_stages, so the agent must guess the hierarchy between them.

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

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

There is no when-to-use guidance at all — no indication of when to call this versus lawcus_list_workflow_stages, or that this is the prerequisite lookup for feeding a workflow id into a stages call. The agent is left to infer the relationship from names alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing further, with no mention of ordering, pagination, completeness of the stage list, or what happens with an unknown workflow_id.

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 short and front-loaded, with no filler. The only weakness is that the fragment form omits a verb and reads more like a label than a usable instruction.

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 one-parameter read tool with annotations and full schema coverage, the minimum is arguably met, but there is no hint of what a stage contains or how the list is ordered, and no output schema exists to fill that gap.

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

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

Schema description coverage is 100% and the single workflow_id parameter is fully documented in the schema, including its UUID pattern and the pointer to lawcus_list_workflows. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

The description names the resource (stages) and scopes it to a single workflow, adding the useful synonym 'pipeline'. However, it is a fragment that largely restates the name and title ('List workflow stages') without a verb, and it does not differentiate the tool from the adjacent lawcus_list_workflows beyond the word 'stages'.

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

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

It gives no condition for when to call it versus lawcus_list_workflows, nor any prerequisite such as obtaining workflow_id first; that hint lives only inside the parameter schema, not the description. Usage must be inferred from the name alone.

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

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

Annotations already cover the read-only and open-world profile, and the description adds the non-obvious auth requirement (Admin role) plus the aging/outstanding-balance framing that annotations cannot convey. It stops short of disclosing result shape, pagination, or what happens with an unbounded period.

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

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

A single sentence with the permission gate and the report's content both front-loaded; nothing is redundant or padded.

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

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

For a read-only report with fully documented parameters and no output schema, the definition covers purpose, audience, and access control adequately. It could say more about default period behavior or grouping defaults, but nothing essential to invocation is missing.

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

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

Schema description coverage is 100%, so the seven optional parameters (start/end, group_by, client/matter/user/practice ids) are already documented at the field level. The description adds no filtering or grouping guidance beyond that, making the baseline 3 the correct call.

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

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

States a specific verb+resource: an accounts-receivable report of unpaid invoices aged by bucket, with the clarifying gloss 'who owes the firm what'. It is meaningfully distinct from list_billing_items or report_payments_collected, though it never names those siblings to sharpen the contrast.

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 Admin-role prerequisite is stated, which is real routing information, but nothing tells the agent when to pick this over the nearby lawcus_report_invoice_history or lawcus_report_matter_balance siblings, nor whether the period parameters are required in practice.

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 readOnlyHint=true and openWorldHint=true, the description discloses two substantive behavioral facts: the Admin permission requirement and the default row-filtering rule (zero balances hidden unless display_zero is true). It does not describe return shape or whether start/end are optional filters, but for a read-only report the additions are meaningful.

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

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

A single dense sentence with the permission constraint and the default-filter behavior front-loaded; no filler, and every clause carries information an agent needs.

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 five optional parameters, no output schema, and sparse annotations, the description covers permissions and default filtering adequately. It stops short of indicating what the report rows contain or whether start/end are required to produce meaningful output, which would round it out.

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

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

Schema coverage is 80%, and the description covers the one gap: display_zero has no schema description, and the description explains its effect as an override of the default hiding of zero balances. The date-range and id parameters are left to the schema, which documents them 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?

Names a specific resource (client trust / IOLTA balances) produced by a report, which is clearly distinct from the sibling reports (accounts_receivable, matter_balance, revenue, payments_collected). The verb is nominal ("report") rather than a true action verb, and no sibling is explicitly named as an alternative, keeping it just under a 5.

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

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

It supplies a real precondition — "needs the Admin role" — which is useful and non-obvious. However, it gives no when-to-use guidance relative to the other report tools or the client/matter listing tools, so an agent must infer the selection context.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds a genuinely non-obvious behavioral fact: the Admin role is required. It says nothing about result limits, pagination, or what the summary aggregates, which remain gaps beyond the annotation coverage.

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 tight sentence with the resource statement front-loaded and the role requirement attached. No filler, though the brevity edges toward under-specification rather than pure economy.

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 say more about what the summary contains and how group_by changes the shape, which it does not. Given zero required parameters and a fully documented schema, though, it is close to sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all six parameters (start, end, user_id, group_by, client_id, practice_id) are already documented, including date format and grouping examples. The description adds only the vague phrase 'for a period', which is fully covered by the schema, so baseline 3 applies.

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

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

States a specific verb+resource: a report summarizing issued invoices over a period. The resource (issued invoices) is distinguishable from the sibling reports (accounts receivable, client trust, matter balance, payments collected, revenue, time entries) without naming them explicitly.

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

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

The description implies when to use it (period-based invoice summary) and gives an important prerequisite (Admin role), but never contrasts it against the neighboring report tools or states any exclusions, so the agent must infer selection criteria.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuinely useful non-annotation fact — the Admin role requirement. It stops short of disclosing response shape, aggregation granularity, or how the optional filters interact with the aggregate, which matters for a report tool.

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

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

A single front-loaded sentence that packs the resource, the permission gate, and the mode switch with no filler. It reads as a terse fragment rather than a full sentence, but every clause carries information.

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

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

For a seven-parameter, zero-required report with no output schema, the description is minimally adequate: it says what is summarized and who may call it. It does not say what the report returns, how grouping affects the result, or whether omitting start/end defaults to all time, leaving an agent to infer call 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 100%, so all seven parameters are documented in the schema (date formats, user/client/practice ids, group_by pattern). The description only touches the trust parameter implicitly and adds nothing about how start/end/group_by scope the report, so the baseline of 3 applies.

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

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

States a specific resource (balance summary of all matters) and a scope modifier (optionally trust balances only), so the agent knows this is an aggregated financial report rather than a record fetch. It does not explicitly name which sibling report it substitutes for (e.g. lawcus_report_client_trust or lawcus_report_accounts_receivable), so differentiation is inferred rather than stated.

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

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

The Admin-role prerequisite is stated and the 'trust balances only' mode is implied, which gives partial usage context. However, there is no explicit when-to-use guidance versus the other report siblings, and no indication of when the trust mode should be preferred over the full balance summary.

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 openWorldHint, so the safety profile is covered. The description contributes the non-obvious Admin-role authorization requirement, which is genuine added context. It says nothing about how the period is bounded when start/end are omitted, or about result size/aggregation, leaving behavioral gaps.

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

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

A single front-loaded sentence with the permission constraint attached to the tool name, no filler. It is arguably terse to the point of under-specification, but every clause earns its place.

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

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

For a reporting tool with six optional parameters, no required fields, and no output schema, an agent still cannot tell what happens with an unbounded or empty period, nor what shape the report returns. The Admin prerequisite is present, but the 'all parameters optional' behavior is left unexplained.

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

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

Schema description coverage is 100%, so all six parameters already carry their own docs including date formats and id semantics. The description adds no parameter-level meaning such as whether filters combine (AND) or how user_id/matter_id narrow the collected-payments figures, so the baseline of 3 applies.

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

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

Names a specific resource and scope: 'payments the firm collected in a period,' which is a clear verb+resource statement. It is distinguishable from lawcus_report_revenue or lawcus_report_invoice_history by the 'collected payments' framing, though the description never explicitly contrasts with those siblings.

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

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

The '(needs the Admin role)' clause gives a real prerequisite for when the call will succeed. However, nothing tells an agent when to pick this report over lawcus_report_revenue, lawcus_report_invoice_history, or lawcus_report_accounts_receivable — the closest alternatives in the sibling list.

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 openWorldHint=true, so the safety profile is covered. The description adds the Admin authorization requirement, which is genuinely useful, but says nothing about aggregation behavior or what happens when filters are omitted.

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

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

A single compact sentence with the scope and role requirement front-loaded. It is efficient, though the compression drops detail an agent would want, such as default behavior with no filters.

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

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

All five parameters are optional and the description never says what the report returns with no start/end or no user_id — all attorneys, all time, or an error. With no output schema, that gap matters more, though the 100% schema coverage and annotations carry much of the load.

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

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

Schema description coverage is 100%, so all five parameters (start, end, user_id, client_id, matter_id) are documented with formats and bounds. The description's 'for a period' and 'by attorney' loosely map to start/end and user_id but add no syntax or semantics beyond the schema.

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

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

States a specific resource and grouping: revenue by attorney over a period, plus the role gate. It is distinguishable from siblings like lawcus_report_payments_collected or lawcus_report_time_entries, though it never names an alternative explicitly.

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

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

The Admin-role prerequisite is stated, which is real guidance, but there is no when-to-use vs when-not framing and no direction toward the other report tools when this one is the wrong fit.

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 openWorldHint=true, so the safety profile is covered. The description adds the real behavioral constraint that the Admin role is required, which is exactly the kind of context annotations cannot carry. It does not say what the summary contains, whether results are paginated, or how grouping affects output, so it adds value but not richly.

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

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

A single sentence with no filler, and the role prerequisite plus resource are front-loaded. It is arguably too compressed rather than too verbose, so it loses a point for under-specification rather than wordiness.

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

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

For a read-only report with 5 fully documented optional parameters and no output schema, the description covers purpose and the access prerequisite, but it never indicates what the result looks like (per-user rows with totals?) or whether omitting start/end or user_id widens the report. An agent can invoke it, but cannot predict its output shape.

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

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

Schema description coverage is 100%, so every one of the five parameters is already documented in the schema, including date formats and the group_by examples. The description's 'per user' and 'for a period' loosely tie user_id and start/end together but add no syntax or constraint beyond the schema baseline of 3.

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

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

States a specific verb and resource — time entries summarized per user for a period — which separates it from the raw-listing sibling lawcus_list_time_entries and from the other lawcus_report_* tools by naming the dimension being summarized (user) and the aggregation (summary rather than list). It does not explicitly name the alternative, so it stops short of a 5.

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

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

The prerequisite 'needs the Admin role' is genuine usage-condition information, but there is no statement of when to choose this report over lawcus_list_time_entries or the other report siblings, and no when-not guidance. Usage is implied by the phrase 'summarized per user for a period' rather than spelled out.

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 openWorldHint=true, so safety and open-world scope are covered structurally. The description contributes the cross-entity search scope, but says nothing about result limits, matching semantics, ranking, or how results from the three entity types are combined.

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-loaded with the resource scope; every word earns its place and nothing is padded.

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

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

For a simple one-parameter read tool this is close to adequate, and annotations cover the safety profile. With no output schema, though, the description never indicates what a hit looks like or whether results are grouped per entity type — an agent must call it blind to find out.

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

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

Schema coverage is 100% with a single documented 'terms' parameter, so the schema carries the burden and baseline 3 applies. The phrase 'for a keyword' merely restates the parameter rather than adding syntax or matching rules.

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

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

Names a specific verb (search) plus the exact resources covered (contacts, matters, leads) and scopes it as 'global', which separates it from the many lawcus_list_* siblings that enumerate a single entity type. It stops short of naming a sibling alternative explicitly, so it is clear but not maximally differentiated.

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

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

The word 'global' implies breadth-first lookup when the entity type is unknown, which is implicit guidance for choosing this over lawcus_list_contacts or lawcus_get_matter. However, no explicit when-to-use/when-not or reference to alternative tools is stated.

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