Andrii Co. Notary & Apostille Assistant

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

While annotations already indicate non-read-only and non-destructive, the description adds substantial behavioral detail beyond annotations: the appointment is 'still a request until the notary confirms it, never guaranteed', and it 'Returns a Pending reference'. It also discloses the failure condition for unauthenticated users. This contextualizes the openWorldHint by explaining that the system is in a pending state, which is more transparent than the annotations alone.

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

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

The description is dense and information-rich but without fluff. It front-loads the core purpose and then details parameters and return/failure behavior. While it is longer than a minimal description, every sentence earns its place by conveying crucial context (pending nature, authentication requirement, parameter references). No sentence is 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?

Given there is no output schema, the description appropriately states the return value ('Returns a Pending reference') and failure condition. It also explains the relationship with search_availability and the guest alternative, covering the main decision points an agent needs. With annotations and full parameter coverage, nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description adds extra meaning by linking `scheduled_at` to a `startUnix` from search_availability and explaining the 'call-me' omission case, and by noting `address` is required for mobile. This goes beyond the schema's basic descriptions, providing contextual relationships and conditional requirements.

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

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

The description clearly states the tool 'schedules an appointment' tied to the signed-in customer, distinguishes it from the guest flow by explicitly naming request_booking, and lists the accepted services. It references search_availability for the slot parameter, establishing a clear relationship to another tool. The verb and resource are specific, and it is easily differentiated from siblings.

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

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

The description explicitly states when to use it ('when the customer is authenticated') and when not to ('guests go through request_booking'). It also notes that it 'fails if not signed in', providing a concrete exclusion condition. This is explicit guidance that leaves no ambiguity about the appropriate context.

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

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

Annotations already indicate destructiveHint=true, and the description confirms the mutation by stating it returns a cancellation notice. It adds valuable context beyond annotations: failure conditions (not yours, not Pending/Scheduled, not signed in) and the return type (notice). No contradiction with annotations; readOnlyHint=false aligns.

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

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

The description is two tight sentences. The primary purpose and constraints are front-loaded, and every clause earns its place—no filler or redundancy. The transition from purpose to usage to behavior is natural and compact.

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

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

For a simple single-parameter tool with no output schema, the description covers the essential operational aspects: return notice, failure modes, and auth requirement. It does not detail the exact response structure, but that is minor. It also does not mention reversibility, which is likely unnecessary given the destructive nature. Sufficient for an agent to call successfully.

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% (the only parameter has a description already). The description reinforces the source ('e.g. copied from my_bookings') and adds the implicit constraint that the booking belongs to the signed-in account, which is more actionable than the bare schema. This slightly exceeds the baseline 3 for full coverage.

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 ('Cancel'), a clear resource ('a booking'), and immediate scope ('on the signed-in account — Pending or Scheduled only'). It also explicitly distinguishes from guest cancellation via the manage link and implicitly from reschedule_booking, making it unambiguous which tool to use.

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

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

It gives a concrete when-to-use condition ('when the visit is no longer needed') and an explicit alternative for guests ('guests cancel via their emailed manage link instead'). It does not explicitly mention reschedule_booking as an alternative for date changes, but the Pending/Scheduled constraint is stated, which implicitly narrows usage. Overall, provides clear context and an exclusion.

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, so the description adds extra context: no authentication required, PII-minimal (never address/name/notes), timezone (Pacific time), and failure behavior ('Fails if the reference is wrong — a not found reply'). This goes well beyond the structured annotation info.

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, well-structured paragraph that front-loads purpose and usage, then covers the parameter, return, and error behavior. No wasted words; every sentence adds value.

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 there is no output schema, the description fully explains the return content (service plus status and timing), the PII limitation, timezone, and failure case. For a single-parameter read-only tool, this is complete and leaves no ambiguity for an agent.

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% (the parameter reference is described in the schema). The description adds meaning by clarifying that 'reference' accepts both the id returned at submission and the token from the emailed confirm link, which is not explicit in the schema's own description but is a valuable clarification.

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

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

States a specific verb 'Check' with a clear resource 'request status' and scope 'previously submitted request'. Distinct from siblings that create or modify requests; it is clearly for querying the outcome of an existing request.

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 when to use: 'Use when the customer asks whether the notary confirmed, moved, cancelled, or merged it.' Also provides a condition 'no sign-in needed, guests welcome', clarifying it can be used without authentication. No explicit exclusions, but the trigger scenario is specific enough to route correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds genuine behavioral context: it lists the exact fields returned (withinServiceArea, distanceMiles, precise) and describes the 'not found' failure case. It also clarifies that the service parameter alters the evaluation rules. This goes beyond the annotations without contradicting them, providing useful expectations for the agent.

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 well-organized: a one-sentence purpose, a usage hint, an 'Accepts' summary, and a 'Returns' note. Every sentence earns its place; there is no fluff or redundant phrasing. The most important distinction (vs. search_availability) 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?

For a read-only tool with two parameters, one required, and no output schema, this description is very complete. It covers the purpose, usage guidance, parameter behavior, and return fields, plus failure behavior. The only minor gap is not defining what 'precise' means in output, but that's not essential for invocation. Annotations already cover safety and open-world aspects.

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% — both address and service have descriptive schema entries, including the default for service. The description repeats that service affects rules, but this is already in the schema. Since the schema fully documents both parameters, the description adds no new semantic value, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Check whether an address sits inside our Washington coverage') and adds a clarifying qualifier ('resolves precisely enough to book'). It immediately distinguishes itself from search_availability by noting that the sibling already validates the area itself. This gives an agent a crisp mental model of what the 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 ('when the customer wants an area answer without searching slots') and names the alternative (search_availability) that already performs area validation. It also flags that service rules differ between notary and apostille. This is clear, actionable routing guidance with no ambiguity.

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

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

Annotations already indicate read-only, but the description adds substantial context: explains handling of ambiguous input ('unknown' category, never an error), documents the return payload (category, DIY path, offer), and outlines the domain logic for different document types. This goes beyond annotation coverage.

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

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

Four sentences with no wasted words. The primary purpose and domain rules come first, followed by the usage trigger and parameter overview. Well-structured and easily digestible.

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

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

For a read-only lookup tool with no output schema, the description adequately explains what it returns and handles edge cases. It doesn't enumerate all possible categories, but examples and the 'unknown' fallback cover the necessary context without confusing the agent.

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 each parameter already described. The description only restates the names and that they are optional/required, adding minimal new meaning (e.g., 'plain words' for document). No significant additional value beyond 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 clearly states the tool checks apostille eligibility and provides an action plan, distinguishing it from siblings like 'request_apostille' (which actually files the request). It also details document categories, making the resource specific.

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 'Use when the customer asks is this apostillable,' giving a clear trigger. It does not explicitly name alternative tools for when a user wants to proceed, but the instruction is sufficient and 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; the description reinforces this with 'pure, no side effects, nothing booked.' It adds valuable behavioral context not in annotations: the tool fails when apostille is true and tier is invalid, and it returns amountCents and line items. It does not discuss rate limits or other edge conditions, but given the annotation coverage, the added behavior detail is adequate.

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

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

The description is three sentences with no fluff, front-loading the purpose and purity guarantee. It condenses parameter interactions and failure conditions into a compact paragraph. A slightly clearer separation between 'accepts' and 'returns' structures might improve scannability, but it remains efficient and to the point.

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 6-parameter tool with no output schema, the description covers the key use case, parameter interdependencies, return value summary, and a failure mode. It does not replicate the schema's per-parameter details but supplies the cross-cutting logic an agent needs to invoke correctly. Given the annotations and schema coverage, the description is sufficiently complete, though a note about the document_count range (1–20) could slightly improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that tier is ignored when apostille is false, and that needs_notarization=false is for already-certified records. It also implicitly clarifies the relationship between after_hours and mobile (already in schema, but reinforced). This adds meaningful usage nuance beyond the structured parameter 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 states a specific verb and resource: 'Calculate a server-authoritative USD price estimate' and clarifies this is pre-shipping, pure, and has no side effects. It clearly distinguishes this from booking tools by stating nothing is booked, and from other estimate tools by noting server-authoritative pricing. The purpose is unambiguous and well-scoped.

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 the customer asks about cost,' which gives a clear trigger for invocation. It also notes that needs_notarization should be set false for already-certified records, which is an operational guideline. However, it does not mention alternatives like get_services or get_turnaround_estimate or explicitly state when this tool should NOT be used, so it lacks the full when/when-not/alternatives structure of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing the tool as a safe read operation. The description adds valuable context beyond that: it explicitly calls the catalog 'static' and states 'no error if repeated', which clarifies idempotency and reliability. It also discloses the return shape ('services plus payment notes') without relying on an output schema. This exceeds the baseline set by 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 about three sentences and front-loads the main purpose. The note about being optional and the server instructions is useful meta-context, and the return info is concise. Nothing is wasteful, though the 'Takes: no arguments' could be seen as redundant with the schema, but it's harmless. Overall, it's efficient and well-structured.

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

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

For a simple, read-only, zero-argument tool, the description covers the purpose, content, and when to call it. It doesn't specify the exact JSON structure of 'services', but the lack of an output schema makes that less critical for a catalog listing. The mention of payment options gives sufficient detail for an agent to know it covers payments. Additionally, the static nature and no-error guarantee reduce uncertainty. It's complete for an agent to invoke correctly.

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

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

There are zero parameters, and the schema already reflects an empty object. The description reinforces this by stating 'Takes: no arguments'. Since there are no parameters to explain, the baseline of 4 applies, and the description adds no redundant information that would inflate the score.

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: 'List the service catalog' and immediately scopes to 'Washington notary and apostille offerings with USD prices and accepted payment options'. This clearly distinguishes the tool from siblings like get_price_quote (specific quote) or get_apostille_requirements (specific requirements). It also states the call signature ('Takes: no arguments') and the return content, 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?

The description gives explicit when-to-use guidance: 'use when the customer asks what we offer or how to pay'. It also notes that the server instructions may already summarize the flow, indicating the tool is optional in some contexts. However, it does not name alternative tools or explicitly state when NOT to use it, but given the tool's clear scope, the guidance is sufficient.

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 annotation, the description discloses critical behaviors: it returns ranges rather than guarantees, falls back to the standard tier for unknown tier values instead of erroring, and explains shipping inference when omitted (apostille defaults to US shipping). These are valuable operational details that an agent needs to invoke correctly, going well beyond the annotation's basic read-only flag.

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

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

The description is a single, dense paragraph that front-loads the purpose in the first clause. Each subsequent sentence adds essential information: range behavior, usage trigger, accepted parameters, and fallback semantics. While slightly long, it contains no fluff and is structured logically, earning a high score.

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 without an output schema, the description covers the key aspects: what it calculates, how it behaves (ranges, fallback), parameter details including inference rules, and when to use it. It doesn't detail the exact return structure ('staged day estimates' is mentioned but not broken down), but given the simplicity and no output schema, this is sufficient for an agent to call it correctly.

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

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

The schema already describes each parameter with allowed values (100% coverage), so a baseline of 3 is appropriate. The description adds extra semantic context: shipping is inferred from destination_country when omitted, and apostille legs default to US shipping. It also clarifies the fallback behavior for unknown tiers. These additions go beyond the schema, warranting a score above 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 a specific verb and resource: 'Calculate typical turnaround — apostille processing days plus mailing and delivery legs.' It clearly distinguishes itself from search_availability by stating 'exact appointment times come from search_availability.' The scope (service types like notarization, apostille, apostille_mail, loan_signing) is unambiguous, so an agent can immediately identify what this tool does and how it differs from siblings.

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

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

The description explicitly states when to use this tool: 'Use when the customer asks how long' and contrasts it with search_availability for exact times. It also notes 'Ranges, never guarantees,' setting expectations. This provides clear guidance on both when and when not to use the tool, fulfilling the dimension fully.

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, so the safety profile is covered. The description adds beyond that: sorted order (latest first), exact return fields (orderId, service, status, scheduledAt, location), and the auth failure behavior. This is useful context beyond the annotation, but not exhaustive (e.g., pagination or error details).

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 main purpose, then compactly provides usage triggers, input/return details, and a failure mode. Every sentence earns its place; no filler or redundancy.

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

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

Given no output schema, the description explains return fields and status examples, the auth requirement, and sorting. All necessary information for an agent to call and interpret the result is present. Nothing critical 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?

With zero parameters, the schema has full coverage. The description states 'Takes: no arguments', confirming the expected call. The baseline for 0 params is 4, and the description adds no parameter-specific info (there is none), so it appropriately met 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?

States specifically 'List every booking on the signed-in customer's own account' with a clear verb and resource, and explicitly differentiates from siblings by mentioning reschedule_booking and cancel_booking. The sorting and field details clarify scope unambiguously.

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 specifies when to use: 'when an authenticated customer asks what is scheduled, or to grab an order_id before reschedule_booking or cancel_booking'. Also notes failure condition (not signed in). This provides clear context and implies exclusions, though not naming all siblings.

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

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

The description discloses that this is a submission creating a lead, returns a reference, fails if required info is missing, and that nothing is charged until approval. It also mentions the notary's follow-up (mailing instructions and quote). While annotations indicate a write operation, the description adds useful process context 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?

The description is dense but not bloated. It front-loads the core action and then covers prerequisites, process, and failure conditions in a few sentences. Every sentence contributes information, though minor restructuring could improve readability.

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 write tool with no output schema, it adequately covers the process (submission, response, failure conditions, and follow-up). It also ties usage to get_apostille_requirements. It doesn't explain future status checks, but that's not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable clarification: it states that at least one of email/phone is required (which the schema does not enforce) and explains the semantic of existing_reference (extending an existing request rather than creating a new one). This goes beyond 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 clearly states the tool's action (submit a mail-in apostille request) and resource (already-certified Washington public records needing no notarization). It explicitly distinguishes itself from get_apostille_requirements by describing the eligibility check, and it specifies the expected outcome (returns a reference).

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 condition for use: 'Use when get_apostille_requirements says they qualify.' It also provides guidance on an alternative usage (passing existing_reference to extend an open request) and lists required inputs (documents, name, contact). This clearly tells an agent when and how to invoke 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?

The description goes beyond annotations by explaining the asynchronous nature (notary follows up), the failure condition (missing name/contact), and that existing_reference never creates a new record. It also mentions the return of a reference for later status checks, all of which are behavioral traits not visible in annotations alone.

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 tight paragraph with every sentence serving a purpose: purpose, timing, requirements, modifications, and return value. It's front-loaded with the core concept and avoids redundancy, making it efficient for an agent to parse.

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 10-parameter tool with no output schema, the description covers the essential workflow: what to pass, how to handle modifications, failure modes, and what the response contains. It also references related tools for the full booking lifecycle, leaving little ambiguity for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant value by linking desired_time_unix to search_availability's startUnix, clarifying existing_reference usage, and reiterating the email/phone requirement. However, some parameter-specific nuances (like address being mobile-only) are only in the schema, not in the description, so it doesn't fully exceed 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 clearly states the tool submits a booking request that is a lead, not a confirmed appointment, distinguishing it from sibling tools like book_appointment. It names the resource (booking request) and the action (submit), and even references related tools (search_availability, check_request_status) to anchor its purpose.

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 ready to book' and provides detailed conditions for when to pass existing_reference (to modify an open request) versus creating a new one. It also highlights the need to collect both email and phone, and to pass desired_time_unix from search_availability, giving clear, actionable usage direction.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so this is a write but non-destructive operation. The description adds substantial behavioral context: it returns a logged reference and a comparable quote 'where computable,' states the notary decides within one business day, and clarifies competitor_url is stored but never fetched. This goes well beyond the annotations, fully disclosing side effects and workflow.

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

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

The description is concise yet rich, front-loading the core purpose and constraints. Each sentence contributes distinct information: the primary behavior, the usage trigger, required inputs, return behavior, and failure conditions. There is no filler or repetition.

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

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

For a tool without an output schema, the description fully explains the return value (logged reference and comparable quote) and its conditional nature. It also covers prerequisites, failure modes, and the manual decision step. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all parameters are already described in the schema. The description adds useful contextual meaning, such as competitor_url being stored but never fetched, and document_count being 'for our comparison quote.' This enriches the schema without redundancy, though some required fields are merely repeated.

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 defines the tool as a request for a price-match review of a competitor's written quote, explicitly stating it never sets the price automatically. It distinguishes itself from sibling tools like get_price_quote by focusing on the competitor-comparison workflow, making it unambiguous for an agent.

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 a direct trigger condition: 'Use when the customer found a cheaper offer.' It also lists required inputs and notes a failure condition (missing name or contact), which implicitly guides the agent on when not to call it. The mention of 'never sets our price automatically' clarifies its non-authoritative role, setting it apart from quote-based 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds context beyond that: it specifies that the tool only works on the signed-in customer's own bookings, that it requires authentication, and that it returns a done confirmation. It also discloses failure conditions, which is valuable behavioral context. Given the relatively straightforward annotations, this description adds meaningful behavioral detail without contradicting 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 — two sentences with a clear flow. The core purpose and usage flow are front-loaded. The only slight inefficiency is the trailing list of failure conditions, which could arguably be tighter, but it's still concise and every sentence earns its place by providing usage guidance.

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 only two parameters, both fully documented in the schema, a clear usage flow, and annotations that carry the safety profile (readOnlyHint=false, destructiveHint=false), the description is complete. It explains prerequisites (authentication), how to obtain the parameters, what the return is (done confirmation), and what failure modes exist. An agent has everything it needs to call this tool correctly and know when it will fail.

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

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

Schema description coverage is 100%, so both parameters (order_id and scheduled_at) are already documented in the schema. The description reinforces that order_id comes from my_bookings and scheduled_at comes from search_availability, which is slightly more context than the schema but doesn't add substantially new meaning. The description mentions the format 'startUnix' (from search_availability) which is slightly more detail than the schema's 'The new slot's description', adding a small bit of value. 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 tool's function: moving a customer's own booking to a new slot. It names the specific resource (booking) and action (move/reschedule), and differentiates it from siblings by emphasizing ownership ('one of the signed-in customer's own bookings') and the use case (customer wants a different time). This distinguishes it from book_appointment, request_booking, and cancel_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?

The description explicitly provides a usage flow: use when an authenticated customer wants a different time, find the order_id via my_bookings, take a fresh startUnix from search_availability, and send it as scheduled_at. It also mentions failure conditions (new time not genuinely available, booking not yours, not signed in) which gives clear guidance on when not to use it and what prerequisites exist. The alternative tools for finding related data (my_bookings, search_availability) are named.

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

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

Despite readOnlyHint and openWorldHint annotations covering the safe-read nature, the description goes further by detailing the return structure (resolved location, up to 7 slots, per-day windows with the k-th start formula), and the geocoding failure flag ('flagged not found'). This adds meaningful behavioral context beyond annotations.

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

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

The description is a compact paragraph with no wasted words. It front-loads the core action ('Find open appointment slots') and then packs in constraints, return format, and integration hints efficiently. Slightly long but every part 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?

There is no output schema, so the description fully compensates by explaining the return format (location, slot count, startUnix, per-day windows, and the formula for deriving each start) and the error flag for ungeocodable addresses. An agent has all needed details to interpret results correctly.

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

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

The schema already covers all 3 parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra nuance—that address is required for mobile and ignored for office, and that document_count drives appointment length—which goes beyond the schema's basic text. This lifts it above 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 clearly states the tool's purpose: 'Find open appointment slots' with the added scope of validating the meeting area. It distinguishes itself from sibling booking tools by explicitly mentioning how the result feeds into request_booking, so an agent knows it is a search, not a booking, operation.

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 when to use: 'Use when the customer wants a time.' It also specifies required service types, the address requirement for mobile, and how to pass the chosen startUnix to request_booking. This is textbook guidance for selecting and invoking the tool correctly.

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