ALCBar Match

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

Annotations already establish readOnly, idempotent and closed-world behavior, so the bar is lower. The description adds meaningful context beyond them: the data is self-reported/confirmed, carries a last-checked timestamp, and has a certainty tier, which tells the agent results may be stale or provisional.

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 core subject front-loaded and no filler. The parenthetical enumeration of certainty states is dense but earns its place by defining the returned vocabulary.

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 lookup with no output schema, the description usefully previews return fields (last-checked time, certainty) and the data-freshness caveat. It remains incomplete on the four input parameters and on when to prefer it over the other attorney-lookup siblings.

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

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

Schema description coverage is only 25%, so the description should compensate, but it never mentions attorney_ids, time_zone, wanted_by or appointment_type. It describes output attributes (certainty, last-checked) rather than parameter meaning, leaving most inputs undocumented.

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

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

The description states a specific resource (attorney availability reported to ALCBar) and the nature of the data, including last-checked time and certainty levels. It distinguishes itself from a live-calendar tool, though it does not explicitly differentiate from siblings like get_attorney_profile or find_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?

The only usage signal is the negative constraint 'There is no live calendar access,' which tells the agent what the tool cannot do. There is no guidance on when to call it versus alternatives such as find_attorneys or request_attorney_introduction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the 2-5 attorney bound, what dimensions are contrasted, that verification gaps and trade-offs are surfaced, and that criteria can be inherited via match_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?

Two sentences, no filler. The comparison scope is front-loaded and the match_id instruction follows, so the actionable guidance is immediately visible.

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 previews what the comparison surfaces (fit, fees, availability, verification gaps, trade-offs) and the input bounds. The only gap is how criteria and priorities interact to weight the ranking, which is not explained.

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% (match_id and priorities carry schema descriptions; attorney_ids and criteria do not). The description restates the 2-5 bound on attorney_ids and the match_id criteria-inheritance behavior, which partially compensates, but 'criteria' and its enum values are left entirely to the schema, so it adds only marginal meaning overall.

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 (compare) and resource (lawyers) plus the cardinality bound (2 to 5) and an enumerated set of comparison dimensions: practice fit, location, years licensed, fees, availability, verification gaps, trade-offs. It is clearly distinct from profile-lookup or finder tools, though no sibling is named outright for differentiation.

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 line 'Pass match_id to use the user's criteria' gives one concrete usage rule tied to a sibling tool (find_attorneys), which is genuinely useful. However, there is no explicit when-to-use/when-not guidance versus get_attorney_profile or find_attorneys, so usage is mostly implied.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's real contribution is disclosing output provenance — published fees vs. confirmed quotes vs. sourced market figures — and the failure behavior of stating plainly when data is insufficient. That is genuine behavioral context beyond the structured fields.

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

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

Three short sentences, front-loaded with what the tool returns before the honesty caveat. Slight redundancy between 'instead of guessing' and 'Not a quote', but no filler sentences.

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

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

With no output schema, the description usefully characterizes the returned fee labels and the insufficient-data case, which is the right thing to disclose. However, for a seven-parameter tool with 43% schema coverage it leaves input semantics largely unexplained, so an agent can invoke it but not confidently populate the optional filters.

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 43% across seven parameters, so the description must compensate and does not. It loosely gestures at matter type and specific lawyer, but says nothing about scope, state, budget_max, billing_preference, or the free-text description field, leaving the two undescribed enums 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?

The description states a specific resource — fee information — for either a matter type or a specific lawyer, which maps onto the practice_area and attorney_id inputs. It is clearly distinct from siblings like get_attorney_profile or compare_attorneys, though the verb 'estimate' from the name is only implied by the 'fee information' phrasing.

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

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

The only guidance is the caveat 'Not a quote', which frames the output rather than when to call the tool. With nine siblings in the matching family, no alternative is named and no condition for choosing this tool over get_attorney_profile or compare_attorneys is given.

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

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

Annotations indicate readOnly=false and idempotent=false, but the description clarifies that it returns ranked results with reasons, sources, gaps, and is not legal advice. It adds honest transparency about data limitations, which is valuable beyond annotations.

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

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

Two concise sentences that front-load the core purpose and key outputs. No wasted words.

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

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

Given the large parameter set and no output schema, the description is incomplete. It explains the ranking logic and result content, but omits parameter usage, which is critical for an agent to invoke 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 coverage is only 47%, and the description does not mention any parameters. With 36 parameters, many undocumented, the description fails to compensate for the coverage gap. Only 'limit' is indirectly referenced.

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?

Uses a specific verb ('Find') and resource ('licensed lawyers') and states the ranking dimensions. Clearly distinguishes from siblings like compare_attorneys and get_attorney_profile, which are follow-up rather than discovery tools.

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

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

Implies this is the entry point for matching, but does not explicitly say when to use it over get_matching_requirements or update_matching_preferences. The 'no-match' behavior and 5-result default are clear usage details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered structurally. The description's only added behavioral signal is 'Public' (visibility of the data) and 'data freshness' as a returned field, which is modest extra context.

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

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

A single dense sentence with the resource and lookup key front-loaded and the returned fields following. No wasted words, though it is a sentence fragment rather than a complete statement of 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 simple single-parameter read whose annotations carry the safety profile and which has no output schema, the field enumeration effectively substitutes for a return-value description. What is missing is any routing context within the matching toolset.

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 nothing documents attorney_id beyond its uuid format and pattern. The description supplies the key insight that the id refers to a single lawyer whose profile is returned, which is marginally more than the parameter name alone conveys, but it adds no format or sourcing detail.

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 concrete resource and scope – a single lawyer's public matching profile retrieved by attorney_id – and enumerates the fields it contains. This is enough to separate it from list-oriented siblings like find_attorneys or compare_attorneys, though it never names those alternatives 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?

There is no when-to-use or when-not-to-use guidance. The phrase 'by attorney_id' implies a prerequisite key, but nothing tells the agent how this differs from check_attorney_availability, compare_attorneys, or find_attorneys in a matching workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds one useful scope trait (it will not answer the legal question) but says nothing about what the returned gap list/questions look like or how many rounds of input are expected.

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

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

Two tight sentences, front-loaded with the purpose and closed with the scope boundary; no filler. It is efficient, though for a 33-parameter tool the terseness edges toward under-specification rather than pure conciseness.

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

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

No output schema exists, so the description must describe the return shape, yet it only gestures at 'missing details... and the questions'. For a 33-param, zero-required gap-analysis tool in a matching workflow, an agent lacks enough to invoke it confidently or know what comes back.

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

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

With 33 parameters and only ~45% schema description coverage, the description carries real burden and adds none — it never mentions a single input field or how known-vs-missing details are supplied. Several undocumented fields (city, court, county, urgency, category, languages, matter_type, communication, etc.) are left with neither schema nor description meaning.

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 concrete verb and output ('list the missing details... and the questions to ask') scoped to 'what is known about a legal matter', so an agent knows this returns a gap analysis rather than attorney results. It distinguishes itself from matching siblings mostly by implication plus the closing boundary 'Does not answer the legal question', but never names the siblings it is not (e.g., find_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?

Usage is only implied: the name and 'would improve a lawyer match' suggest calling this before a matching/find step, but there is no explicit when-to-use, prerequisite, or alternative named among the nine siblings. The one boundary given ('Does not answer the legal question') is a when-not hint, which keeps this above a bare 2.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context by enumerating the possible status values (sent, tentative, confirmed, cancelled, completed), which is otherwise absent since there is no output 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 sentences, front-loaded with the status enumeration and ending with the parameter prerequisite. No filler, though the final sentence adds little beyond what the schema surface implies.

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 enumeration of status values is necessary and present, but the required referral_id parameter is never mentioned and the description says nothing about token lifetime, error states, or what happens for an unknown referral. Adequate but with clear gaps.

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

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

Schema coverage is 50%: status_token is documented in the schema while referral_id, the sole required parameter, is documented nowhere. Worse, the description says the call "Needs the referral's status_token," implying status_token is required, while the schema marks only referral_id as required — the description misdirects the agent on parameter requirements.

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 (check) and resource (introduction's status) and enumerates the states it reports, which lets an agent distinguish it from the sibling request_attorney_introduction. It does not explicitly name a sibling, so it falls short of a 5.

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

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

The prerequisite ("Needs the referral's status_token") is stated, implying usage after a referral is created, but there is no explicit when-to-use guidance or comparison to alternatives like request_attorney_introduction.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's extra context is what counts here: the consent gate, the guarantee that only user-authorized fields are shared, and the fact that it returns a referral id plus a private status token. That is meaningful disclosure beyond the annotations, though it says nothing about failure modes, duplicate handling, or delivery latency.

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 short sentences, zero waste, with the consent precondition front-loaded and the return value disclosed at the end. Every sentence carries information the 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?

For an 11-parameter write tool with a nested consent object and no output schema, the description covers the highest-risk aspects (consent gating, authorized-field sharing, return shape) but leaves most parameter semantics undocumented. Adequate for safe invocation, incomplete for correct invocation.

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

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

Schema description coverage is only 36% across 11 parameters, so the description must compensate and largely does not. It touches only the consent concept ('shares only the fields the user authorized'), leaving state, contact, match_id, practice_area, preferred_contact_method, attribution_token, and idempotency_key unexplained in both schema and description.

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

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

States a specific verb and resource ('Record a client-authorized introduction to ONE lawyer'), which is distinguishable from discovery siblings like find_attorneys and get_referral_status. It does not name a sibling explicitly, so it falls short of the 5 bar, 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?

Gives an explicit precondition: call only after the user has seen the lawyer's name, the exact details to be shared, and explicitly agreed. That is strong when-to-call guidance. It stops short of a 5 because it names no alternative tool (e.g., use find_attorneys to obtain attorney_id first) or when-not-to-call condition.

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 disclose that this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds one genuinely useful behavioral constraint ('No case details'), but says nothing about needing a match/referral identifier or status token to associate the feedback, and nothing about resubmission/idempotency semantics.

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

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

Two dense sentences with no filler, and the rating scope is front-loaded. The brevity is efficient, though it comes at the cost of the missing semantic detail noted above.

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

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

For a 12-parameter mutation tool with no output schema and near-zero schema coverage, the description is too thin: it omits the identifiers/token required to target the submission, does not disambiguate the three satisfaction dimensions, and does not indicate what happens on submission or whether ratings can be revised later.

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 8% schema description coverage, the description must carry the burden, and it only partially does: it maps to relevance, responsiveness, pricing_accuracy, availability_accuracy, the satisfaction fields, and retained. It leaves comment, match_id, referral_id, and status_token completely undocumented in both schema and description, and it collapses the three distinct satisfaction_* parameters into one ambiguous 'satisfaction'.

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 clearly: it collects 1-5 ratings on match relevance, responsiveness, pricing/availability accuracy, satisfaction, and hiring outcome. An agent immediately understands this is a post-match rating submission. It does not, however, differentiate itself from sibling tools like update_matching_preferences or get_referral_status, 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 word 'Optional' signals that individual ratings are not mandatory, which is mild guidance, but there is no statement of when this tool should be called (e.g., after a referral/introduction completes) or which sibling to use instead. No prerequisites, no exclusions, no alternatives 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?

Beyond the annotations (which only say non-read-only, non-idempotent, non-destructive), the description discloses three useful traits: data is keyed to this conversation, personal contact details must not be included, and records auto-expire after 24 hours. It stops short of describing update-vs-create behavior or what a save returns.

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

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

Three tight sentences with the action and scope front-loaded, then the PII constraint, then the retention rule. No filler or repetition, though the parenthetical field list is the least load-bearing part.

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

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

For a mutation tool with ~30 nested optional fields and no output schema, the description covers retention and the PII prohibition but omits update semantics (partial vs full replacement of criteria, what clear_fields does, when a new preference_set_id is created). Adequate but with visible gaps given the tool's complexity.

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

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

Schema description coverage is 67% and the nested criteria object already documents most fields with patterns, enums and semantics (e.g. budget_min/max, priorities ordering). The description lists broad categories (location, budget, timing, practice area, language, priorities) but adds essentially no meaning beyond that enumeration. The 'no personal contact details' rule is a genuine constraint on the criteria parameter.

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

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

States a specific verb pair (save/change) and resource (matching criteria) and enumerates the criterion categories, so the agent knows this persists filtering preferences for a conversation. It does not, however, distinguish itself from close siblings like get_matching_requirements or find_attorneys, which an agent would need help disambiguating.

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 never says when to call this versus get_matching_requirements (read the stored criteria) or find_attorneys (act on them). 'For this conversation' implies scoping but provides no explicit when/when-not guidance or named alternatives among the ten siblings.

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