ShearQuery — Barber & Beauty Industry Data

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds real behavioural detail: content is sectioned by topic, omitting topic returns the whole playbook, and it contains concrete commission numbers and 'never promise' guidance.

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 'For AGENCIES:' lead is well front-loaded, but the body is a long comma-spliced list of content categories that reads as inventory padding rather than precise routing 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?

With no output schema, the description carries the burden of explaining what is returned, and it does list the content sections plus the whole-vs-section default. Adequate for a zero-required-parameter reference tool.

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

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

Schema coverage is 100% and the single topic enum is already documented in the schema ('Leave out for the whole playbook'). The description only restates this ('Pass a topic for one section'), 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?

Names the resource (ShearQuery partner-program playbook) and enumerates its contents, so an agent knows this is a static reference/teaching document rather than an action tool. It does not explicitly differentiate itself from the nearby what_shearquery_does tool, which is the only gap.

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

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

Gives clear triggering contexts ('teach a new agency', 'whenever an agency asks how to do something or what to say') and a directive to answer from it rather than improvise. No explicit when-not or sibling routing, but the usage condition is unambiguous.

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=false, so the safety profile is covered. The description adds genuinely useful behavior: results are limited to already-published videos, scoped to the agency's own Instagram, and it enumerates the returned fields (ref, title, type, post date, length, IG link) despite there being 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, no filler, and the audience constraint is front-loaded before the search behavior and return 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?

For a read-only, no-output-schema search tool it is nearly complete: eligibility, search semantics, downstream ref usage, and return fields are all stated. The only gap is pagination/limit behavior for the limit and offset parameters.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the query parameter well (title/caption keyword search with concrete examples), but is silent on limit (max 30) and offset, leaving two of three parameters undocumented anywhere.

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

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

It names the exact resource (Shorts and Reels ShearQuery has already published) and the scope/audience (an APPROVED AGENCY reposting to its own Instagram). An agent can distinguish this from siblings like my_instagram_posts or queue_agency_post without opening any schema.

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

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

It states the eligibility precondition (approved agency) and how to search (words in title or caption, with examples). It also routes the agent forward by naming queue_agency_post as the consumer of the returned ref, though it does not state explicit when-not conditions or a sibling alternative for browsing non-published content.

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 readOnlyHint=true, so the agent knows it's a safe read operation. The description adds valuable behavioral context beyond annotations: it compares against local medians computed from a private directory, returns a coverage figure because the public tier can only see part of the audit, and warns never to present the score as a complete audit. This is exactly the kind of context that helps an agent set expectations and avoid misusing the result.

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 sentences, each earning its place: the first states the core function, the second explains the comparison methodology, and the third discloses the coverage limitation. It is front-loaded with the action and resource, and there is no wasted wording.

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 tool with two well-documented parameters and no output schema, the description is quite complete. It explains the scoring basis, the local median source, and the coverage limitation. The only minor gap is that it doesn't describe the exact return format (e.g., whether the ranked missing items are a list or a string), but the description's warning about coverage is more important and is covered.

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 both parameters. The description adds context about the business types and the comparison logic, but it doesn't add much detail about the parameters themselves beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb ('Score'), a specific resource ('a named barbershop, salon, barber/cosmetology school or beauty supply store's public Google Business Profile'), and the output ('what is missing, ranked'). It also distinguishes itself from siblings by naming the exact business types it covers, which helps an agent select it over compare_barbershops_salons or compare_barber_cosmetology_schools.

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 clearly implies when to use this tool: when a single named business needs a Google Business Profile score. It does not explicitly state when not to use it or name alternatives, but the sibling list and the description's focus on a single business make the usage context clear. A small gap: it doesn't explicitly say 'use compare_barbershops_salons for comparing multiple businesses'.

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?

Adds real behavioral context beyond the annotations: it explicitly states existing appointments are NOT cancelled and that the call reports overlaps, which is important given destructiveHint=false and idempotentHint=false (a repeat call may create another block). It does not discuss auth/permission requirements or whether the block is scoped to one calendar/provider.

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; the core action and its parameter-driven variants are front-loaded, and the non-cancellation caveat follows immediately. No filler or restatement of the title.

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

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

No output schema exists, but the description compensates by noting the call reports overlapping appointments. With 5 parameters at 80% coverage and one required field, the definition is nearly complete; only the `reason` parameter and auth expectations are unaddressed.

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

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

Schema coverage is already 80%, but the description adds the combinatorial meaning the schema cannot: which parameters must be paired together for each blocking mode. The only gap is `reason`, which is undocumented in both the schema and the description, a minor omission for a non-required field.

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 ('block time so nothing can be booked in it') and decomposes the operation into three unambiguous modes (whole day, date range, partial day) keyed to parameter combinations. An agent can immediately tell this apart from browsing tools like find_open_times or the scheduling siblings, which all read or create bookings rather than reserve unbookable blocks.

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

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

Clearly signals when each parameter combination applies (date alone vs. date+end_date vs. date+start+end), which is genuine usage guidance for choosing an invocation shape. It never names an alternative for the inverse operation — remove_time_off is the obvious counterpart and goes unmentioned — so sibling disambiguation is left implicit.

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 a non-read-only, non-destructive, non-idempotent write, so the bar is lower. The description adds genuine behavioral context beyond that: it refuses overlapping bookings, defers to the owner for outside-hours/time-off requests, and states it does not text the client. It stops short of noting auth requirements or whether re-booking duplicates an entry.

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

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

Front-loads the action and required fields, then appends constraints in short sentences with no filler. The parenthetical 'plus phone so repeat visits link up' is slightly crammed but still 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 9-parameter mutation tool with 33% schema coverage and no output schema, the description covers the main fields and the important behavioral edge cases, but leaves walk_in and notes unexplained and says nothing about the result of a successful booking. Adequate but with visible 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 only 33%, so the description has to carry weight and it does for some fields: 'phone so repeat visits link up' explains client_phone, and the allow_outside_hours gating explains that flag. But it leaves walk_in, notes, and the required-vs-optional distinction unaddressed, so the compensation is partial.

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

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

States a specific verb ('Book a client in') and the resource with its key fields (service, date, time, client name/phone), so the agent knows exactly what the tool creates. It does not explicitly differentiate itself from nearby siblings like book_with_pro or find_open_times, which keeps it short of a 5.

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

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

Provides real conditional guidance: only set allow_outside_hours after the owner confirms, and it explains that the tool asks first outside working hours. It gives clear context for use but never names an alternative sibling (e.g. book_with_pro, find_open_times) or when NOT to use this tool.

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

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

Annotations only declare that this is a non-idempotent, non-destructive, open-world write. The description adds genuinely new behavior: a Stripe payment link may be returned, the slot is held for 30 minutes and only booked once paid, a deposit/full payment may be required, and the phone must be verified. These are the facts an agent needs to set expectations and sequence steps.

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

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

Front-loaded with the action and the source of each input, then prerequisites, then payment behavior, then the sibling route-out. Dense with substance, though it runs long and could tighten the payment-policy sentence without losing meaning.

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

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

Despite having no output schema, the description tells the agent what comes back (a secure Stripe payment link), how long the hold lasts, and what the client must do. For a 7-param booking write tool, this is complete enough to invoke correctly end to end.

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 57% and the description compensates well for the important ones: pro_id's provenance (find_pros_to_book), time's format source (pro_open_times), and the optional tip tied to the payment. It adds little for name and notes, which remain thin, but the load-bearing parameters are clarified.

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 ('Book the client a NEW appointment with a pro') and pins the inputs to their sources (pro id or booking handle from find_pros_to_book, time from pro_open_times). It explicitly distinguishes itself from reschedule_my_booking, so an agent can route correctly without opening schemas.

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

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

Gives explicit preconditions (confirmed mobile via verify_my_phone, client must be told the booking policy and give OK) and names the alternative for the change case ('never book a second one: use reschedule_my_booking'). When-to-use and when-not-to-use are both covered.

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=false, so no destructive or open-world behavior is expected. The description adds valuable non-obvious behavior: data comes from the ShearQuery directory, coverage is deepest in Houston and thinner elsewhere, and city results with fewer than 5 reported rates return a count without a median. These caveats are materially useful 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 dense and front-loaded with the main operation, followed by data-source context and edge-case behavior. The final explanatory clause is slightly wordy but earns its place by clarifying why sparse data is handled differently. No filler or redundant restatement of the title.

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

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

Given that there is no output schema, the description does a good job enumerating the returned metrics and explaining threshold and omission behavior. The optional parameters are fully covered by the schema PARA. The only minor gap is that it doesn't describe the exact response structure or explicitly routing to alternatives, but neither is essential for this tool.

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

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

All three parameters (city, type, examples) have full descriptions in the schema, so the baseline is 3. The description reinforces the city-omission behavior and the 'with a published rate' qualifier for examples, but it doesn't substantially add semantic meaning beyond what the schema already provides.

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: 'Return what barbershops and salons in a city actually charge for a chair or suite' and enumerates the metrics (median weekly rent, range, venue counts, chairs, hiring). This distinguishes it from siblings like compare_barbershops_salons and compare_barber_cosmetology_schools, which focus on comparisons rather than actual city-level rent benchmarks.

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 context for how to invoke different behaviors: include a city for local figures, omit it for the overall picture and cities with the most reported rates, and be aware that fewer than 5 reports suppress the median. It never explicitly names a sibling as the alternative, so it stops short of a 5, but the usage context is more than 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 indicate destructive=true, idempotent=true, and readOnly=false, so the safety profile is partially covered. The description adds useful behavior beyond annotations: refunds of booking payments and tips, owner-confirmation requirements, and the conditional client text via notify_client.

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 front-loaded with purpose and effect, then adds refund and notification guidance in a compact sequence. Every sentence adds useful context, though the aside about the pro never being at fault is slightly conversational.

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, idempotent cancellation tool with no output schema, the description covers the key behavioral concerns: owner confirmation, refunds, and client notification. The main remaining gap is the unexplained reason parameter, which is minor relative to the overall guidance.

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 33%, so the description must compensate. It explains that id comes from my_schedule and clarifies notify_client behavior, but it leaves the reason parameter completely 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 verb and resource: canceling an appointment, with the id coming from my_schedule, and mentions the effect of freeing the time. It does not explicitly name or distinguish itself from the sibling cancel_my_booking, so it falls short of the highest clarity tier.

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 operational guidance: confirm with the owner first, and ask the owner before texting the client via notify_client. It does not explain when to prefer this tool over siblings such as cancel_my_booking or update_appointment_status, but the context is otherwise clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the mutation profile is covered. The description adds genuinely new behavior: confirm before cancelling, refund amount is dictated by the pro's own policy, and a too-late cutoff sends the client to the pro.

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, none wasted, with the destructive-scope and id source front-loaded. Slightly dense prose but every clause adds a distinct constraint.

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-param mutation with annotations covering safety and no output schema, the description supplies the key missing pieces: confirmation step, refund-policy dependency, and the too-late fallback. Only a pointer to the reschedule alternative would make it fully complete.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does identify where the single required id comes from (my_bookings). It stops short of describing format or failure behavior when the id is invalid.

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 (Cancel) and resource (one of the client's own appointments), and identifies the id's source (my_bookings). That scope wording separates it from pro-side siblings like cancel_appointment and from reschedule_my_booking.

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

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

Gives clear operational context: confirm first, and when it's too late the client must contact the pro instead. However, it does not name a sibling alternative (e.g., reschedule_my_booking) for the common 'change rather than cancel' case, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds real value: the permission-gating behavior, the graceful failure mode for non-shared clients, the 'nothing here changes the client's account' guarantee, and the privacy constraint that customer details are excluded. It stops short of describing output/pagination format, but the addition beyond annotations is substantial.

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

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

Front-loaded with the audience and operation ('For an AGENCY: a read-only health check...'), then the safety and access constraints. It is dense but every clause carries information, though the long em-dash enumeration of covered areas makes it heavier than strictly necessary.

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 results and does so by enumerating the health-check contents. Access conditions, safety profile, and privacy limits are all covered, leaving nothing an agent needs in order 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?

Schema description coverage is 100%; the single 'client' parameter is documented as 'the client's name as shown in my_agency.' The description implies the same identifier ('one of its clients') but adds no syntax or format detail beyond the schema, so the 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?

The description states a specific verb and resource ('read-only health check on one of its clients') and enumerates exactly what the check covers (Google connection, failed changes, Autopilot, audit score, etc.). It is clearly distinguishable from adjacent tools and is scoped to agency use.

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

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

It gives an explicit precondition ('Only for clients who have switched on sharing with this agency'), states what happens otherwise ('for others it says so'), and names the alternative to use in that case ('request_client_access can ask them'). When-to-use and the fallback path are both 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=false, so the safety profile is known. The description adds valuable behavioral context: it reveals data provenance (state licensing exam outcomes), the exclusion rule (schools with <5 test-takers), and the coverage boundary (not from Google/school websites). This exceeds the baseline and adds meaningful transparency.

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

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

The description is concise (two sentences) and front-loads the core purpose. Each clause adds value: the data source, the metrics, the optional filter, and the data caveat. No redundant or filler content.

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

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

Given the tool has no output schema, the description adequately explains what results to expect (rankings by pass rates and tuition). It covers the data source, the exclusion logic, and the optional filter. The enumeration of metrics (written/practical pass rates, etc.) prepares the agent for the response shape. With 3 parameters and no nested objects, this is complete for effective 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 100%, so parameters are well-documented. The description adds nuance: it explains the 'license' parameter's significance (separate exams) and implies what 'city' filters (optional). It doesn't repeat the schema but provides context on how the parameters affect results (e.g., ranking by exam outcomes). Justification for 4: the description enhances understanding beyond the schema by connecting parameters to the ranking logic, though not exhaustively.

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

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

The description clearly states the tool ranks schools by exam outcomes and supports filtering by city. It names the specific resource (barber/cosmetology schools) and the action (compare/rank). However, it doesn't explicitly distinguish itself from the sibling 'compare_barbershops_salons', which might be confused as similar, though it does specify the data source differentiates it.

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 this tool: when you need objective exam pass rates and tuition data, and explicitly states the data is not available from other sources, which signals its unique value. It doesn't explicitly exclude alternatives, but the context is clear. It would benefit from explicit 'when not to use' guidance, but it's adequate.

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

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

Annotations already mark readOnlyHint=true, so no safety caveat is needed. The description adds meaningful behavioral context: booth rent is 'quoted directly by shops rather than scraped,' coverage is partial, and the response states how many listings publish a rate. This is valuable provenance and trust information beyond what annotations provide.

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

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

Three sentences, each earning its place: the purpose, the practical answer it provides, and the critical coverage caveat. The description is front-loaded with the core ranking criteria and contains 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 read-only search tool with six self-describing parameters and no output schema, this is largely complete: it explains scope, ranking dimension, availability filters, and the partial-coverage caveat. It does not describe the exact response shape, but the schema and read-only annotations cover enough for an agent 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?

Schema description coverage is 100%, so the description need not repeat parameter definitions. It does add useful framing such as 'weekly' booth rent and the city-level chair availability interpretation, but it does not meaningfully expand on individual parameter formats beyond what the schema already says.

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

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

The description names a specific verb and resource: 'Find barbershops and salons ranked by weekly booth rent' and states the axes (chairs available, Google rating, review count, hiring status). This clearly distinguishes it from a sibling like compare_barber_cosmetology_schools and signals it is a list-level comparison rather than a single-entry lookup.

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

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

The description provides useful usage context: it 'answers what a chair costs in a given city and which shops have one free,' implying a city-scoped search. However, it does not explicitly say when to prefer this tool over booth_rent_for_city or give any exclusions, so sibling differentiation is left to inference.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world mutation, so the safety profile is covered. The description adds genuinely new context beyond them: the code must come from verify_my_phone, the operation is one-time, and the result persists into later bookings.

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

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

Two short sentences, the action and its required input front-loaded, then the frequency/persistence note. 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?

There is no output schema and no annotations describing results, so the description should cover outcomes: what a success or failure looks like, whether the code expires, and the expected phone format. It covers the prerequisite and persistence model but leaves these 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 0%, so the description carries the burden, and it clarifies the code parameter with a format constraint (6 digits) and its source. The phone parameter is left undefined – no format, E.164, or whether it must match the number passed to verify_my_phone.

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 resource (confirm the client's mobile number) and identifies the exact input artifact (the 6-digit code from verify_my_phone). It is clearly separable from its sibling verify_my_phone, which initiates the flow rather than completing it.

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?

"Needed once; later bookings reuse it" tells the agent when this step is required and that it should not be repeated, and it points at the prerequisite tool verify_my_phone. It stops short of naming an explicit alternative or stating what to do if confirmation fails or the code expires.

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 only say non-read-only, open-world, non-idempotent. The description adds meaningful context beyond that: the tool returns Stripe's hosted setup page, bank and identity details are entered there and never in chat, and repeat invocation reveals connection/readiness state rather than blindly re-connecting. It doesn't explain what happens if the user has multiple accounts or how to disconnect.

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 leads with the action and keeps the payoff (money goes to the owner, no fee) and the security note in subordinate clauses. Slightly dense with nested em-dash clauses, but nothing 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 correctly covers the return shape (Stripe setup URL or connection readiness), which is the key thing an agent must relay. Remaining gaps are minor: no guidance on prerequisites, eligibility, or multi-account handling.

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

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

Zero parameters, so the baseline of 4 applies and there is no param semantics for the description to compensate for.

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: connecting the owner's OWN Stripe account so client payments route directly to them. The parenthetical about ShearQuery taking no per-booking fee and the emphasis on 'OWN' distinguishes this from generic payment-policy tools like set_booking_payments_and_policy.

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 (a pro who isn't yet connected needs this to accept cards), and the description does address the already-connected case by saying it will report readiness. But it never explicitly states when to reach for this versus siblings, nor any prerequisite such as being signed in as the account owner.

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

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

Annotations already mark it as a non-read-only, non-destructive send. The description adds substantial context beyond that: any signed-in member of any account type can use it, the message must be in the member's own words with what they tried and what happened, the user must see and approve the message before sending, and a human replies by email.

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

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

Front-loads the LAST RESORT constraint, then the alternative channel in parentheses, then eligibility, content requirements, approval flow, and outcome. Sentences are dense with useful information and none are 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?

No output schema exists, and the description covers the full lifecycle: who may use it, when to use it versus alternatives, what to include, the required pre-send approval, and how the reply arrives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 50%; the message parameter has a short schema description. The tool description adds meaningful content guidance for message (what they tried, what happened, which page or tool) and the pre-send confirmation process. The topic enum is self-explanatory but never mentioned, leaving one small 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, 'send a message', and resource, 'ShearQuery's team'. It explicitly names the sibling send_shearquery_feedback as the channel for bug reports and feature ideas, so the agent can tell the two apart without inspecting schemas.

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

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

Frames itself as the LAST RESORT after trying to help, names the alternative send_shearquery_feedback for bugs/ideas any time, and lists qualifying problems (account, billing, booking, unanswerable question). No ambiguity about when versus when not to use it.

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

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety picture is covered. The description adds the scope distinction versus crm_add_note but says nothing about auth requirements, whether notes are editable/deletable afterward, or what the write returns, so it contributes only modestly beyond 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 sentence that front-loads the action and resource, then uses the trailing parenthetical for sibling disambiguation. No filler; every clause earns its place.

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

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

For a simple two-parameter mutation with annotations present and no output schema, the description covers purpose and sibling routing adequately. It is thin on what a contact_id must reference and what happens on success/failure, which a fully complete definition would touch on.

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

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

Schema description coverage is 0% for both parameters. The description gives useful content guidance for 'note' via the examples, but 'contact_id' is left entirely undocumented and no format or length expectations are set for either field, so it only partially compensates for the coverage 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 ('Add') and resource ('note to a contact'), and explicitly disambiguates from the sibling crm_add_note by noting that one is for a deal. An agent can pick between the two without opening either schema.

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

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

The parenthetical 'crm_add_note is for a deal' routes the agent to the correct sibling, and the examples of note content ('what they said, what they want, when to follow up') clarify the intended usage context. It lacks explicit exclusions such as when not to log a note or prerequisites for the contact existing.

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 that this is a non-readonly, non-idempotent, non-destructive, closed-world write. The description adds useful context about what a note is meant to capture, but says nothing about permissions, persistence, or effects on the deal record — modest value beyond 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?

A single front-loaded sentence with no filler; the verb and resource lead and the examples trail. Efficient, though the examples are arguably content-flavor rather than necessary detail.

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

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

For a simple two-parameter note-creation tool with an existing safety profile in annotations and no output schema, the intent is adequately conveyed. The missing piece is any handling of the deal identifier and confirmation of what calling it changes.

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 both parameters rely on the description. It clarifies the intended content of 'note' (what was said, requests, follow-up timing) but gives no guidance on 'opportunity_id' format or how to obtain a valid deal id — a partial, not full, compensation for the coverage gap.

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

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

The description states a specific verb and resource: 'Add a note to a deal.' That is unambiguous and distinguishable from the other crm_* siblings (which operate on opportunities, pipelines, etc.), though it does not explicitly name or contrast with any sibling.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternatives are named. The content examples hint at intended scenarios (call notes, follow-ups) but the agent gets no routing logic.

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=false, so safety and locality are covered. The description adds what is returned (tags, channels, notes, deals, membership status), which is useful, but says nothing about permissions, error behavior when the id is unknown, or response shape guarantees.

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 leads with the action and key, then lists returned content. No filler, no repetition of the title.

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

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

With no output schema, the description usefully enumerates the return payload, which is the main gap it needs to fill for a single-record get. It stops short of documenting error/not-found behavior, but nothing essential to invoking the tool 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?

Only one parameter with 0% schema description coverage, so the description must carry the load. 'By id' identifies the parameter's role but adds no format, source, or validity details (e.g., where the id comes from, whether it's opaque).

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

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

The description names a specific verb ('Show'), resource ('one CRM contact'), and lookup key ('by id'), then enumerates the returned facets. It is clearly distinguishable from the plural list-style sibling crm_contacts.

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 'by id' (single-record lookup), but there is no explicit when-to-use guidance and no named alternative such as crm_contacts for listing or find_client for searching. An agent must infer routing from the name alone.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds the real behavioral payload: what true vs false mean per channel and the consent condition for re-enabling a channel. It does not cover permission requirements or whether unspecified channels are left untouched.

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

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

Two tight sentences, front-loaded with the action and the channel set, then the usage rule. Every clause carries information; nothing is 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 mutation tool with no output schema, the description supplies the action, the value semantics, and the consent guidance an agent needs. The remaining gap is whether only supplied channels change (partial update) and whether at least one channel must be provided.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does explain the boolean semantics for all six channel flags (email, sms/texts, call, whatsapp, gmb, fb) plus the opt-out intent behind false. It leaves contact_id and the partial-update question (what happens to channels not passed) unexplained.

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

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

States a specific verb and resource ('mark one contact reachable or Do Not Disturb') and enumerates the six channels, which is concrete enough that an agent can distinguish it from crm_save_contact or crm_tag_contacts. It does not explicitly name a sibling it should be used instead of, 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 an explicit trigger ('when someone unsubscribes or asks not to be texted — set that channel to false') and an explicit caution for the inverse ('setting true... only do that if they asked'). Both the when and the when-not are stated, which is exactly what routing guidance should do.

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=true, openWorldHint=false), so the description's added value is the return shape: a total count plus a page of contacts with ids, and the side effect that an unfiltered call also returns most-used tags. That is useful behavior not derivable from the schema, though rate limits or empty-result handling are not mentioned.

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: capability first, return shape second, usage guidance last. No filler, no repetition of the title, and the routing hint is placed where it will be read.

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 correctly compensates by describing the return (total + page of contacts with ids). For a six-parameter, all-optional read tool this is close to complete, though pagination defaults and behavior on empty results are left to the schema.

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

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

Schema coverage is 83%, so parameters are largely self-documenting; the description still adds framing by grouping the filters into text, tag, channel reachability, and membership/listing status, which helps an agent map intent to parameters. It does not add syntax details beyond what the schema already provides.

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 (search/filter) and resource (ShearQuery CRM contacts) plus the filterable dimensions (text, tag, reachability, member vs listing). It clearly separates this from mutation siblings like crm_save_contact or crm_delete_contacts by naming itself as the source of contact ids.

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 tells the agent when to reach for it: answering 'how many…' questions and obtaining contact ids for the other crm_ tools. It does not, however, distinguish itself from near-neighbors such as ghl_find_contacts, find_client, or find_prospects, which an agent could easily confuse with this one.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the return contents in detail: every inbound/outbound message with delivery status (sent, delivered, opened, bounced, not sent and why) plus email-capability of the contact.

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

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

Single front-loaded sentence led by the core action 'Show one conversation in full'. It is densely packed with em-dash asides, but every clause (lookup keys, message detail, email capability) adds information rather than repeating structured 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?

With no output schema, the description must convey what comes back, and it enumerates the message fields and delivery statuses plus email eligibility. It does not mention pagination or volume limits for long threads, a minor gap for a tool that 'shows everything'.

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 parameter meaning, and it does: conversation_id selects by conversation, contact_id selects that contact's whole thread. This explains the semantics and the choice between the two optional parameters beyond what the bare schema provides.

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 (Show) and resource (one conversation), with explicit scope 'in full'. This clearly distinguishes it from crm_inbox (a list) and crm_update_conversation (a mutation) without needing to open either schema.

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

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

It clarifies how to look up the conversation — by conversation_id or by contact_id for that contact's thread — which is useful invocation guidance. However, it never states when to prefer this tool over siblings like crm_inbox or crm_contact_channels, so alternative routing is left to inference.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely new behavior: the exact default stage set applied when stages is omitted and the 'Names must be unique' constraint that governs failure. It does not describe what happens on a uniqueness violation, but the added context is above baseline.

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 creates the tool first, then illustrates the stages argument and the default behavior. The example is somewhat long but earns its place by concretizing the expected array format.

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 ideally say what a successful call yields (e.g., the created pipeline object or its id), and it says nothing about the response. For a two-parameter creation tool the core input behavior is covered, but the return contract is a real 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 coverage is 50% (only stages is documented in the schema), so the description must carry more weight. It explains stage ordering ('in order', first-to-last via example) and the default fallback when stages is omitted, and it adds the uniqu</br>eness rule for name that the schema does not state.

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 ShearQuery pipeline') plus the stages concept, cleanly distinguishing it from crm_update_pipeline, crm_delete_pipeline, and crm_pipelines. It never names those siblings explicitly, so the differentiation relies on the verb rather than routing language.

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 does give conditional guidance on the stages parameter ('Leave stages out for a default...'), which is useful context. However, it offers no when-to-use/when-not guidance versus crm_update_pipeline or crm_pipelines, leaving the create-vs-modify decision to inference from the name.

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 readOnlyHint=false but omit destructiveHint, so the description carries real weight: it discloses irreversibility ('It can't be undone'), the collateral effect on notes, what survives (deals remain without a contact), and the loss of opt-out records. This is exactly the kind of destruction detail an agent needs before invoking.

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, front-loaded with the destructive action and its scope before the safety instruction and the alternative. No filler; every clause carries load-bearing 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 single-parameter mutation with no output schema, the description covers destruction semantics, side effects, irreversibility, a precondition, and an alternative tool. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0% and the only parameter (contact_ids) is undocumented in the schema itself. The description compensates by clarifying the key type ('by id') and an operational bound ('up to 500 contacts'), adding meaning beyond the bare array-of-strings schema.

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

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

States a specific verb and resource ('Permanently delete up to 500 contacts by id') and immediately clarifies scope ('with their notes'). It separates itself from the messaging sibling by naming crm_contact_channels, so an agent can distinguish it 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 crm_contact_channels for the related-but-different intent of stopping messaging, and states the required precondition ('say who will be deleted and get a clear yes first'). Both when-to-use and the alternative case are 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=false and idempotentHint=false, so the bar is lower. The description still adds valuable context beyond them: deletion is permanent and cascades to notes and history, and a confirmation step is required. It does not mention permission requirements or behavior on an invalid/not-found 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?

Three short sentences, front-loaded with the destructive action and its scope, then the alternative, then the confirmation requirement. 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 single-parameter destructive tool with no output schema, the description covers destruction scope, the safer alternative, and a confirmation gate. Only minor gaps remain (error/not-found behavior, permission needs).

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

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

Schema description coverage is 0% for the single required parameter, so the description could have compensated by clarifying what opportunity_id refers to. 'Delete one deal' implies the identifier targets a specific deal, and the param name is self-explanatory, but no format or sourcing guidance is added.

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

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

States a specific verb (permanently delete) and resource (one deal) plus the cascade scope (its notes and history). It also implicitly distinguishes itself from crm_move_opportunity by name, so an agent can tell the two apart without opening schemas.

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

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

Explicitly names the alternative tool (crm_move_opportunity) and the condition that selects it ('to close a deal without losing it'). It also adds a prerequisite gate: 'Confirm first.' Both when-to-use and when-not-to-use are covered.

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

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

Annotations already mark this as a non-read-only, non-idempotent mutation; the description adds the critical facts they don't carry: the deletion is permanent, irreversible, and cascades to all contained deals, plus the human-confirmation requirement.

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 zero filler; the destructive consequence is front-loaded before the procedural advice, which is the right ordering for a delete tool.

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 two-parameter destructive tool with no output schema, the description covers everything an agent needs: what is destroyed, that it is irreversible, which sibling supplies the deal count, and the confirmation gate.

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

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

Schema coverage is 100%, so the baseline is 3, but the description elevates confirm_name beyond its schema text by framing it as a deliberate safety guard (it 'must repeat the pipeline's exact name'), explaining the intent of the parameter rather than just its type.

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

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

States a specific verb (delete) and resource (pipeline) with explicit blast radius ('AND every deal in it'), which cleanly separates it from siblings like crm_delete_opportunity.

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

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

Gives a clear prerequisite workflow — call crm_pipelines to count the deals and obtain a verbal yes before invoking — and names the sibling used for that count. It does not state explicit when-not-to-use conditions, but the intended invocation context is unambiguous.

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=false, so the burden is light. The description still adds real behavioral context: ordering (newest first), grouping (one thread per contact), the fields surfaced (unread counts, open/closed, last message), and the presence of an email-sending connection flag.

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 paragraph that front-loads what is returned and follows with filtering and triggers. Every clause carries information, though the packing of five distinct facts into one paragraph slightly reduces scannability.

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, three-parameter listing tool with no output schema, the description usefully enumerates the returned data and the filtering/search surface, so an agent can call it correctly without guessing at 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 67%, and the description compensates for the undocumented 'query' parameter by specifying it searches 'name, email or text'. It also mirrors the view filter values, adding meaning beyond the bare enum. It does not explain the limit ceiling, which the schema already covers.

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 the person's ShearQuery conversations') and sharpens the scope to 'one thread per contact, every email with them', newest first. That is enough to separate it from a single-conversation reader, but it never names or contrasts with the sibling crm_conversation, 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 concrete invocation triggers ('any new messages?' or 'who replied?') and explains the available narrowing (unread, open/closed, search by name/email/text). No explicit when-not-to-use or named alternative, so it is clear context without routing.

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

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

Annotations already disclose the mutation/safety profile (readOnly=false, destructive=false, idempotent=false). The description adds two useful behavioral facts: the move is written to the deal's history, and a lost status pairs with lost_reason. It still omits reversibility, permission needs, and the fact that repeated calls are non-idempotent.

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

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

Two tightly packed sentences, zero filler, with the primary action and the status options front-loaded and the history side effect last.

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 5-parameter mutation tool with no output schema, the description covers the essential action, the status set, and the visible side effect. It leaves minor gaps such as whether stage/status can be supplied alone or what a partial update means, but nothing critical for correct invocation.

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

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

With 60% schema coverage, the schema documents stage, pipeline and lost_reason well. The description adds the conditional linkage 'lost (with lost_reason)' and clarifies that status and stage moves can be combined, which is genuine meaning beyond the field descriptions.

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

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

The description gives a specific verb+resource ('Move a deal to another stage... and/or set its status') and enumerates the exact status outcomes (won, lost, abandoned, open). It is clearly distinguishable from write siblings like crm_save_opportunity or crm_update_pipeline.

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 the verb and the 'and/or' framing, which tells the agent a move and a status change can be combined. However, it never states when to choose this over crm_save_opportunity or crm_opportunity, nor any preconditions, so the routing guidance is only inferable.

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=false, so the safety profile is covered. The description adds valuable context that it groups results by stage and returns ids intended for use by the other crm_ tools, but says nothing about pagination, ordering, or result size beyond the limit param.

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

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

Front-loads the core action and compresses modes, searchable fields, and filters into roughly two dense sentences with little waste. The parenthetical and em-dash clause make it slightly heavy but nothing is redundant.

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

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

For a read-only list tool with a fully described schema and no output schema, the description covers modes, filters, defaults, and what identifiers are returned. It could be more complete about result ordering or pagination, but an agent has enough 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 five parameters (limit, query, stage, status, pipeline) are already documented including defaults and the enum. The description restates the searchable fields and the default-open status but adds no syntax, format, or interaction detail beyond the schema, so the 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 and resource ('List deals (opportunities)') plus its scope: grouped by stage, either one pipeline's board or a cross-pipeline search. The plural/list nature clearly separates it from the singular crm_opportunity and from crm_pipelines.

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?

Describes two usage modes (single-pipeline board vs. cross-pipeline search) which implies when each applies, and the filter options are enumerated. However, it never names the sibling tools (crm_opportunity, crm_pipelines) or states when an agent should pick those instead, so the routing guidance is only implicit.

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=false, so safety is covered. The description adds real value by enumerating the returned payload — notes and history with 'when and from where' — which substitutes for the absent output schema. It does not cover failure modes (e.g., unknown id), keeping it short of a 5.

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

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

A single front-loaded sentence that leads with the verb and resource before enumerating fields. Every clause earns its place, especially the field list that stands in for a missing output schema.

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

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

With no output schema, the description correctly documents what comes back (pipeline/stage, value, status, contact, source, notes, history timestamps and origins), and annotations cover the read-only profile. Only the missing error/not-found behavior and id format keep it from being fully complete.

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

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

One parameter with 0% schema description coverage, so the description must carry the load. 'By id' ties the parameter to the deal's id, but no format or type guidance (string id vs numeric) is given, and the schema itself is bare. Minimal compensation for the coverage 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 (Show) and resource (one deal/opportunity) plus the fields it returns, and the singular 'one deal by id' implicitly contrasts with the plural crm_opportunities list tool. It stops short of explicitly naming the sibling it differs from, so an agent must infer the list-vs-single distinction.

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

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

The phrase 'by id' hints that an existing opportunity_id is a prerequisite, but there is no statement of when to use this versus crm_opportunities, crm_save_opportunity, or crm_move_opportunity, and no exclusion guidance. Usage is left entirely to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds genuine value by disclosing the return contents and the cross-tool naming convention ("pipelines and stages can be named in other tools by name"), which is behavior an agent needs and cannot infer from annotations.

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

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

Three sentences, all load-bearing: identity and return shape first, then call priority, then the naming convention. Front-loaded and waste-free.

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 what comes back, and it does so concretely (ordered stages, counts, value, won totals). Combined with the call-first guidance and the naming note, an agent has everything needed 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. It correctly does not pad with irrelevant parameter talk.

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 (List) and resource (the signed-in person's ShearQuery Pipelines), and enumerates the returned content: ordered stages, open deal counts, open value per stage, and won totals. This clearly separates it from crm_opportunities, crm_opportunity, and the pipeline-mutation 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?

"Call this first for any pipeline, deal, lead or sales question" gives explicit routing priority over the deal/opportunity siblings. It stops short of naming a specific alternative or stating when not to use it, but the sequencing guidance is unusually strong.

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?

Adds substantial behavior beyond the annotations: partial-update semantics ('only the fields given change'), the empty-string-clears convention, the replace-not-append semantics of tags, and the duplicate-email/phone refusal that returns the existing contact's id. These are exactly the non-obvious behaviors an agent would otherwise discover by trial and error.

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 dense sentences, front-loaded with the add/edit distinction, then the update semantics, then the tag caveat and the failure case. No filler, no restatement of the tool name.

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 upsert with no output schema, the description covers the critical decision points: mode selection, partial update, field clearing, tag replacement, and duplicate rejection. It omits what the call returns and whether any permission/account context is required, but nothing stated is misleading.

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 7% (14 params, one documented), so the description carries a heavy burden and does add real meaning: partial-update behavior applies to every field, empty string clears a value, and tags replaces rather than merges. It still says nothing about the many undeclared fields (source, company, name vs first_name/last_name, phone formatting), leaving most parameters semantically undefined.

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 pair and distinguishes the two operating modes ('Add a new CRM contact, or edit one by contact_id') in the first clause. It also names the sibling crm_tag_contacts for the tag-modification case, so an agent can separate it from related CRM writes without opening a 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 tag add/remove work to crm_tag_contacts, which is the main sibling-confusion risk for a contact-write tool. However, it gives no guidance on choosing between this and other CRM write siblings such as crm_update_pipeline-style helpers, and no prerequisites are mentioned.

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

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

Adds real behavior beyond the annotations: it discloses partial-update semantics ('only the fields given change') and the contact resolution logic (matched by email/phone, or created). Annotations already cover the write/destructive/idempotent profile, so this is a solid additive contribution.

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 create/edit mode and immediately followed by contact handling and the sibling alternative. 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 13-param write tool with no output schema, it covers the create/edit modes, the contact path, and the sibling alternative. It stops short of describing validation/defaults (e.g. new-deal stage default), which the schema partially covers.

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 54%, so it needs to pull weight; the description explains how contact_name/contact_email/contact_phone/company interact to match-or-create a contact, which the schema does not state. It leaves the remaining params (stage, value, source, status, lost_reason) mostly 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 (add/edit) and resource (deal/opportunity) and explicitly distinguishes the upsert behavior via opportunity_id. It also names the sibling it is NOT, crm_move_opportunity, so an agent can route without opening schemas.

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

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

Gives clear conditional guidance: create when opportunity_id is absent, edit when present, and route to crm_move_opportunity for pure moves or won/lost marking. No exclusion guidance for other CRM siblings (e.g. pipelines), but the core when-to-use is explicit.

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 only flag non-read-only, non-idempotent, open-world. The description goes well beyond that: the message 'can't be unsent,' who the sender address is and where replies land, what happens if no sender is configured, and the exact refusal conditions. This is the behavioral context an agent needs before a mutation.

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

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

The core action and targeting rule are front-loaded, and every sentence carries distinct information (sender routing, refusal rules, confirmation requirement). It is dense and slightly long, but nothing is redundant 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?

With no output schema, the description still covers the error path ('it says where to connect Gmail') and the irreversible-mutation caveat. For a 5-parameter, no-output-schema send tool, an agent has what it needs 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 coverage is only 40%, and the description compensates by explaining contact_id (start or continue a thread), conversation_id (target an existing thread), and subject's optional/reply-reuse behavior with 'Re:'. channel and body are largely left to the schema, so it is strong but not fully compensatory.

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 with cardinality and scope: 'Send one email to one contact, in their conversation thread.' That distinguishes it from sibling senders (ghl_send_email, ghl_send_sms) and from crm_* read/update tools without opening a 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 between the two entry keys ('by conversation_id, or contact_id to start or continue that contact's thread') and names the alternative channel with its status ('channel is email; texting isn't connected yet'). It also states refusal conditions (no email, do-not-contact) and a prerequisite workflow (read the message back and get the owner's OK first).

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 (not read-only, not destructive, not idempotent), so the bar is lower. The description adds real behavioral value beyond that: 'other tags are left alone' discloses partial-update semantics, 'tags are lowercase' discloses a normalization rule, and 'up to 500' discloses a batch limit. It does not address idempotency despite the annotation, but coverage is strong overall.

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 compact sentences, front-loaded with the core action and scope, then the id source, then the behavioral caveats. No filler; every clause earns its place.

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

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

For a batch mutation with no output schema, the description covers the batch limit, tag normalization, and non-destructive merge behavior. However, it omits what the response contains, what happens on partial failure or unknown contact ids, and whether re-adding an existing tag errors — meaningful gaps for this tool.

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

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

Schema description coverage is 0%, so the description carries the burden. It clarifies that add and remove are both optional ('and/or'), that contact_ids come from crm_contacts, and that tags are lowercase. This adds meaningful semantics but leaves the exact format of ids and tag strings, and per-parameter details, undocumented.

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

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

States a specific verb (add/remove tags) and resource (contacts) with scope (up to 500 at once), clearly distinguishing it from sibling mutation tools like crm_save_contact or crm_delete_contacts. An agent can tell exactly what this does 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?

Points the agent to crm_contacts as the source for ids, which is useful routing, but provides no explicit when-to-use/when-not guidance or alternatives (e.g., vs crm_save_contact). Usage is implied rather than stated.

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

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

Annotations already declare this is a non-destructive, idempotent mutation. The description adds a genuinely useful behavioral trait beyond them: a closed conversation auto-reopens when the contact writes again, which prevents redundant reopen calls. It stops short of disclosing permissions or error behavior.

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

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

Two short sentences, front-loaded with the primary action and followed by the one behavioral caveat. No filler, every clause earns its place.

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

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

For a three-param mutation with no output schema and covering annotations, the description supplies the state semantics and the auto-reopen nuance an agent needs. Minor omission is that it never states conversation_id is required or what the call returns.

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 carries the burden, and it does map both meaningful params conceptually: the boolean as read/unread and the status enum as closed/open. The required conversation_id is left implicit, which is the only 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 (mark) and resource (conversation) plus the exact state axes affected: read/unread and closed/open. The purpose is unambiguous and clearly distinct from read-oriented siblings like crm_conversation and crm_inbox.

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 the description of the two state toggles, but there is no explicit when-to-use/when-not guidance or reference to alternative tools for conversation handling. It does hint that reopening is unnecessary, but does not frame this as 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 only flag non-read-only, non-idempotent, closed-world; the description adds the destructive specifics that matter: stages left out are removed, their open deals move to the first stage, and named stages retain their deals. The 'Old name => New name' rename path and the advice to disclose deal movement before calling are exactly the behavioral context an agent needs before a mutating call.

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

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

Front-loads the two operations, then the consequences, then the prerequisite—every sentence carries information. Sentences are long and multi-clause, which slightly taxes parsing, but nothing is redundant.

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

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

For a non-idempotent mutation with no output schema, the description covers consequences, rename semantics, stage removal, and a pre-call check. It omits permission/auth requirements and any hint about result confirmation, which are minor remaining 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 67% and the description meaningfully extends it: 'stages' is the FULL ordered list, 'new_name' is the rename target, and the rename syntax explains how a stage keeps its deals. The 'pipeline' parameter's id-vs-name distinction is left to the schema, so it is not a complete semantic layer.

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

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

Specific verb+resource ('Rename a pipeline and/or replace its stages') that clearly distinguishes it from siblings like crm_create_pipeline, crm_delete_pipeline, and crm_pipelines. The scope (rename and/or restructure) is stated immediately in the first clause.

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

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

Gives a concrete prerequisite ('Get the current stages from crm_pipelines first') and an operating instruction ('tell the person which deals will move before calling'). It does not explicitly route to alternatives such as crm_create_pipeline for new pipelines, so it falls just short of a full when/when-not map.

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 destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is partly covered. The description adds a genuinely useful fact beyond the annotations — 'Nothing on Google changes' — clarifying the discard is confined to the local draft and has no live-profile side effect. It omits whether the discarded draft is irrecoverable, which is the main remaining behavioral unknown.

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 zero filler; the action is front-loaded and the scope clarification follows immediately. Nothing to trim.

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 tool with full schema coverage and annotations, the description is nearly sufficient: it says what happens and that nothing changes on Google. It would be complete with a note on whether discarding is reversible and how it differs from undo_change.

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% for the single change_id parameter, and the schema already explains it comes from a propose_ tool or my_changes. The description adds nothing further about the parameter, so baseline 3 applies.

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

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

States a specific verb ('throw away') and resource ('a pending draft'), and clarifies the draft is one the owner does not want. It is distinguishable from sibling propose_*/publish_change tools, but it never contrasts itself with undo_change, the closest sibling and the most likely source of confusion.

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 'the owner does not want' suggests discard applies to unwanted pending drafts, but there is no explicit when-to-use statement, no prerequisites, and no pointer to undo_change for changes that were already published.

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=false, so safety is covered. The description usefully adds that search is scoped to the owner's calendar and that results include notes and recent appointments, but it omits ambiguous-match handling, what 'recent' means, and any result 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 filler, leading with the action and search keys. Slightly dense 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 one-parameter read tool with no output schema, the description covers scope, keys, and return contents, and annotations cover the safety profile. Minor gap around multiple-match behavior, but adequate overall.

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

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

Schema coverage is 0% and there is one parameter, so the description must carry the burden. It adds real meaning by stating the query accepts a name or phone number, but gives no format detail (e.g. digit-only vs formatted phone), so it partially compensates rather than fully.

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 (Find), resource (client), scope (on the owner's calendar), lookup keys (name or phone number), and the return content (notes and recent appointments). No sibling tool performs client lookup, so there is nothing to confuse it with.

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 the lookup framing, but there is no explicit when-to-use guidance and no alternatives are named. Nothing tells the agent when this is the right call versus, say, browsing appointments directly.

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 useful behavioral context by explaining that results include each category's id and are ranked with the most relevant for this trade first, which goes beyond 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?

Three short sentences are front-loaded with purpose, then output shape, then usage guidance. The examples are compact and every sentence contributes necessary information without repetition.

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

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

For a simple one-parameter read tool with annotations covering safety and openness, the description supplies the essential purpose, output format, and follow-up workflow. No output schema is present, but the description explains what the tool returns, so an agent has enough 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?

Schema coverage is 100%, so the single query parameter is already documented as "Words to search for." The description supplements this with concrete example queries, adding semantic guidance beyond the schema 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?

The description states a specific verb and resource: search Google's list of business categories, with examples such as "hair salon" and "barber". It also clarifies the output (category ids ranked by relevance) and distinguishes this lookup tool from the sibling propose_categories, which consumes those ids.

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 explicitly says to use the returned ids with propose_categories, giving a clear workflow context. However, it does not state when not to use this tool or mention alternative lookup paths, so it falls short of the full when/when-not/alternatives standard.

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 only declare readOnlyHint and openWorldHint, so the description carries the burden of explaining behavior and does add real context: it accounts for working hours, existing bookings, clean-up time and time off. The minimum-notice effect of for_client is also disclosed. It stops short of explaining result size/ordering beyond the schema's limit default.

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, front-loaded with the core action, then behavioral coverage, then the one non-obvious parameter. No filler or repetition of the name.

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?

There is no output schema, but 'find open start times' plus the enumerated 'when' values and the 20-item limit default give an agent enough to call this correctly. The only gap, explicit non-overlap with pro_open_times, is a sibling-routing nuance rather than a calling blocker.

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% (for_client has no description), and the description compensates by explaining that for_client applies the minimum-notice rule clients get, and by enumerating the accepted 'when' forms beyond the schema's bare 'Default week'. It adds genuine meaning over the structured fields.

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 open start times for a service on the owner's calendar.' An agent knows exactly what the tool returns (open slots). However, it never differentiates itself from the sibling pro_open_times, which looks like the same capability viewed from another side, so routing between the two is left to inference.

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 accepted values for 'when' ('today', 'tomorrow', 'week', a date or range) and the for_client scenario give implicit usage context, and the minimum-notice note hints at the client-facing case. But there is no explicit statement of when to use this versus pro_open_times or my_calendar, so usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the data comes from ShearQuery's own directory (not a live external scrape), the call is free, results carry a data-as-of date, and email addresses are never returned. Ranking criteria are disclosed, though it doesn't explain result freshness limits or how stale data can get.

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?

Key information — the agency gate, the target resource, the ranking basis — is front-loaded in the first sentence, and the trailing sentence usefully summarizes the returned fields. The middle clause is a long parenthetical stack that a reader must unpack, so it is efficient but not maximally crisp.

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

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

For a tool with no output schema, five parameters and read-only annotations, the description covers everything an agent needs: eligibility, search inputs, ranking logic, the shape of each result (id, phone, website, links, date), the follow-up tools for that id, and the explicit absence of emails.

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 80%, so the baseline is 3, and the description genuinely adds meaning: it explains what each 'needs' signal means (few Google reviews for their city, a low rating, stalled reviews, no website, plus open booths) and that they are combined cumulatively, matching the schema's 'ALL of these' semantics. The required business_type and the city/ZIP pairing are also made explicit.

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 plus a precisely scoped resource: businesses of four named types in a city/ZIP that are 'not on ShearQuery yet,' ranked by need. This clearly separates it from find_client, find_pros_to_book and my_prospects, which operate on existing relationships rather than net-new leads.

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 'For an APPROVED agency' gate gives an explicit precondition, and the description names follow-up siblings (prospect_details, save_prospect) for the id it returns. It stops short of saying when *not* to use it (e.g. to review already-saved leads — that's my_prospects), so it is clear but not exclusion-complete.

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

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

With annotations only covering readOnlyHint and openWorldHint, the description adds genuine behavioral context: auth requirements for viewing vs booking, and everything the response contains (pro id, workplace, services with length and price, booking/payment/cancellation policy). No contradiction with readOnlyHint=true.

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

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

Front-loaded with the core action and lookup keys, and every sentence carries information (usage keys, auth notes, return shape). It is a dense single paragraph, but nothing reads as 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?

No output schema exists, so the description supplies the return fields itself, and it covers auth prerequisites and the empty-query mode. For a one-parameter read tool with minimal annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 0% and the single 'query' parameter is undocumented in the schema, so the description carries the full burden — and does: it names the accepted forms (name, business name, booking handle), gives a concrete format example (marcus-cuts), and explains the empty-string list behavior.

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 (find) and resource (barbers, stylists, shops that take real bookings on ShearQuery), and enumerates the lookup keys (name, business name, booking handle) plus the empty-query list mode. This clearly separates it from booking-oriented siblings like book_with_pro and cancel_appointment.

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

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

Gives concrete context: no account needed to search, client must sign in to actually book, and an explicit fallback ('leave the search empty to list them'). It never names a specific alternative tool, so it falls short of the explicit when-not/alternative framing 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 safety is covered. The description goes beyond them by enumerating the returned fields (id, email, phone, tags, Do Not Disturb status) and stating the agency-scoped precondition, which is genuinely useful context for planning a call.

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 scope and precondition before the usage advice. The trailing clause about checking with the agency is slightly conversational but still earns its place as a verification step.

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 tool with no output schema, the description supplies the return shape and the precondition, which is what an agent needs to call it correctly. Only pagination/limit behavior and disambiguation from other find_* siblings are left 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 description coverage is 100%, so both query and limit are already documented in the schema, including the default of 10 and the maximum of 25. The description repeats the searchable fields but adds no syntax, matching behavior, or edge-case guidance beyond the schema, 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 a specific verb (search), a specific resource (its own GoHighLevel contacts), the searchable fields (name, email, phone, company), and the precondition (agency with GoHighLevel connected). It also distinguishes itself from the messaging siblings ghl_send_sms and ghl_send_email by positioning itself as the id-lookup step that precedes 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?

It gives a clear when-to-use: obtain the correct contact id before calling ghl_send_sms or ghl_send_email, and confirm the identity with the agency. It does not, however, distinguish itself from other lookup-style siblings such as find_client or find_prospects, so the agent gets routing guidance but no exclusions.

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

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

Annotations only flag readOnlyHint=false, openWorldHint=true, idempotentHint=false; the description adds far more: the message cannot be unsent, it goes out from the agency's own domain, new email addresses auto-create a contact, blank lines become paragraphs, and a 100-message-per-day rate limit. These are real operational constraints an agent cannot infer from 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?

A single dense paragraph, but every sentence carries a distinct constraint (routing method, body format, approval workflow, consent rules, rate cap) and the most decision-relevant information — what it sends, to whom, from where — is front-loaded. No filler or restatement of the tool name.

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 non-idempotent, outward-facing mutation tool with no output schema, the description covers safety, consent, identity resolution and limits thoroughly. The only gap is that it never indicates what the call returns on success (confirmation, message id, failure mode), which an agent would otherwise have 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 coverage is 80%, so the baseline is 3, and the description genuinely adds above that: contact_id is flagged as preferred, email is the fallback path and will create a new contact if unknown, and name only applies during that creation. It complements rather than repeats the schema, though it doesn't clarify the subject/body formatting beyond the paragraph rule.

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+resource with scope: 'send one email from its own GoHighLevel ... to one contact'. It also distinguishes itself from siblings by naming the contact_id source (ghl_find_contacts) and implicitly contrasting with the channel-specific ghl_send_sms. An agent can identify exactly what this does and what it does not.

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?

Explicit conditions for use are given: agency accounts with GoHighLevel connected, one person per call, contact_id preferred or email address as fallback. It names the prerequisite sibling (ghl_find_contacts), the when-not rules (never message Do Not Disturb contacts, only consenting recipients), and a required pre-call workflow (read the message back and get approval).

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 only say non-readOnly, non-idempotent, openWorld. The description adds substantial context beyond that: the message is real and cannot be unsent, a read-back confirmation step is required, consent/DND constraints apply, and there is a 100-message-per-day cap.

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

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

Front-loads the actor, action and scope, then adds constraints in a single dense paragraph. Slightly long and dash-heavy, but nearly every clause carries operational weight; minor trimming would help.

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 irreversible mutation with no output schema, the description covers the essentials: preconditions, addressing options, confirmation workflow, consent rules, and rate limits. An agent has enough to invoke it safely.

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% and the schema descriptions already state 'Preferred' for contact_id and 'used only if a new contact has to be created' for name. The description largely repeats this, adding no syntax or format detail beyond 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 (send one SMS from the agency's GoHighLevel to one contact) with clear scope limits ('one person per call'). It implicitly distinguishes itself from ghl_send_email by channel and routes the agent to ghl_find_contacts for obtaining a contact_id.

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?

Explicit preconditions ('For an AGENCY with GoHighLevel connected'), two clear addressing modes (contact_id preferred, or phone which creates a contact), and named hard exclusions (never message DND contacts, only consented people).

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=false, so the safety profile is covered. The description adds genuinely useful behavior: the view spans today plus a backlog of unposted earlier comments and reports 7-day fullness against a 5-per-day cap, which hints at a queue quota. It stops short of stating pagination, ordering, or what 'draft' means operationally.

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 a single sentence, but it opens with an audience preamble ('For the ShearQuery team') rather than the function, and then chains three loosely joined clauses with dashes. The information is there but not front-loaded or cleanly structured.

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

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

With no output schema, the description does the work of telling the agent what comes back: per-comment post links and drafts, a backlog section, and a forward-looking capacity count. That is sufficient for a single-optional-param read tool, though ordering and pagination remain unstated.

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

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

Only one parameter with 100% schema description coverage ('YYYY-MM-DD (Eastern). Default today.'). The description repeats the default-today behavior but adds no format, timezone, or boundary semantics beyond the schema, so the 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?

Names the resource ('the comment calendar') and enumerates what it contains: one day's comments with post link and draft, earlier unposted comments, and next-7-day capacity. The verb is implicit (view/list) rather than stated, and the 'For the ShearQuery team' framing is audience-scoped rather than functional, but an agent can still tell this apart from update_ig_comment or queue_ig_comment.

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 'default today' note implies a routine check-in use, but there is no explicit when-to-use, no condition for passing a date, and no routing against siblings like ig_engagement_targets, my_instagram_posts, or shearquery_instagram_activity. The agent must infer 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 only declare readOnlyHint=true and openWorldHint=false. The description adds real behavior beyond that: the 7-day recency window, returning shops ranked first, and the fact that each row carries the last-engaged timestamp. It omits result-count/pagination behavior, though limit is capped at 100 in 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?

Purpose and selection rule are front-loaded, then filters, then the next-step chain — a clean ordering. The only slightly expendable clause is the parenthetical justification for returning-first ordering.

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 return-shape burden and does so reasonably (ordering, last-engagement field). It stops short of describing result volume or how to page through a large city list.

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 both enums (mode, type) are already documented there, including mode's 'all' default. The description names the same three filters but adds no syntax or format detail beyond the schema, and never mentions the limit parameter. 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?

Names a precise resource (directory businesses with matched Instagram handles) and a precise selection rule (DUE — never engaged, or not engaged within 7 days either side of today). An agent can distinguish this targeting tool from ig_comment_queue or my_instagram_posts without opening any 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?

Clearly frames the use case and chains the follow-up workflow: fetch posts, pick a recent post, then queue_ig_comment. It does not, however, state when NOT to use it or how it relates to ig_comment_queue/my_prospects as alternatives.

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

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

Annotations only declare the generic safety profile (readOnly=false, openWorld=true, destructive=false), leaving rate/policy behavior unstated. The description fills that gap richly: a real email is sent naming the agency, the business is credited to the agency with commission on paid plans, and explicit limits of 50/day and one invite per address per week.

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

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

Three sentences, front-loaded with eligibility and the core action, then consequences, then the operational caveat and limits. No filler; every clause carries decision-relevant 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?

No output schema exists, but the description covers prerequisites, side effects (real email, attribution, commission), verification step, and hard limits. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by framing the email and business name as values that must be verified with the agency before calling, and clarifies business_name's role in the greeting, which the schema states only tersely.

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

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

Specific verb (email an invite) plus resource (client: barber, stylist, shop, salon, school) and the join→attribution→commission outcome. An agent can distinguish this from siblings like propose_booking_link or find_prospects without opening any 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?

States the precondition clearly ('For an APPROVED agency') and adds a procedural gate ('confirm the address and business name with the agency before calling'). It does not name a rival tool to use instead, but the context is unambiguous for when this applies.

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 only cover the generic safety profile (readOnly=false, destructive=false, idempotent=false), so the description carries the rest well: it preserves length and clean-up time, refuses overlaps, confirms before scheduling outside working hours, and does not text the client. These are concrete side effects and failure modes, though auth/permission requirements and the confirmation flow wording ('asks' whom) remain unspecified.

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

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

A single front-loaded sentence carrying the action, the id source, duration preservation, conflict handling, working-hours confirmation, and the no-notification side effect. 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 non-idempotent mutation with no output schema and 0% parameter coverage, the description supplies the important behavioral facts (preserves duration, refuses overlaps, confirmation outside hours, no client text). Missing only return/error surface detail and parameter format conventions.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain id ('from my_schedule') and indirectly the allow_outside_hours boolean ('asks first outside working hours'), but leaves date/time formats and the exact meaning of allow_outside_hours (override vs prompt) undocumented.

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

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

States a specific verb and resource ('Move an appointment') plus the scope (to a new date and time) and points to the source of the id ('id from my_schedule'). An agent can distinguish this from book_appointment, cancel_appointment, and update_appointment_status without opening any 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?

Gives useful context ('id from my_schedule') and a conditional behavior ('asks first outside working hours'), but never names an alternative operation or states when this should be preferred over cancel+rebook or update_appointment_status. Usage is implied 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=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the account is agency-scoped, sample clients exist and are labeled, and gaps in the data are surfaced rather than hidden. No auth or rate-limit details, but none are needed for a read-only detail fetch.

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

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

A single sentence that front-loads the account scope before enumerating contents, with zero filler. It is dense and list-like, but every clause names a distinct returned field or action, so the length is earned.

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

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

With no output schema and no parameters, the description carries the burden of describing the response and does so by enumerating the returned data categories, including the unexpected sample clients. It also closes the loop to update_my_agency_details, leaving no major gap for a read-only zero-arg tool.

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

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

Zero parameters, so schema semantics are not at issue and the baseline is 4. The description correctly signals that no input is required by scoping everything to 'an AGENCY account' implicitly derived from the caller's identity.

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 the resource (an agency account) and enumerates what it returns: details, partner approval status, referral link/code, credited businesses and their setup stage, sample clients, and sent invites. This clearly differentiates it from the sibling my_shearquery_account and pairs it with update_my_agency_details. It lacks an explicit retrieval verb, but the scope 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?

Tells the agent what to do with the result: missing details are listed so you can ask the user and persist them via update_my_agency_details, naming the sibling tool. It does not state when to prefer this over my_shearquery_account, which is the one plausible alternative for account lookups.

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?

Adds substantial context beyond annotations: enumerates what the agency can see (connections, stuck drafts, failures, plan, audit score) and a privacy boundary ('never their customers' details'). It also imposes a consent requirement, which is valuable behavioral guidance. Annotations already cover safety (non-destructive, idempotent), but the description reveals data-sharing scope and authorization needs.

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?

Efficiently packed into two sentences with no filler. Front-loads the target user context rather than the core action, but remains readable and appropriately sized.

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?

Covers target user, purpose, data scope, privacy, parameter usage, and consent rule. No output schema exists, so return values need no explanation. Minor gap: it does not clarify behavior when no agency is connected.

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%, already explaining share: true/false and that leaving it out means just checking. The description repeats true/false but adds no new parameter semantics; the consent rule is usage guidance rather than parameter 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 specific verb and resource: checking or switching whether an agency can see the business owner's account health. Clearly distinguishes from sibling tools like my_agency (agency details) by focusing on access visibility. Also identifies the target user (business owner brought by an agency).

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

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

Provides clear context on who this is for and an explicit consent guideline: 'Only switch it on when the owner asks to.' However, it does not name alternative tools or explain when to use this versus my_agency or update_my_agency_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?

With annotations denying readOnly but asserting idempotent and non-destructive, the description adds meaningful context: it explains the two outcomes (sign-up link vs Stripe page) and crucially directs the agent never to collect bank or tax details in chat. This adds security/privacy behavior not present in 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?

Front-loaded with the controlling condition ('For an APPROVED agency') and then the behavior and the safety constraint. It is a dense single sentence but every clause earns its place; 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?

No output schema exists, so the description carries the burden, and it does explain what the agent gets back (setup status plus a link, with the link type depending on completion). Complete enough to invoke correctly, though it does not detail error or non-approved-agency cases.

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

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

The tool takes no parameters and has 100% schema coverage, so there is nothing for the description to disambiguate. Baseline of 4 applies for a zero-parameter tool.

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 ('Set up or open agency payouts') and clearly defines scope: determines whether an APPROVED agency's commission payouts are set up with Stripe and returns a link to open. This distinguishes it from sibling account tools like my_agency, my_agency_access, and update_my_agency_details.

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

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

Provides a clear precondition ('For an APPROVED agency') that tells the agent when the tool applies. It does not name alternative tools or explicitly state exclusions, so it falls short of full when/when-not routing, but the context is clear.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the approval precondition, the concrete slot times (9 AM / 2 PM / 7 PM ET), and the fact that content is Reels of ShearQuery's videos on the agency's own Instagram rather than arbitrary uploads. It stops short of describing ordering guarantees or limits on the returned queue.

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

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

Two sentences, zero filler, with the gating condition ('For an APPROVED AGENCY') front-loaded before the enumerated payload. Every clause earns its place by naming a distinct piece of returned data.

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 conveying the return shape and does so well by enumerating connection, schedule with slot times, ordered post line, and posted/failed status. It is complete enough to call correctly; only the queue's size or pagination behavior is left unstated.

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

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

The tool takes zero parameters and the schema is empty, so there are no parameter semantics to document and the baseline of 4 applies. Nothing in the description misleads about inputs.

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 resource (the agency's Instagram connection, schedule, post queue, and results) and scopes it to an APPROVED AGENCY, which separates it from personal-account siblings like my_instagram_posts and my_posts. It is a status/read view rather than a clear verb-led action, so it is clear but not maximally sharp.

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

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

The phrase 'For an APPROVED AGENCY' supplies a real precondition (the agency must be approved), which is genuine usage context. However, it never states when to call this versus the obvious alternatives that mutate the same domain (queue_agency_post, update_agency_post, set_agency_publishing_schedule), leaving the read-vs-write routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value: the return payload is itemized as id + current answer, and it warns the agent not to infer truth values. It doesn't discuss rate limits or staleness, so not a 5.

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

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

Two sentences, front-loaded with the resource and examples, followed by the critical owner-verification instruction and the handoff to propose_attributes. 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?

No output schema exists, but the description compensates by describing the returned fields (id and current answer) and the downstream usage. For a zero-parameter read tool with clear annotations, nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly signals a no-argument call and instead explains what the values returned mean.

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 (List) and resource (attributes Google offers for this business's category), with concrete examples (wheelchair accessibility, walk-ins, Wi-Fi). It is clearly distinguishable from siblings like propose_attributes and my_service_options.

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 workflow guidance — 'Only the owner knows which are true: ask them, never assume' — and routes the agent onward: 'Use the ids with propose_attributes.' The read-then-propose sequence is fully 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=false, so safety is covered. The description goes well beyond that by disclosing the semantics of the reported data: replies are auto-published in the owner's voice, posts are sent a day ahead for cancellation, 4-5 star reviews are auto-replied while sub-4-star reviews never are, and published output is reversible via undo_change. It does not describe the return shape or freshness, which keeps this from a 5.

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

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

A single dense paragraph that front-loads the core purpose ('what it does and what it has done') and then enumerates the behaviors. Detail about a-day-ahead cancellation is arguably more product lore than tool instruction, but it is compact and 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 zero-parameter read tool with no output schema, the description gives an agent enough to understand what comes back and what it signifies. The remaining gap is routing: it should point at update_autopilot_settings for configuration changes, since that sibling exists and the description explicitly mentions 'settings'.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The schema object is empty and fully described by construction, and 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 concretely what the tool surfaces: what Autopilot is configured to do for the owner and what it has actually done (replies, posts, reports, digests). That is far more specific than the title alone. However, it never names the obvious sibling update_autopilot_settings, so the boundary between reading settings here and changing them there is left to inference.

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 content implies a read/view call, and the closing sentence routes the agent to undo_change and my_changes for undoing published items. But there is no explicit when-to-use statement, no guidance on using this versus update_autopilot_settings to modify settings, and no exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the 30-day lookback window, the inclusion of website and pre-signup bookings, and the gating condition that the client's mobile number must be 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?

Two dense sentences with no filler. The core scope comes first, then the id-usefulness and eligibility caveat, which is the right ordering.

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 parameters and no output schema, the description covers eligibility, scope, and that ids are returned. It does not sketch the shape of the returned list beyond ids, which is a minor gap for a tool with no output schema, but nothing critical is missing 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The implicit scoping to the calling client is stated clearly ('this client').

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 (List) and resource (appointments the client booked with pros), plus a precise temporal scope (upcoming and the last 30 days). The client-side framing distinguishes it from pro-side siblings like my_calendar and my_schedule without needing to name them.

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

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

The mention of ids 'for reschedule_my_booking and cancel_my_booking' effectively routes the agent to this tool as the lookup step before those mutations. It does not state explicit exclusions or name a read-only alternative, but the context of use is clear.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, and the description's "Show" is consistent. Beyond that, it lists returned fields but adds no auth, rate, or side-effect context; with annotations covering safety, this is adequate.

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

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

Two sentences, front-loaded with the core purpose and a compact list of covered fields. The final routing sentence is short and purposeful 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?

With no output schema, the description carries the burden of explaining returns and does so thoroughly: time zone, weekly hours, services with length and price, booking lead windows, and upcoming time off. It also gives the first-call instruction, making it complete for a no-param read-only summary tool.

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

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

The tool takes zero parameters, so parameter semantics are not a concern. Baseline for 0 params is 4, and the description does not need to document parameter meanings.

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 ("Show") and resource ("owner's ShearQuery appointment calendar... set up") and enumerates the setup data returned. This distinguishes it from appointment-list siblings like my_schedule and my_bookings.

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?

"Call this first for any calendar question" gives clear usage context and a routing instruction. It does not, however, name when-not-to-use cases or alternatives among the many calendar-related siblings.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about the change categories returned and the fact that each change has an id, which matters for follow-up actions. It does not describe pagination or ordering beyond 'recent'.

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

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

The description is two sentences with no filler. It front-loads what the tool lists and follows with the concrete use case, making it easy to scan.

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

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

For a simple list tool, the description covers the main content and the reason to call it. Annotations cover the read-only nature and the schema covers the limit parameter. Since there is no output schema, the description could say more about the return structure beyond ids, but it is largely sufficient 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?

The input schema has 100% description coverage for the single limit parameter, so the schema already carries the parameter meaning. The description adds no additional semantics about the limit. A baseline 3 is appropriate when schema coverage is complete and the description is silent on parameters.

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

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

The description uses a specific verb ('List') and resource ('recent changes to the owner's Google profile'), and it enumerates the relevant change types: pending drafts, published changes, failures and undos. The use-case phrasing distinguishes it from action siblings like publish_change, discard_change and undo_change.

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 clearly states when to use the tool: to find a draft to publish or discard, or a published change to undo. That gives strong context, but it does not explicitly name the action tools as alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine value beyond that: it discloses what happens when the account is not connected (returns the connection page) and imposes an auth-handling rule about never requesting a token in chat.

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

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

Front-loaded with the audience and subject, with the parenthetical explaining the downstream benefit and the closing sentence handling the failure path. Slightly overlong as one run-on sentence but no sentence 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 steps in to enumerate return content (status, sub-account, last messages, or the connect page), which is what an agent needs here. It is complete for a zero-parameter status tool.

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

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

The tool takes zero parameters and the empty schema is 100% covered, so the baseline of 4 applies; there is nothing for the description to clarify about argument semantics.

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

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

The description names the specific resource (the agency's GoHighLevel sub-account connection to ShearQuery) and spells out exactly what it reports: connection status, which sub-account, and last messages sent. This clearly separates it from write-oriented siblings like ghl_send_sms and ghl_send_email, though it never explicitly contrasts itself with them.

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

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

The 'For an AGENCY:' scoping and the instruction 'Never ask the agency to paste a GoHighLevel token into the chat' imply when this tool applies and how to handle the negative case, but no alternative tool is named and no explicit when-not condition 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 declare readOnlyHint=true and openWorldHint=true. The description adds that it returns the profile exactly as Google has it now and lists fields (name, phone, hours, categories with ids, services, booking links), which usefully scopes the return. It does not cover auth, rate limits, or response format, so a 4 is appropriate.

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

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

Two sentences: the first front-loads the action and field list, the second gives the call context. Every field named is relevant to the live profile read, and there is no filler or redundancy.

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

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

No output schema exists, so the field enumeration is necessary and sufficient to understand what is returned. Annotations cover the safety profile and open-world nature, and the description adds the usage trigger. Nothing needed to call this correctly is missing.

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

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

The tool has 0 parameters, so the schema provides no parameter descriptions. Per the rubric, a no-parameter tool receives a baseline of 4; the description does not need to add parameter meaning.

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