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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses meaningful behaviors: no authentication required, PII-minimal output, Pacific-time fields, and a not-found error for bad references. This gives an agent realistic expectations for invocation and response handling.

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 core purpose, followed by when to use it, the parameter, output characteristics, and error behavior. Every sentence earns its place and no filler is present.

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 one required parameter, full schema coverage, an output schema, and safety annotations already present, the description adds the remaining context an agent needs: authentication requirements, PII boundaries, time zone, and failure mode. Nothing important appears 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 schema's property description already explains that `reference` accepts the submission id or the emailed token. The description essentially restates this, adding no new semantic information beyond what the schema provides, 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 opens with a specific verb and resource: 'Check what became of a previously submitted request.' It also distinguishes from sibling tools by enumerating the status transitions it covers (confirmed, moved, cancelled, merged), making its role as a read-only status lookup 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?

It explicitly states when to use the tool: 'Use when the customer asks whether the notary confirmed, moved, cancelled, or merged it.' It also notes that no sign-in is needed, but it does not name sibling alternatives or explicitly describe when not to use it, so it stops short of a full when/when-not guide.

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?

The description goes beyond the readOnlyHint and destructiveHint annotations by explicitly stating there are no side effects, nothing is booked, the estimate is server-authoritative, it returns amountCents and line items, and it fails under a specific invalid combination of apostille and tier. This is rich, useful 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?

Three dense sentences carry purpose, usage, parameter guidance, return behavior, and an edge case without wasted words. The most important safety information is front-loaded, and every sentence 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?

With six optional parameters, a complete input schema, and an output schema available, the description covers all key decision points: when to call, what side effects to expect, key parameter interactions, and failure behavior. No critical context is missing for an agent to invoke this tool 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 baseline is 3, but the description adds meaningful cross-parameter semantics: it explains the apostille/tier relationship, notes that tier is ignored when apostille is false, and ties needs_notarization=false to already-certified records. This goes beyond simply restating 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?

The description opens with a specific verb and resource: 'Calculate a server-authoritative USD price estimate before shipping.' It also clarifies this is not a booking ('pure, no side effects, nothing booked'), which distinguishes it clearly from sibling tools like book_appointment, request_booking, and request_price_match.

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 the customer asks about cost,' which gives a clear trigger condition. It does not name alternative tools or explain when not to use it, but the context—comparing against booking and request siblings—makes the intended usage reasonably 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 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?

The description adds meaningful behavioral context beyond the readOnly/destructive annotations: results are ranges, never guarantees; returns are staged day estimates; and an unknown tier falls back to the standard figure rather than erroring. These are non-obvious behaviors an agent must know before invoking the tool.

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

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

The description is compact and front-loaded: the primary purpose and core behavioral caveat appear first, followed by a concise parameter list and the fallback behavior. Every sentence adds useful information; there is no filler or repetition of schema defaults.

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 estimation tool with four parameters, full schema coverage, and an output schema, the description covers the essential context: what it computes, how to use it, how it differs from the exact-availability tool, and what happens with invalid tier input. 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 100%, so the baseline is met. The description adds extra semantic value by giving concrete service examples, noting the fallback behavior for unknown tier values, and framing the parameters as contributing to 'processing days plus mailing and delivery legs.' This goes slightly beyond the schema's property 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 opens with a specific verb and object ('Calculate typical turnaround') and clearly defines the resource as an estimate of apostille processing plus mailing/delivery legs. It also distinguishes itself from search_availability, which provides exact appointment times, so an agent can tell them apart immediately.

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

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

The description explicitly states when to use the tool ('Use when the customer asks how long') and when not to rely on it ('exact appointment times come from search_availability'). This gives clear decision criteria and names the alternative tool, leaving no ambiguity about selection.

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

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

Annotations already declare 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.