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

Annotations already declare it as a non-read-only, non-idempotent, non-destructive creation tool. The description adds useful behavior beyond those annotations: it creates an active customer with default price group, document theme, and tax settings, and it clarifies that the email is stored for quotes/invoices but no external message is sent.

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 short and front-loads the core action. However, the final sentence ('It reaches no one and stays inside Tradify') is somewhat vague and could be phrased more directly.

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?

It covers the main creation semantics and important defaults, which is valuable for a 9-parameter create tool with no output schema. It still lacks details on duplicate handling or what the tool returns, leaving meaningful gaps for an agent invoking it.

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 56%, so the schema already documents the key fields, including email and contact. The description restates email behavior and groups contact/address fields, but it adds little detail for city, phone, mobile, or postal_code, leaving several parameters without additional semantic 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?

The description uses a specific verb and resource: it creates a new customer profile and states that the result is an active customer with company defaults. This clearly distinguishes it from list_customers and from other create_* siblings for jobs, quotes, and invoices.

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

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

The description implies usage by comparing it to the New Customer form and by explaining that email is used for quotes and invoices, but it does not explicitly say when to use this tool versus alternatives or when not to use it. The guidance is inferable rather than stated.

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

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

Adds substantial context beyond the annotations: the created object is a draft (not a finalized invoice), it is linked to the quote and its job, the due date is derived from payment terms, partial invoices inherit the quote's tax rate, and part modes are plan-gated. These are exactly the lifecycle and entitlement facts annotations do 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?

Front-loaded with the core action and scope, then a dense but purposeful sentence enumerating modes. The mode enumeration is a run-on list, but every clause maps to a real enum value or constraint, so little is wasted.

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

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

With no output schema, the description does the work of explaining the resulting state (draft, linked to quote and job, derived due date). It never states what identifier or payload is returned, which an agent needs in order to chain into send_invoice, but otherwise covers the call fully.

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

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

Schema coverage is 75% and the mode enum has no per-value documentation in the schema, so the description carries real weight: it defines what each of the five modes does and clarifies that `lines` holds 1-based positions and `amount` means a percent or a tax-inclusive figure depending on mode.

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 (draft invoice from a quote) and immediately scopes it: entire quote or a part of it. It is clearly distinguishable from siblings such as create_quote, create_job, and send_invoice, and even anchors to the equivalent UI action (Create Invoice > From Quote).

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

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

Gives a clear precondition (quote must be approved or accepted), a routing constraint (part modes require a Pro plan with progress invoicing), and an explicit next step (the invoice stays a draft until send_invoice). The agent knows both when to call it and what to call afterwards.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description usefully adds that each call consumes a new job number (explaining the non-idempotency), that the job begins Unassigned, and that creation sends no notification and stays inside Tradify. This is real context beyond the annotations, though it omits what happens on failure or whether deletions/rollback are possible.

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

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

It is short, but the opening 'New job for a customer. It starts as Unassigned.' is restated almost verbatim in the third sentence, wasting the front-loaded position. The fragment style and the unexplained 'as New Job does' also cost clarity.

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

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

With no output schema, the description should say what a successful call returns (e.g., the new job's identifier) so the agent can chain into schedule_appointment or get_job. It covers the creation semantics and defaults well but leaves that chaining-critical detail unaddressed.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the 'Default: the customer's' fallbacks that the description restates. The description adds no field-level meaning 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 names a concrete verb and resource (creates a job for a customer) and states the resulting state (starts as Unassigned, Tradify assigns the next job number). It also positions itself against schedule_appointment, which books staff on the created job. The only weakness is the redundant first sentence overlapping with the third, and the cryptic reference to 'as New Job 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?

Usage is implied rather than stated: the agent can infer this is the creation step that precedes schedule_appointment. There is no explicit 'use this when X, not Y' or exclusion such as 'do not use for existing jobs, use update_job_status instead,' so routing must be inferred from the sibling list.

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 that it writes and is non-idempotent, and the description adds real context on top: the object stays a draft, tax uses the default rate or a named rate, totals are computed as Tradify does, and price-list items/kits will not work yet. That discloses side-effect boundaries and failure modes an agent could not infer from the schema.

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

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

The key constraint (nothing sent until send_quote) is front-loaded and the closing sentence reinforces it, so the reader gets the gist in one line. The middle is a dense run-on chain of clauses that could be broken up, but every clause carries distinct 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?

Covers creation semantics, defaults, tax handling, and unsupported features for a 7-parameter create tool with no output schema. The one real gap is that it never says what comes back (presumably a quote ID needed for send_quote), which the agent must infer.

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

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

Schema coverage is already 86%, so baseline is 3; the description adds cross-field logic the schema lacks, notably that job_id must be a job of the same customer, that time-line prices come from the customer's price group unless unit_price is given, and that expiry falls back to a user setting. It does not explain reference, description, or tax_inclusive beyond the schema, which is acceptable.

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 up front ("Draft quote with line items") and immediately distinguishes its scope from send_quote. The related sibling (New Quote / send_quote) is named, so the agent can tell it apart from send_invoice and create_invoice_from_quote.

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 nothing is sent until send_quote, which tells the agent this is the pre-send step, and it flags unsupported inputs (price list items and kits) as a when-not condition. It does not, however, position itself against create_invoice_from_quote or explain how a draft flows into invoicing.

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

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

With readOnlyHint and idempotentHint already declaring safety, the description adds valuable return-content transparency: customer, contact, site address, staff, tasks, notes, Scheduler appointments with UTC offset, costs, and linked quotes/invoices. It does not discuss error behavior or permissions, but it substantially exceeds the annotation-level disclosure.

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

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

The description is front-loaded with a useful summary and then expands into detail. There is some redundancy between "Full job: ..." and "Returns one job: ...", but the overall structure is readable and not excessive.

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

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

For a one-parameter read tool with no output schema, the description fully explains what is returned and adds the key workflow instruction to read the job before changing it. No essential calling information appears to be missing.

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

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

Schema coverage is 100%, and the sole parameter is documented as "Job ID from list_jobs." The description does not add parameter-specific meaning beyond the schema, so the baseline score of 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 gives a specific verb/resource ("Returns one job") and enumerates the job data returned, so its purpose is clear. It distinguishes itself implicitly from list_jobs by emphasizing a single full job, though it does not explicitly name 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?

It provides one workflow cue: "Read it before changing a job." That is useful context, but it does not explicitly compare this tool with alternatives such as list_jobs or update_job_status, so selection guidance is only partially covered.

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

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

Annotations already declare readOnly, idempotent and openWorld, so the description does not need to re-establish safety. It does add genuinely new behavioral facts: the 31-day maximum window, inclusive end-day semantics, ISO 8601 timestamps carrying the company's UTC offset, the enumeration of possible status values, and that the staff filter is a restriction rather than an expansion. The only notable gap is pagination/result-size behavior for a potentially long range.

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

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

Two tightly packed sentences with no filler; the purpose and field list come first, followed by the constraints and return shape. The opening is a noun phrase rather than a verb phrase, which is slightly less front-loaded than it could be, but nothing is wasted.

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

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

With no output schema, the description fully carries the return contract: entity fields, timestamp format, status vocabulary and filter semantics. Combined with the documented range ceiling, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nonetheless adds meaning beyond the schema by clarifying that both from and to are included as whole days and that staff narrows results by full name (a filter, not a lookup key).

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

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

The description names the resource precisely (Scheduler job appointments) and enumerates the returned fields (job, customer, staff, start/end, notes, status), so an agent knows exactly what it is querying. It does not, however, contrast itself with the nearby list_jobs or schedule_appointment siblings, leaving the boundary between 'jobs' and 'appointments' to inference.

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

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

Usage is only implied by the date-range framing; there is no explicit statement of when to call this instead of list_jobs, get_job or schedule_appointment, and no exclusions or prerequisites. An agent can infer it is a read/list operation over a bounded window, but the routing decision is left unstated.

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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuine context beyond them: search matches name/contact/email/phone, archived switches the result set, and next_cursor must be passed back as cursor. It does not mention rate limits or default page size, so not a 5.

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

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

Tight, two-sentence body where every clause carries information (search scope, downstream use, archived, cursor). The lead fragment 'Customer profiles with contact details and sites' is slightly return-value focused rather than action-focused, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing returns and does so at a summary level (fields, archived variant, cursor pagination). For a four-optional-parameter read tool this is sufficient; only the limit default/maximum behavior is left entirely to the schema.

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

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

Schema description coverage is 75% — cursor, search and archived are already documented in the schema, and limit is constrained there. The description mostly restates the search match fields and cursor handoff rather than adding syntax or edge-case semantics, so baseline 3 applies.

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

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

The description pairs the verb 'Lists' with the resource (customers, by name) and enumerates the fields returned (contact, email, phone, mobile, address, sites). It is clearly not one of the write-oriented siblings (create_job, send_invoice), though it doesn't name a specific sibling to contrast with.

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

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

Explicitly states the routing use case: 'use it to find the customer_id before creating a job or quote', which ties this lookup to the downstream create_* tools in the sibling set. It also explains the archived toggle and the cursor round-trip. It lacks an explicit 'do not use this when…' exclusion, keeping it short 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?

Beyond the read-only annotations, the description discloses sorting order, computed amount due, pagination flow via next_cursor, and precise filtering semantics for status and customer_id. This gives the agent meaningful behavioral context for invoking the tool correctly.

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

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

The description is dense and front-loads the returned fields, but it repeats the invoice fields in the first two sentences. It remains efficient overall, though slightly redundant.

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

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

For a read-only list tool with no output schema, the description sufficiently explains returned fields, ordering, filtering, status semantics, and pagination. An agent has enough information 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 high at 80%, and the description adds useful meaning for status values, default status behavior, customer_id filtering, and cursor pagination. It does not explain the limit or search parameters beyond what the schema provides, so it is strong but not exhaustive.

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

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

The description uses a specific verb and resource: it says the tool lists invoices, names the fields returned, and specifies newest-first ordering. It is clearly distinct from sibling list tools such as list_quotes, list_jobs, and list_customers.

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 explains the default status and the meaning of each status value, and it clarifies how customer_id and status interact. It does not explicitly name when to use an alternative tool, but the usage context for a filtered invoice list is clear.

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

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

Annotations already establish this as a safe, idempotent, read-only, open-world read, so the description's extra value is in ordering ('newest number first'), the default active-only filter, and cursor-based paging. The ambiguous clause 'status then filters the page you get' hints that filtering happens after the limit is applied, which is a genuinely useful if slightly murky disclosure.

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?

Dense and front-loaded: return fields first, then ordering and default scope, then parameter interactions, then the cursor instruction. The opening sentence is a bare noun-phrase fragment that reads awkwardly, but every clause carries information and nothing is padding.

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

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

With no output schema, the description compensates by naming the five returned fields, the sort order, the default filter, and the continuation mechanism. An agent can call this correctly and paginate without needing anything further.

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

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

Schema coverage is 80%, so the schema does much of the work, but the description adds real meaning: cursor must be the next_cursor from a prior call, and customer_id composes with status in a way the schema alone does not convey. It says nothing about `search` or `limit`, which is the remaining gap.

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

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

States a specific verb and resource ('Lists jobs') and immediately enumerates the returned fields (number, customer, site address, status, assigned staff), which tells an agent this is a bulk job listing rather than a single-record fetch. It doesn't explicitly name get_job as the single-record alternative, so sibling differentiation is left implicit.

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

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

Gives clear operating context: default is active-only, and 'status all, a built-in status or the name of a custom status narrows it' tells exactly what values do. It also flags the non-obvious combination rule that customer_id plus status filters within the returned page. No explicit when-not guidance or named alternatives, keeping it below 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 read-only, idempotent and non-destructive, so the safety profile is covered. Beyond that, the description adds ordering behavior, default status behavior, the definition of 'expired', and the cursor round-trip ('Pass next_cursor back as cursor') — real behavioral context rather than restatement.

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 what it returns and how it sorts, then defaults, then pagination — a sensible order. The opening fragment ('Quotes with customer, total, quote date, expiry date and status.') largely duplicates the following sentence's field list, which is the only real waste.

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

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

With no output schema, the description carries the return-shape burden and does so by listing fields and ordering, and it explains pagination. It's nearly complete for a filtered read tool; the relationship between limit/paging behavior and the default result set is left to the schema.

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

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

Schema coverage is 80%, so baseline is 3, but the description adds meaning the schema lacks: the default status is awaiting_acceptance, 'expired' is a subset of awaiting_acceptance past expiry, 'since' filters by quote date, and cursor is the previous next_cursor. The remaining gap is limit/search behavior, which the schema covers.

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

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

States a specific verb and resource ('Lists quotes') and immediately enumerates the returned fields (customer, linked job, total with tax, quote/expiry/accepted dates, status) plus sort order (newest quote date first). That is enough to distinguish it from create_quote, send_quote and create_invoice_from_quote without opening any schema.

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

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

It explains the default filter ('quotes awaiting acceptance'), clarifies what 'expired' means, and gives a concrete recipe: 'use status accepted with since to find what was won in a period'. It offers no explicit when-not-to-use or sibling routing, so it falls short of the top band, but the usage context is clear.

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

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

Goes well past the annotations: no charge is made, no email is sent, the amount is capped at the amount due, full payment flips the invoice to paid, and payments sync to a connected accounting app (which explains openWorldHint). This tells the agent exactly what side effects to expect from a non-idempotent mutation.

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

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

Two tight paragraphs: the first states the action and effect, the second supplies preconditions, limits and side effects. Every sentence carries information and the summary line 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 mutation tool with no output schema, the description covers preconditions, amount constraints, downstream state changes and external sync. Combined with annotations that already declare safety and idempotency, 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 five parameters are already documented including defaults and the invoice_id provenance. The description echoes amount, date, method and reference without adding format or constraint detail beyond what the schema states, so the baseline 3 applies.

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

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

Names a specific verb and resource ('Record a payment received against an invoice') and states the resulting state change ('reduce the amount due'). No sibling tool touches payments, so the boundary is unambiguous from the sentence alone.

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?

Establishes the precondition explicitly - the payment must already be received and the invoice must be approved - and clarifies scope with 'It charges nobody and emails nobody', which implicitly routes charging/notifying to tools like send_invoice. It does not name an alternative tool directly, so it stops short 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 flag mutation, external side effects, destructiveHint, and non-idempotency; the description adds concrete behavior beyond that: each named staff member gets a scheduled notice, an Unassigned or Assigned job becomes Scheduled, and email_customer sends the customer confirmation with customer_message. It still does not disclose duplicate-call behavior or appointment conflict 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 front-loaded with the core action and key side effects. It is slightly redundant, since the opening mentions optionally emailing the customer and the second paragraph repeats that email_customer sends the confirmation, but it remains efficient overall.

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 seven-parameter mutation with no output schema, the description covers the important invocation context: defaults, staff expansion, status transition, and external email side effects. It leaves response shape and conflict/idempotency behavior unstated, but those are secondary 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 the schema already documents all seven parameters. The description still adds meaning beyond schema text: staff are named by full name, default to the signed-in user, and receive one appointment each; email_customer controls the customer confirmation; customer_message is included in that email.

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

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

States a specific verb and resource: 'Book a job appointment on the Scheduler for staff.' It clearly distinguishes the action from viewing siblings like list_appointments and from status-only changes like update_job_status by describing start-to-end booking and staff assignment.

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 context and defaults, including that staff defaults to the signed-in user and that email_customer is optional. However, it does not explicitly say when to use this instead of siblings such as update_job_status or list_appointments, nor when not to use it, so usage is only implied.

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

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

Beyond annotations, it discloses the approval step, email link, payment reminders, default recipient/subject/text, resend behavior, and a hard prerequisite (2-Step Security) that stops the call before approval. This gives the agent a complete behavioral picture.

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 opening sentence front-loads the core action, but the second sentence partially repeats the approval/email flow, adding some redundancy. Overall it remains readable and appropriately sized.

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

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

For a state-changing, external-send tool with no output schema, the description covers the key prerequisites, side effects, and defaults. It could mention what a successful call returns or error behavior beyond the 2-Step Security stop, but the gaps are minor.

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

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

Schema coverage is 80% and already documents the default behavior for to, message, and subject. The description repeats those defaults but adds no further parameter semantics, and send_me_a_copy remains undocumented in both schema and description.

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

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

The description states a specific verb (approve and email) and resource (invoice), including side effects like payment reminders. It does not explicitly differentiate from close siblings such as send_quote, leaving that inference to the 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 implies usage—approve a draft invoice and email it, with resend allowed—but offers no explicit when-to-use or when-not-to-use guidance relative to alternatives like send_quote or record_payment. It does note the 2-Step Security prerequisite, but does not 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 declare non-read-only, non-idempotent, destructive, open-world, but the description adds what those hints cannot: the state transition to 'awaiting acceptance', that mail is sent from Tradify, that partial failure is possible (the call stops before approving when 2-Step Security is absent), and that repeat sends are permitted despite idempotentHint=false. That is exactly the behavioral context an agent needs before invoking a real-world email send.

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

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

Front-loaded with the action and outcome, followed by the operational details (defaults, re-send, security prerequisite). The second sentence restates the accept/decline link slightly, but that minor overlap is offset by the density of unique information per sentence.

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 and an external email side effect, the description covers state change, delivery channel, defaults, and the blocking prerequisite. It stops short of describing what the call returns on success or failure, which would complete the picture.

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

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

Schema coverage is 80%, so the baseline is 3, and the description usefully explains default resolution for `to` (customer's email), subject, and message (quote email template). It does not explain `send_me_a_copy`, which is undocumented in both schema and description, keeping it below a 5.

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 opening sentence states a specific verb pair (approve + email) on a specific resource (quote), including the customer-facing accept/decline link. This is unambiguously distinct from siblings like create_quote (drafting) and send_invoice (different document type).

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 concrete preconditions: the quote must be a draft that gets approved, re-sending an already-approved quote is allowed, and sending only works when the login has 2-Step Security set up (otherwise the call aborts before approving). No sibling tool is named as an alternative, but no reasonable alternative exists for this action, so the guidance is effectively complete.

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

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

Adds real context beyond the annotations: 'It reaches no one' discloses that no notification is sent, and 'one more call sets it back' discloses reversibility, which sharpens the destructiveHint=false/idempotentHint=false signals. Minor gap: nothing about validation failures for unknown custom status names.

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 verb and short enough to scan, but the first two sentences restate the same idea ('Set a status on a job' / 'Sets a job's status'), costing a sentence that could carry new information.

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

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

For a 2-param mutation tool with no output schema and full annotation coverage, the description covers what it changes, how to express custom values, absence of side effects (no notifications), and reversibility. 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 baseline is 3; the description earns above that by explaining how custom statuses are spelled ('spaces as underscores') and pointing to Settings > Jobs > Job Statuses as their source, which the schema does not say.

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 ('Set a status on a job') plus the scope (built-in or custom statuses). No sibling tool touches job status mutation, so the description makes the tool's role unambiguous without needing to name a competitor.

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?

Anchors usage to the equivalent UI action ('as Change Status on the Jobs list does'), which tells the agent this is the sole mutation path for status. It does not state prerequisites (e.g. required permissions or whether the job must exist / be in a particular state), so it stops short of explicit when-not guidance.

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