ESQ Matching Engine

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

Beyond the readOnly/idempotent annotations, it discloses provenance ('only what lawyers reported or confirmed'), that results carry a last-checked time and certainty level (reported/tentative/confirmed), that unknown means no report, and the hard limit 'There is no live calendar access.' This is exactly the behavioral context an agent needs to avoid over-promising.

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: trigger first, then output semantics, then the caveat. Every sentence carries load and nothing is repeated from the schema or annotations.

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

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

With an output schema present, return-value detail is not required, and the certainty-model caveat covers the main ambiguity. The only missing piece is guidance on the undocumented parameters (time zone, appointment type, batch 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 description coverage is only 25% — four parameters, only wanted_by is documented. The description never mentions attorney_ids, time_zone, or the appointment_type enum, so the meaning of three parameters rests entirely on bare schema types/enums.

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

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

The description states a specific verb and resource ('whether a lawyer takes new clients or can meet soon') and clarifies the result is availability signal, not a booking. It does not explicitly distinguish itself from siblings like get_attorney_profile or request_attorney_introduction, but the purpose 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?

'Use when the user asks whether a lawyer takes new clients or can meet soon' is a clear triggering condition. It stops short of naming when to prefer a sibling (e.g., profile lookup or introduction request) or what to do when availability 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it reports data confidence and gaps, and explicitly flags when price or timing cannot be compared because data is unknown — a useful disclosure about output quality.

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

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

Three sentences, no filler. The usage trigger is front-loaded, the scope and compared dimensions follow, and the caveat about incomparable data closes it out.

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?

An output schema exists, so return structure need not be described. The description covers when to call, what gets compared, and the key limitation on price/timing. The only real omission is guidance on how priorities interact with criteria, which an agent would have to infer.

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%. The description maps loosely onto criteria (fees, availability, practice fit) and reiterates the 2–5 bound already encoded in attorney_ids minItems/maxItems, plus explains match_id's purpose. However, 'priorities' — the parameter that shifts ranking weights — is never mentioned, and the criteria vs priorities distinction is left to the schema.

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

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

States a specific verb (compares) and resource (lawyers), bounds the input (2 to 5), and enumerates the dimensions compared (practice fit, location, years licensed, fees, availability, confidence, gaps). This clearly separates it from get_attorney_profile and the other siblings, which operate on one attorney at a time.

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

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

Gives an explicit trigger ('when the user asks to compare lawyers from find_attorneys') with a sample utterance, and ties match_id to reusing the user's criteria. It lacks an explicit 'do not use for a single attorney, use get_attorney_profile instead' exclusion, which keeps it 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?

Beyond readOnly annotations, it discloses important behavior: results are limited to published fees, confirmed quotes, or sourced market figures, each labeled, and the tool will say when data is insufficient rather than guessing. This meaningfully sets expectations for reliability and uncertainty.

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 and front-loaded, with the primary use case stated first followed by return behavior and a limitation. Every sentence contributes useful information.

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

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

Given the annotations and output schema, the description is largely complete: it explains purpose, return sources, labeling, and uncertainty handling. The main gap is how optional parameters should be used, especially given low schema description coverage.

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

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

The description adds no guidance on the seven input parameters, including scope, state, budget_max, billing_preference, and attorney_id. With only 43% schema description coverage, the description should compensate for undocumented parameters 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 states a specific purpose: estimating what a lawyer or type of legal matter will cost. It is clearly distinct from the attorney-search, availability, and referral tools, though it does not explicitly name those siblings.

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

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

It gives a clear trigger: use when the user asks what a lawyer or matter will cost. It does not name alternatives or explicitly state when not to use it, aside from clarifying that the result is not a quote.

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

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

Goes well beyond the annotations by disclosing privacy behavior (anonymous search log only), a scope exclusion rule (court/government lawyers omitted unless they take private clients), honest labeling of unknown fees and availability, no-match fallback to legal-aid options, and the "not legal advice" disclaimer. These are exactly the operational facts an agent needs before calling a matching tool and are not derivable from readOnlyHint/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?

The trigger condition is front-loaded in the first clause and every sentence carries operational content (inputs, return shape, exclusions, privacy, disclaimer). The middle sentence enumerating return fields is long and partially duplicates the output schema, but it is a single sentence rather than 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 37-parameter open-tool with an output schema, the description covers the key decision points: when to use it, minimum required inputs, result cap of 5, exclusion rules, honest-unknown handling, and no-match behavior. Gaps remain around how location inputs interact (ZIP vs city vs county vs court) and pagination or exclusion-by-ID behavior, which matters given the parameter count.

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

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

With 37 parameters at 49% schema coverage, the description only covers the essential inputs (state, matter type, or a short description) and omits meaning for location fallbacks (city/county/court), urgency, languages, budget, and the many matching refinements. It surfaces the one critical usage fact (state and matter type are what's needed), but does not compensate for the large undocumented remainder.

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 (find licensed lawyers) plus two concrete trigger examples and the tool's scope (U.S. legal matters), so an agent knows exactly what it will get back. It never names a sibling tool (compare_attorneys, get_attorney_profile) to contrast against, so differentiation is inferable rather than 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?

"Use when someone wants a lawyer for a U.S. legal matter" plus the Santa Ana tenant and Los Angeles wrongful-termination examples give crisp invocation context, and it specifies the minimal inputs needed (state plus matter type or a short description). It gives no when-not guidance or explicit routing to sibling tools such as compare_attorneys or check_attorney_availability.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: license source and check date, data freshness, directory link, suggested citation, and exact consent text required before an introduction.

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 usage condition is front-loaded, followed by a compact return summary and the consent-text detail. The dense return list earns its place because each item clarifies what the caller receives.

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 an output schema and safety annotations present, the description does not need to explain return values or read-only behavior. It is nearly complete, but would be stronger if it stated where attorney_id comes from.

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 one required UUID parameter is not documented in the schema. The description implies it identifies 'one lawyer from a match,' but it does not explain the ID's provenance, format, or where to obtain it.

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

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

The description states a specific verb and resource: getting details on one lawyer, with the scope 'from a match.' This clearly distinguishes it from list/search siblings like find_attorneys and compare_attorneys.

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

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

It gives a clear when-to-use condition: the user wants details on one lawyer from a match. It does not explicitly name alternatives or exclusions, but the context is strong enough for correct 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 declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds value beyond that by describing the response shape (remaining questions plus a summary of what was understood) and scope limits (no legal answers, no storage), which tell the agent this is a tolerant, partial-input clarification step.

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

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

Three short sentences, zero waste: usage trigger front-loaded, then what is returned, then what it does not do. Nothing repeats the schema or annotations unnecessarily.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. For a 33-option schema with zero required fields, the one missing note is that parameters are all optional and only known/confirmed values should be passed, but overall the description is sufficient to invoke 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?

With 33 parameters and only 45% schema description coverage, the description should compensate more. It does enumerate the key dimensions to supply (state, matter type, location, timing, budget), which is useful guidance, but does not map them to parameter names or address the many undocumented parameters (city, court, languages, client_side, service_needed, etc.).

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 output ("Returns the few questions still needed ... and what was understood") and scopes it precisely to ambiguous lawyer requests. An agent can distinguish it from find_attorneys or compare_attorneys without opening any schema, since it clearly gathers requirements rather than returning attorneys.

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?

"Use first when someone asks for a lawyer but the state or type of legal matter is unclear" gives an explicit trigger with two concrete example utterances. It also sets exclusions (does not answer the legal question), though it never names the follow-up sibling (find_attorneys) the agent should route to once requirements are filled.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: an authentication requirement ("Needs the private status_token"), the full enumeration of lifecycle states needed to interpret results, and the semantic rule that a consultation counts only when confirmed.

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 trigger is front-loaded, followed by return contents, credential requirement, and a clarifying caveat — each sentence earns its place. The 10-value parenthetical is long but high-value for interpreting output, so it is justified rather than 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 simple two-parameter read with an output schema and full annotation coverage, the definition is nearly complete: it states the trigger, the auth need, return fields, and a domain caveat. The one gap is the unresolved tension over whether status_token is truly mandatory versus optional as the schema declares.

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%: status_token is documented in the schema, while referral_id has only a pattern and no prose. The description flags that status_token is 'private' and needed, which adds meaning, but it never explains referral_id and its 'Needs the status_token' phrasing sits awkwardly against a schema where only referral_id is required.

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

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

The description names a specific retrieval action on a specific resource ('what happened with an introduction') and enumerates the lifecycle_state values returned, which makes it unmistakably distinct from the sibling write tool request_attorney_introduction. An agent can identify the tool's function 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?

"Use when the user asks what happened with an introduction" gives a clear trigger condition tied to user intent. It does not, however, name alternatives or state exclusions (e.g. use request_attorney_introduction to create, or what to do if the token was lost), so it stops short of full routing guidance.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description adds material context beyond them: only authorized fields are stored, idempotency_key retries do not duplicate, and critically that sending is switched off so the action is recorded, not delivered. That last fact would otherwise cause the agent to report a completed introduction.

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?

Preconditions come first, then guardrails, then storage/idempotency behavior, then the critical operational caveat and return values. Every sentence carries distinct information an agent needs to act correctly; the capitalized emphasis on RECORDED, NOT SENT is load-bearing rather than 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 destructive, open-world, 11-parameter write with an output schema, the description covers the consent gate, the current no-send state, and the return shape (referral id, lifecycle_state, status token). It stops short of describing failure modes (e.g. consent.confirmed rejected, invalid attorney_id) or what match_id/practice_area are for.

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

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

Schema coverage is only 36%, so the description must carry weight; it explains the consent contract (fields_authorized sourced from get_attorney_profile) and idempotency_key retry semantics. But of 11 parameters, match_id, practice_area, attribution_token, preferred_timeframe and preferred_contact_method go unexplained in both schema and description, leaving a real gap.

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

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

States a specific verb and resource (request an introduction to ONE specific lawyer) and scopes it to exactly one recipient. It also names the sibling it depends on (get_attorney_profile) and the precondition chain, so an agent can distinguish it from compare_attorneys or find_attorneys immediately.

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

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

Gives explicit when-to-use conditions (user asked, has seen the name/details/consent text, said yes) and explicit when-not-to (never on own initiative, never for several lawyers at once). The alternative path — give phone or profile link via get_attorney_profile — is 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 this is a non-read-only, non-idempotent, non-destructive write with no open-world access, and the description adds only the privacy constraint "No case details." It does not disclose what a submission creates, whether a match_id or referral_id is required, what status_token authorizes, or what happens on resubmission.

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 no filler, and the scope of collected ratings is front-loaded. The second sentence ("No case details.") is a high-value constraint rather than 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 12-parameter tool with zero required parameters and three ambiguous satisfaction fields, the description leaves the agent guessing which identifiers and ratings to supply. The presence of an output schema removes the need to explain return values, but the input-side guidance is still thin.

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

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

Schema description coverage is only 8% (just the comment maxLength note), so the description must carry parameter meaning and largely does not. It names rating topics like "satisfaction" but never disambiguates satisfaction_match vs satisfaction_process vs satisfaction_attorney, and says nothing about match_id, referral_id, or status_token — the identifiers the call likely depends on.

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 (feedback ratings on a match/introduction) and enumerates the dimensions collected, so an agent can tell what the tool records. It is distinguishable from siblings like request_attorney_introduction or get_referral_status, though it never states that distinction explicitly.

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

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

"Optional" is the only usage signal; there is no statement of when submitting feedback is appropriate, whether it can be repeated or revised, or what the alternative is if the caller only wants to read referral state. An agent must infer the trigger condition entirely.

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

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

Annotations already flag the tool as destructive, non-read-only, and idempotent. The description usefully adds that data is deleted automatically after 24 hours and that no personal contact details should be stored, though it does not explain how clear_fields behaves or exactly what can be removed.

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 three short sentences, front-loads the action and scope, and then adds the two most important constraints. There is no redundant repetition of schema fields.

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 is complex and destructive, with a rich nested schema and an output schema. The description covers purpose, privacy, and retention, but leaves important update semantics unclear, especially how clear_fields works and when preference_set_id creates versus updates a set.

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

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

Schema coverage is 67% and the nested criteria object is heavily documented by the schema itself. The description enumerates criteria categories but adds little meaning for clear_fields or preference_set_id, so it only partially compensates for the remaining 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 states a specific action and resource: save or change matching criteria. It also scopes the operation to this conversation and lists representative criteria categories, making it distinguishable from read-oriented siblings like get_matching_requirements.

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

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

Usage is implied by 'Save or change matching criteria' and the conversation scope, but there is no explicit when-to-use guidance or comparison to alternatives such as get_matching_requirements. It does add the constraint that personal contact details must not be included.

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