Andrii Co. Notary & Apostille Assistant

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

The description adds important contextual info: appointments are requests pending notary confirmation, never guaranteed; returns a Pending reference; fails if not signed in. These are useful beyond the annotations, which already set readOnlyHint=false and destructiveHint=false. However, the description doesn't warn about potential side effects beyond creating a pending request, and doesn't explain what happens if confirmation fails or what 'fails if not signed in' entails (error type, partial state). No contradiction with annotations.

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

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

The description is compact and front-loaded with the most important decision rule (prefer over request_booking when signed in), followed by parameter highlights and return/error behavior. Every sentence 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?

Given the output schema exists and annotations declare openWorldHint=true, the description covers the key behavioral context: pending status, signed-in requirement, guest fallback, and parameter specifics. It could mention what happens on failure in more detail, but for selecting and invoking the tool correctly, it's nearly complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds usage nuance: scheduled_at should be 'a slot's startUnix from search_availability, omitted for a call-me request', and address is for mobile. This adds value, but it largely paraphrases the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Schedule an appointment'), ties it to the signed-in customer's account, and differentiates it from request_booking. It also lists the key parameters (service, scheduled_at, address, notes, document_count) and the return type, making the tool's purpose unmistakable.

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

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

The description explicitly instructs to prefer this tool over request_booking when the customer is signed in, and directs guests to request_booking. It also notes that only a booking on the customer's own account can later be listed, rescheduled, or cancelled, providing clear decision 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 signal destructive behavior, and the description adds concrete constraints: it only succeeds on Pending/Scheduled bookings, fails when the booking is not yours or the user is not signed in, and returns a cancellation notice. This meaningfully supplements the structured hints without contradicting them.

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-load the core action and then cover usage trigger, exclusions, accepted parameter, and failure conditions. Every clause adds decision-relevant information with no filler or redundant explanation.

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 destructive tool with an output schema, the description covers purpose, preconditions, failure modes, and result. An agent has enough information to select and invoke this correctly, including knowing not to use it for guests or non-Pending/Scheduled bookings.

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 only parameter, order_id, is already described as 'The booking's order id (from my_bookings).' The description repeats this by saying 'e.g. copied from my_bookings,' but does not add new semantic details such as format, length, or validation rules.

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

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

Opens with a specific verb and resource: 'Cancel a booking on the signed-in account' and immediately scopes it to 'Pending or Scheduled only.' This clearly identifies the operation and distinguishes it from sibling tools like book_appointment and reschedule_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?

Explicitly states the trigger: 'Use when the visit is no longer needed,' and provides an exclusion for guests: 'guests cancel via their emailed manage link instead.' It also lists preconditions such as the booking being yours, Pending/Scheduled, and the user being signed in.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations: discloses the auth profile (no sign-in), the privacy posture of the response (PII-minimal, never address/name/notes), timezone convention (Pacific, e.g. scheduledAtPacific), and the failure mode (not-found on a bad reference). This is rich, actionable behavioral context.

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

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

Front-loads purpose, then usage, then parameter and return/failure notes in a tight paragraph with no filler. Slightly dense with parenthetical asides, 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 an output schema, the description supplies everything else an agent needs: eligibility, trigger conditions, input variants, privacy constraints, timezone, and error behavior. Nothing material 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% and the sole `reference` parameter is already documented in the schema. The description restates that it accepts the submission id or the emailed confirm-link token, adding little beyond what the schema says. Baseline 3 is correct when the schema carries the parameter definition.

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 ('check what became of a previously submitted request') and immediately scopes it apart from siblings by noting it needs no sign-in while other booking tools (my_bookings) do. An agent can tell what it does and who it serves 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?

Gives a concrete trigger ('use when the customer asks whether the notary confirmed, moved, cancelled, or merged it') and an access condition (guests welcome, no sign-in). It does not explicitly name a when-not or a sibling alternative, so it stops short of 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 cover the read-only and non-destructive nature. The description goes beyond annotations by disclosing the return fields (withinServiceArea, distanceMiles, precise) and the failure behavior ('if the address cannot be resolved the message says not found'). It adds meaningful behavioral context, though it doesn't detail resolution thresholds or geocoding 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?

Three sentences with each one earning its place: purpose and scope, usage guidance with alternative, then parameter and return behavior. The information is front-loaded, and there is no filler or repetition of the 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?

For a two-parameter read-only tool with an output schema and clear annotations, the description covers everything an agent needs: use case, parameter semantics, return values, and not-found handling. No critical information 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?

Input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds extra value by giving an example of an acceptable address ('a Seattle street or ZIP') and explaining why service matters ('notary or apostille rules differ'), supplementing the schema with practical usage 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?

The description opens with a specific verb and resource: 'Check whether an address sits inside our Washington coverage and resolves precisely enough to book.' It also immediately differentiates itself from the sibling search_availability, so an agent knows exactly what this tool does and what it does not do.

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

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

The description explicitly states when to use this tool: 'Use when the customer wants an area answer without searching slots' and names the alternative, search_availability, which 'already validates the area itself.' It also notes that the optional service parameter changes notary vs. apostille rules, giving the agent clear selection criteria.

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

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

Beyond the readOnly and destructive annotations, the description discloses the three-path processing logic, the exact contents of the response (category, DIY path, offer), and the edge-case guarantee that unclear wording yields an 'unknown' category rather than an error. This is substantial behavioral context.

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

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

The description is a single dense paragraph that front-loads purpose, then covers categories, trigger, parameters, and behavior. Every clause carries distinct information, and there is no filler or repetition of schema 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 that an output schema is present, the description does not need to detail return fields. It fully covers input expectations, decision categories, the DIY path, and the fallback behavior, making it complete for an informational lookup 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% with meaningful descriptions for all three parameters, so the baseline is 3. The description adds only that 'document' should be in plain words and that the other two are optional, which is minor and mostly redundant with the schema's default null values.

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: 'Check whether a document can get an apostille and how,' and immediately distinguishes the three document categories (vital records, private papers, federal). This makes it clear what the tool does and separates it from action-oriented siblings like request_apostille.

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 names the trigger condition: 'Use when the customer asks is this apostillable,' which is clear and precise. It does not explicitly name when not to use this tool or call out alternatives, but the trigger is specific enough that an agent can route correctly against sibling tools.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, and the description reinforces this with 'pure, no side effects, nothing booked'. Beyond that it discloses a genuine error mode ('fails if `apostille` is true and `tier` is invalid') and the tier-ignored-when-apostille-false rule, which annotations cannot convey.

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 purpose and safety, then parameters, then return/failure behavior. Efficient and well ordered, though the parameter sentence is long and list-like.

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 annotations covering safety and an output schema covering amountCents/line items, the description fills the remaining gaps: parameter interactions and failure conditions. The only omission is how it relates to request_price_match, a meaningful ambiguity given the sibling set.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds cross-parameter semantics the schema lacks: tier examples, the ua_lane choice and its pricing effect, the first-doc-free interaction of translation_docs with the direct lane, and the needs_notarization condition.

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 ('Calculate a server-authoritative USD price estimate') and immediately scopes it with 'pure, no side effects, nothing booked', which distinguishes it from the booking siblings. An agent can tell this is a pre-sale quote tool and not an action tool 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?

Gives a clear trigger: 'Use when the customer asks about cost.' However, it never addresses the obvious alternative in the sibling list, request_price_match, leaving the agent to guess which pricing tool to pick.

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 signal read-only and non-destructive behavior. The description adds that this is a static catalog with no error if repeated, which conveys idempotency, and states the return shape (services plus payment notes). This is useful beyond the annotations, though it does not detail response structure further.

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 compact and front-loaded: purpose, then usage context, then I/O and behavior. Every sentence earns its place, and the note about the server instructions is an efficient way to manage optional invocation.

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 zero-parameter, read-only, static nature of this tool and an existing output schema, the description covers all necessary decision points: when to call it, what it returns, and that repeated calls are harmless. Nothing important 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 zero parameters, and the schema shows an empty properties object, so the baseline is 4. The description reinforces this with 'Takes: no arguments,' leaving no ambiguity for the agent.

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 begins with the specific verb 'List' and a concrete resource: the service catalog for Washington notary and apostille offerings, including prices and payment options. This clearly distinguishes it from siblings like get_price_quote, which targets a specific quote, and get_apostille_requirements, which targets requirements.

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

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

The description explicitly says to use it when the customer asks what the business offers or how to pay, and notes the tool is optional because server instructions already summarize the flow. It provides clear trigger conditions but does not name alternatives or give explicit when-not-to-use 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior: results are ranges and never guarantees, and an unknown `tier` silently falls back to the standard figure rather than erroring — a non-obvious failure mode an agent would otherwise mis-handle.

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 purpose before the alternative and the parameter recap. The single dense paragraph packs a lot in but every clause carries operational content; it is slightly over-stuffed rather than wasteful.

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

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

With an output schema present, return shape need not be explained, yet the description still notes 'staged day estimates' and the fallback semantics. Combined with explicit alternatives and the range-not-guarantee caveat, an agent has everything needed to call and interpret this read-only estimate 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 100%, so the baseline is 3; the description still adds value by giving concrete `service` examples (notarization, apostille, apostille_mail, loan_signing) and restating that `ua_lane` supplies the Ukraine lane when `shipping` is omitted, plus the unknown-tier fallback. It stops short of documenting destination_country inference beyond a pointer.

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 (calculate turnaround) and immediately defines what the estimate comprises: apostille processing days plus mailing and delivery legs. It also separates itself from the sibling search_availability, so an agent can distinguish estimate vs. exact availability 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?

'Use when the customer asks how long' gives an explicit trigger, and 'exact appointment times come from search_availability' names the alternative and the condition that routes to it. The boundary between this tool and the availability lookup 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 destructiveHint=false, but the description adds sorting behavior, return fields (orderId, service, status, scheduledAt, location), status examples, and a clear authentication failure mode. This goes well beyond the annotation defaults and gives agents a precise picture of what the call does.

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 with a distinct role: purpose, usage triggers, and arguments/return/error. Front-loaded with the core behavior and 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?

Covers purpose, sort order, use cases, return fields, status examples, and authentication requirement. With an output schema present and no parameters, 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?

The tool takes zero parameters, so the empty schema already covers everything. The description's 'Takes: no arguments' is redundant but harmless. For 0-param tools the baseline is 4.

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'), a clear resource ('every booking on the signed-in customer's own account'), and adds sorting order. The phrase 'own account' distinguishes it from any broader booking view, and no sibling tool overlaps with this read-only list.

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

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

Explicitly says 'Use when an authenticated customer asks what is scheduled' and 'to grab an order_id before reschedule_booking or cancel_booking.' It names the exact sibling tools it feeds into, and the failure condition 'fails if not signed in' implies when it should not be used.

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

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

The description discloses behaviors well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false): it reveals this creates a lead, not a confirmed order; that the notary asynchronously 'replies with mailing instructions and a quote'; that 'nothing charged until approved'; that existing_reference extends an open request; and that it 'fails if the name or a valid contact is missing.' This gives the agent a realistic model of the tool's side effects and non-deterministic human-in-the-loop behavior, which openWorldHint alone does not convey.

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?

Roughly four sentences contain the core purpose, the gating condition, required fields, the async reply flow, pricing behavior, extension semantics, and failure modes. The most important constraint (what this tool is for) is front-loaded, and every sentence adds non-redundant information. 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?

For a 7-parameter, 2-required tool with a rich output schema, the description is complete: it covers eligibility, prerequisites, the asynchronous process, approval/payment semantics, the extension path, the return value ('Returns a reference'), and failure conditions. Nothing an agent needs to decide whether and how to call it 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?

Schema description coverage is 100%, so baseline is 3. The description adds only marginal parameter insight beyond the schema: it reinforces that 'an email or phone' is required (already stated in the email property's schema description) and ties failure to missing name/contact. It does not add format, syntax, or value details beyond what the schema already documents.

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: 'Submit a mail-in apostille request — a lead for already-certified Washington public records needing NO notarization.' The scope is sharply delimited (mail-in, certified records, no notarization), which clearly separates it from siblings like request_booking, request_price_match, and get_apostille_requirements. The eligibility boundary ('already-certified', 'NO notarization') makes the tool's identity unambiguous.

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

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

The description gives an explicit when-to-use condition tied to a named sibling: 'Use when get_apostille_requirements says they qualify.' The 'already-certified ... needing NO notarization' phrasing implicitly states when-not-to-use (records still needing notarization or certification), and the lead-based nature distinguishes it from booking/price-match 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?

Beyond the annotations, the description discloses critical behavior: the booking is not a confirmed appointment, the notary follows up, passing existing_reference modifies rather than creates a duplicate, and the call fails if name or valid contact is missing. This is substantial behavioral context that the boolean annotations alone cannot convey.

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 but every clause earns its place: core distinction, usage condition, required inputs, cross-tool parameter provenance, modification behavior, and failure conditions. Key information is front-loaded, with the most important distinction stated first.

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 10 parameters and an output schema, the description covers the essential decision criteria, required fields, cross-tool dependencies, modification semantics, and what the caller receives for follow-up. The rich input schema and output schema handle the remaining details, so nothing needed to call the tool 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 schema already documents parameters well and the baseline is 3. The description adds meaningful semantics by requiring the FULL LEGAL NAME, insisting both email and phone be collected, tying desired_time_unix to search_availability's startUnix, and explaining existing_reference as an edit mechanism with 'never a duplicate'.

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 ('Submit a booking request') and immediately clarifies that this is a lead, not a confirmed appointment. It also distinguishes itself from the sibling book_appointment, leaving no ambiguity about what the tool does.

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

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

Explicitly says when to use this tool ('ready to book AND the customer is not signed in') and when not to ('a signed-in customer goes through book_appointment instead'). It also connects to search_availability for the time parameter and check_request_status for the returned reference, giving clear routing and follow-up guidance.

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

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

The description reveals that the notary decides within one business day, that the tool does not automatically set prices, that it returns a logged reference and a comparable quote when computable, and that it fails without a name or valid contact. This is substantial behavioral context beyond the annotations, with no contradiction.

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

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

Three dense sentences with no filler; the core purpose and the most important caveat are front-loaded. Every sentence contributes actionable operational 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 full schema coverage and an output schema present, the description adds exactly what is missing: when to use it, what happens after invocation, the human-decision timing, and failure conditions. An agent has enough to select, invoke, and set expectations 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 schema already documents all parameters. The description adds meaningful constraints: the email-or-phone requirement, service examples, and the failure condition when contact info is missing, which enriches rather than merely repeats 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?

Description names a specific action (request a price-match review), a specific target (a competitor's written quote from a comparable licensed notary), and a key scoping caveat: it never sets the price automatically. This distinguishes it from quote and booking siblings even without naming 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?

"Use when the customer found a cheaper offer" gives a direct trigger, and the written-quote/comparable-notary qualifiers narrow applicability. It does not explicitly say when not to use it or name sibling alternatives, but the context is clear enough.

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 signal a non-read, non-destructive, idempotent operation. The description adds valuable behavior beyond that: it returns a done confirmation and fails under specific conditions (unavailable slot, not your booking, not signed in). It does not mention idempotency details, but the annotation covers that, so the bar is met and exceeded slightly.

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

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

The description is a single dense sentence, but every clause earns its place: purpose, usage trigger, parameter sourcing, return signal, and failure modes. It is front-loaded with the core action 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?

With an output schema present, the description does not need to explain return structure. It fully covers how to obtain both parameters, when to invoke, expected confirmation, and failure conditions. Nothing an agent needs 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?

Schema coverage is 100%, so baseline is 3. The description repeats the schema provenance (order_id from my_bookings, scheduled_at from search_availability) and adds a minor 'fresh' nuance, but it does not provide meaningful new semantics beyond what the schema already states.

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 opens with a specific verb+resource: 'Move one of the signed-in customer's own bookings to a new slot.' It clearly distinguishes from siblings like book_appointment (new booking) and cancel_booking, and the 'own bookings' phrase separates it from any admin-style rescheduling.

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 'Use when an authenticated customer wants a different time' and gives a concrete workflow: find order_id via my_bookings, get a fresh startUnix from search_availability, send it as scheduled_at. It also states failure conditions including incorrect ownership and missing authentication, which effectively tells the agent 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses concrete behavior: meeting-area validation, resolved location, up to 7 slot recommendations, per-day windows, the exact start-time formula, and the ungeocodable-address error case. This gives the agent a strong behavioral model.

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 front-loads the purpose, then packs only high-value usage, return, and error behavior into a compact paragraph. Every clause adds information; there is no filler or repetition of the 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?

Given the output schema exists and the parameter schema is fully documented, the description covers the remaining operational details an agent needs: when to call it, how service/address interact, what the response contains, how to pass the result onward, and how errors surface.

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 schema already documents service, address, and document_count fully. The description adds a helpful example address and states the relationship between service and address, but these largely restate what the schema already says, so it does not significantly raise the baseline.

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

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

The description opens with the exact action and resource: finding open appointment slots, plus the additional validation of the meeting area. This clearly separates it from related tools like request_booking or check_service_area.

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 trigger ("Use when the customer wants a time") and explains the required service and address dependency for mobile appointments. It also directs the picked startUnix to request_booking, but it does not list explicit when-not cases or compare 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 already convey read-only and non-destructive behavior. The description adds meaningful behavioral detail beyond that: lexical matching with no semantic fallback, returns ranked excerpts with a URL and Markdown URL, empty list on no match, and the caveat that this is reference text, not a live quote. No contradiction with annotations.

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

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

Five dense sentences, each earning its place: scope first, usage next, params, return behavior, and exclusions. No filler or repetition; the most important scoping information is front-loaded.

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

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

Covers purpose, content scope, usage context, parameter constraints, return behavior, and distinctions from siblings. With an output schema present and annotations covering safety, nothing an agent needs to decide when and how to call it is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that query should be keywords and mentions optional lang, section, and limit, but it does not add new semantic information beyond what the schema already provides. The 'keywords, not prose' emphasis is helpful but redundant with the schema's own guidance.

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: 'Search the text of andrii.co', enumerating content (service pages, terms, privacy notices, apostille handbook). It distinguishes itself from siblings by saying it is for 'reference questions the other tools do not answer' and explicitly names get_price_quote and check_service_area as alternatives.

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

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

Explicitly says when to use this tool: 'Use for reference questions the other tools do not answer, and to cite a page.' It also provides a clear exclusion: 'not a live quote — use get_price_quote and check_service_area for what we charge and where we go.'

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