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

Annotations declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the description needn't restate mutability. It adds real behavioral context beyond that: the existing-job precondition, the unitPrice-overrides-catalog rule, and the name-based catalog-matching fallback when price is omitted. It does not mention that repeated calls are non-idempotent and will add duplicate lines, a notable gap for a write tool with idempotentHint=false.

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

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

Three tightly written sentences, front-loaded with the action and scope, then the alternative routing, then the price-handling rule. No filler or repetition of the title.

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

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

Covers the action, routing, and the key pricing ambiguity for a moderately simple 3-parameter tool whose schema is fully documented. It stops short of describing what the call returns or the non-idempotent duplicate risk, which are the only real omissions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the precedence behavior between unitPrice and catalog name matching that goes slightly beyond the field-level text. It does not explain how jobId and customerName interact for identifying the target job, though the schema covers both.

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 ('Add billable line items to an EXISTING job') and immediately scopes it against the sibling create_job path. The 'EXISTING' emphasis plus the sibling reference lets an agent distinguish it from create_job without opening either schema.

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

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

Gives an explicit when-to-use trigger with a concrete user utterance example ('add a $50 cable management charge to the Smith job') and names the alternative tool plus its condition for new jobs. Both the positive and negative cases are covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds meaningful context beyond that: cancellation is a status change to CANCELED and 'No data is deleted,' clarifying that the destructive hint does not mean data loss.

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

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

Three short sentences, front-loaded with purpose, then side effect, then parameter routing. Every sentence carries distinct information with no redundancy or filler.

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

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

For a cancel mutation with annotations and no output schema, the description covers purpose, side effect, and parameter routing. It omits what happens if neither identifier is supplied (required list is empty) and does not mention the close_jobs alternative, leaving a small gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: customerName resolves to the most recent scheduled job (fuzzy lookup) while jobId is an exact match, and it frames the two as alternatives (OR). This goes beyond the schema's terse per-parameter notes.

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 ('Cancel a scheduled job') plus the mechanism ('setting its status to CANCELED'), so the agent knows exactly what happens. It does not distinguish itself from siblings such as close_jobs or reschedule_job, so it falls short of the top score.

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 routes the agent between the two parameters ('Use customerName when user mentions a customer'), which is useful selection guidance, but never says when to cancel versus close_jobs or reschedule_job. Usage is implied rather than explicitly scoped against alternatives.

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

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

Annotations already cover the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false), so the bar is lower, and the description still adds a genuinely non-obvious behavioral fact: the tool resolves and closes jobs in a single step rather than requiring a prior lookup. It stops short of saying whether the change is reversible or what happens when a customer name matches multiple jobs, which matters for a destructive operation.

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?

Lead sentence states the action, followed by usage triggers and examples, then the get_jobs exclusion - a sensible front-loaded order. The three example phrases are near-duplicates of the trigger list and could be trimmed without loss.

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 a full schema, no output schema, and annotations carrying the destructive flag, the definition gives an agent enough to route and call correctly. It leaves open behavior a destructive tool should clarify: precedence when multiple of date/jobIds/customerName are supplied, and whether ambiguous customer matches close nothing or everything.

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

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

Schema description coverage is 100%, so each parameter's role and required-when condition is already documented in the schema. The description restates the date/customerName usage patterns and adds no new format, precedence, or mutual-exclusivity rules beyond what the schema provides, so this is the baseline 3.

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

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

States a specific verb+resource with scope ('Mark jobs as complete/done'), and the phrasing distinguishes it from read-oriented siblings like get_jobs and other mutations like cancel_job and reschedule_job. An agent can identify the operation without opening the schema.

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

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

Explicitly enumerates trigger phrasings ('close jobs, complete jobs, mark jobs done, finish jobs') and supplies concrete examples. It also names the alternative path and rules it out: 'Do NOT use get_jobs first - this tool finds and closes jobs in one step.'

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description does not need to restate that. It adds one genuinely useful data-model fact — that catalog is the sole store for pricing — but says nothing about duplicate-name handling, required permissions, or what is returned after creation.

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

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

Three short sentences, front-loaded with the action and resource before the usage trigger. The only mild redundancy is that 'with pricing' and 'the ONLY place to store pricing information' restate the same idea, costing a little space without adding 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 6-parameter create tool with full schema coverage, annotations covering the safety profile, and no output schema to explain, the description supplies purpose and trigger condition. Nothing critical to correct invocation is missing, though duplicate-handling rules would have been a nice extra.

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%, and every property (cost, name, price, itemType, isTaxable, description) already carries its own description and example, including the enum semantics for itemType. The prose adds no field-level meaning beyond that, so the baseline 3 applies when the schema does all the work.

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 and resource — 'Add a new service or product to the catalog with pricing' — so an agent immediately knows this creates catalog/pricing entries. It implicitly separates itself from line-item or estimate tools by declaring this is 'the ONLY place to store pricing information,' but it never names a sibling such as add_line_items, so the differentiation is indirect rather than explicit.

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

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

'Use when user mentions pricing for services/products' gives a concrete trigger condition, and the 'ONLY place to store pricing' line frames it as the canonical path for pricing data. There is no when-not guidance, no mention of required prerequisites (e.g., an existing business/profile context), and no named alternative for cases where the user is pricing a one-off job line rather than the catalog.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation/non-idempotency profile is covered. The description adds the notable behavioral boundary that no job is created, but is silent on the tool's first-pass behavior of reporting duplicate customers and prompting for createAnyway — a significant trait that lives only inside the parameter 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?

Three short sentences, front-loaded with the core action before the routing rule. No filler, though the final extraction sentence is closer to an instruction than a definition and could be trimmed without loss.

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-param create tool with full schema coverage, annotations and no output schema, the description does the important jobs: it disambiguates from create_job and hints at which fields to capture. The duplicate-reporting workflow is delegated entirely to the schema, which is the only real gap.

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

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

Schema coverage is 100%, so every parameter including the non-obvious createAnyway flow and the source/'never guess' rule is already documented in the schema; baseline 3 applies. The description's 'Extract ALL contact details the user provides (name, phone, email, address)' mildly reinforces which optional fields to populate but adds no syntax or format detail 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?

Specific verb+resource ('Add a new customer') with an explicit scope qualifier ('without scheduling a job') that immediately distinguishes it from create_job, the closest sibling in the tool list. An agent can route to it 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?

Names the alternative and the exact condition that selects it: 'For new customers WITH a job, use create_job instead — it handles creating the customer inline.' It also instructs what to do with the incoming message (extract all contact details), closing the loop on usage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds meaningful behavior beyond that: the price-resolution logic (custom price overrides catalog) and the rule for constructing flat-rate line items. It still doesn't say what the tool returns or whether the estimate is sent to the customer, 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?

Three sentences, front-loaded with the core action, then the pricing rules. No filler and each sentence earns its place, though the pricing elaboration could be slightly tighter.

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 create tool with 7 fully-documented params and no output schema, the description covers the tricky pricing decision logic well. It leaves gaps around the customer-resolution flow and what the tool returns, but those are partly handled by the schema (createNewCustomer) and are not strictly required.

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 adds concrete usage examples for lineItems/unitPrice ('total $250', 'charge $300 flat') and the single-line-item convention for flat rates, which meaningfully extends what the schema states about the same fields.

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

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

States a specific verb+resource: 'Create an estimate/quote for a customer.' This is unambiguous against the read siblings (get_estimates) and other create siblings (create_job, create_invoice). It doesn't explicitly differentiate itself from those create siblings, so it stops short of a 5.

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

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

Gives explicit conditional guidance for the pricing path: use a custom unitPrice when a flat rate/custom price is stated, and only fall back to catalog pricing when no price is given. It does not, however, say when to choose create_estimate over create_job or create_invoice, so it lacks the alternative-tool routing a 5 would require.

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 write/non-destructive/non-idempotent/openWorld=false, so the safety profile is covered; the description adds real behavioral context beyond that: events cannot create new customers, blocksAvailability defaults to true, and an omitted duration falls back to the account default. It does not say what is returned or how duplicate creation is handled, which is a minor gap for a non-idempotent create.

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

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

Front-loads the critical disambiguation ('NOT a job') and the create_job contrast before the softer details. The trigger-phrase enumeration and the trailing date-parsing sentence are slightly redundant with the schema's date description, but nothing is wasted or buried.

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 the key gaps an agent would otherwise hit for an 11-parameter create: the not-a-job boundary, optional customer/crew linkage, all-day vs timed handling, and default duration/availability behavior. With no output schema it would help to state what the tool returns (e.g. the new event id) so it can be referenced afterward.

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, but the description adds cross-cutting parsing semantics for date/time ('pull the date and time from anywhere in the message', resolve relative dates via the DATE REFERENCE) and clarifies that customerName/crewMemberName must reference existing records. That is meaningfully more than the per-field schema text.

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 specific verb (add) and resource (calendar event) and immediately scopes it as 'NOT a job', naming the sibling create_job as the alternative for billable work. An agent can route between create_event and create_job from the description 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?

Explicit when-to-use with concrete trigger phrases ('event', 'block off', 'time off', 'meeting') and an explicit when-not plus the named alternative (create_job for billable customer work). Also covers the linking case (optionally tied to a customer and/or crew member).

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

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

Annotations already declare this is a write, non-idempotent, closed-world operation with destructiveHint=false. The description adds substantial behavioral context beyond annotations: it creates both customer and job in one step, validates source against existing job sources and retries with valid options, and gates createNewCustomer behind a prior confirmation step.

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 dense sentences, front-loaded with the primary action and then the most important edge cases: date/time extraction, relative-date resolution, and new-customer handling. Every sentence carries invocation-relevant 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 complex 12-parameter creation tool with no output schema, the description covers the critical invocation behaviors well. It does not explain the success/return shape or broader error handling beyond the source-mismatch retry, so a small completeness gap remains.

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 parameter documentation is already thorough. The description repeats date/time extraction guidance that is also present in the schema and does not add new parameter-level semantics beyond that repetition.

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

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

States a specific verb+resource: 'Schedule/create a new job for a customer.' It also distinguishes the tool from create_customer by explicitly saying new-customer details should be passed here and that create_customer should NOT be called separately.

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

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

Gives explicit when-to-use and when-not-to-use rules: use ONLY this tool when the user says 'create customer X and schedule a job,' do not call create_customer separately, and only ask for date/time when none appears in the message. The alternative path is named and excluded.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description is not obligated to restate them. It adds real behavioral value by disclosing that returned dates are resolved in the business's own timezone and week-start convention, and that catalog/jobSources are authoritative inputs for other tools. It does not mention caching or refresh semantics, keeping it short of a 5.

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

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

It is a single long paragraph, but nearly every clause carries actionable content and the return inventory is front-loaded. The two imperative directives ('Call this FIRST', 'Also call it BEFORE') are slightly buried mid-paragraph rather than leading, which is the only structural flaw.

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 must describe return values — and it does so exhaustively, down to the exact list of relative-date keys and their format. Combined with the call-ordering guidance, an agent has everything needed to invoke this correctly and consume its output.

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

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

The tool takes zero parameters, which is the baseline-4 case; there are no arguments to disambiguate. The description's explanation of returned fields is a bonus rather than a deficit.

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 and then enumerates exactly what it returns: business name, timezone, working hours, catalog, lead sources, and resolved date ranges. An agent can immediately tell this is a foundational context/reference tool rather than a data-mutating sibling like create_job or get_jobs.

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

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

Gives explicit, prioritized when-to-use rules: call FIRST for any relative date, call BEFORE creating a job/estimate/line items. It also names the alternative behavior to avoid (computing dates yourself) and routes outputs to specific sibling arguments (dateFrom/dateTo, create_job's source). This is about as prescriptive as usage guidance gets.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no note on pagination, result caps (the schema handles the 100 max), or what a customer record contains.

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 written sentences with the core purpose front-loaded and no wasted preamble. The phrase 'customer-related questions' is slightly vague filler, keeping it just under a 5.

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?

The tool is simple, fully-documented in the schema, and safe per annotations, so little is strictly required. However, with no output schema, the description could usefully hint at what a customer result contains (name, contact, stats), which it does not.

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%, with every parameter (limit, query, includeStats) documented including defaults and max values. The description adds no parameter meaning beyond what the schema provides, 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?

States a specific verb ('search or list') and resource ('customers'), making the operation unambiguous. It doesn't explicitly contrast itself with the sibling create_customer, but the read-vs-write distinction is apparent from the verb.

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 usage contexts ('customer lookups, finding contact info, or customer-related questions') that tell the agent when to reach for this tool. It stops short of naming an alternative or stating exclusions, so it falls 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe repeated read operation. The description adds no behavioral details beyond annotations, such as return format, ordering, or pagination behavior. With annotations covering the safety profile, a 3 is the minimum viable score.

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

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

Two short sentences with no waste. The primary action is front-loaded and the usage scenarios are compact. Every sentence earns its place.

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

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

For a simple read-only list tool with rich annotations and full schema coverage, the description covers purpose and typical use cases adequately. It does not mention return shape or pagination, but no output schema exists and the parameter schema already documents filtering behavior, so the gap is 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 description coverage is 100%, so the schema already documents all five parameters, including enum values and the dateFrom default behavior. The description adds no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a clear verb and resource: 'Fetch estimates/quotes.' This distinguishes it from creation siblings like create_estimate and from other resource-based siblings (jobs, invoices, customers). However, it does not explicitly name or contrast with alternatives, so it stops short of the clearest possible differentiation.

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

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

Provides concrete use contexts: pending proposals, conversion tracking, estimate follow-ups. It tells the agent when this tool is relevant but does not specify when not to use it or name an alternative tool for adjacent tasks.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that — nothing about result volume, pagination behavior, or what the default limits mean in practice. It does not contradict the annotations, but it contributes essentially nothing behavioral.

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

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

Two short sentences, front-loaded with the core action before the use cases, with no filler or repetition of the title. It is appropriately sized for a simple list tool, though the second sentence is a loosely packed list of scenarios rather than precise 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 read-only, non-destructive list operation with fully documented parameters and clear annotations, the description is minimally sufficient. With no output schema, the agent still learns nothing about the shape of returned invoice records or whether results are paginated, which is a real but modest gap for a listing tool.

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

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

Schema description coverage is 100%: each of the six parameters has its own description, including the DATE REFERENCE warning on dateFrom and the default/max on limit. The description adds no syntax, format, or filtering semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch invoice records') that clearly identifies a read of invoice data. However, it never distinguishes itself from adjacent read tools in the sibling set such as get_payments, get_estimates, or get_line_items, so an agent must infer the boundary. Clear but undifferentiated.

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 offers intended scenarios ('billing questions, unpaid balances, invoice status tracking'), which is implied usage guidance rather than explicit routing. It names no alternative tool and gives no when-not condition, so an agent choosing between this and get_payments or get_estimates gets no help.

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/safe, so the bar is low, but the description adds real value by disclosing the return shape contract: 'Returns raw job data - you calculate totals, counts, and comparisons.' That tells the agent not to expect aggregation, which is not derivable from the annotations.

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

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

Two short sentences, imperative and front-loaded, with the most important behavioral caveat (raw data, no aggregation) placed last where it has impact. The opening clause 'Use for any question about jobs' is slightly overbroad but not 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?

For a read-only, single-resource search tool with no output schema, the description covers purpose, usage, and return semantics well enough to call it correctly. It is less complete about result ordering/pagination beyond the limit field and about how it relates to get_schedule.

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% with self-documenting parameters (limit defaults/max, enum values, date formats, the non-obvious jobSourceId semantics), so the schema carries the burden. The description adds no parameter-level meaning beyond it, which is the baseline 3 case.

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 ('Fetch job records') with a scope qualifier ('with filters'). It is clearly distinguishable from mutation siblings like create_job, close_jobs, and cancel_job, but it does not explicitly differentiate itself from the read siblings (get_schedule, get_reference_data).

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 broad usage cue ('Use for any question about jobs, work performed...'), which is implied guidance rather than explicit when/when-not. Naming 'schedules' as in-scope is risky given the sibling get_schedule exists, and no alternative tools are named or excluded.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds intent framing but nothing about return shape, pagination behavior, or size of payloads, so it earns only a modest amount of extra credit.

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

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

Two tight sentences with zero filler: the purpose leads and the use-case list follows. Every clause earns its place and nothing is repeated.

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 five schema-documented parameters, rich annotations, and no output schema, the description covers purpose and usage adequately. It leaves minor gaps around result volume or ordering, but 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 description coverage is 100%, with each of the five parameters documented including enum values and defaults, so the schema carries the parameter burden. The description adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb (Fetch) plus the resource (line items from jobs) and even clarifies the domain meaning with '(services/products sold)'. This makes the concept concrete, though it does not explicitly contrast itself with the sibling add_line_items or get_jobs, so the differentiation relies on the reader's inference.

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

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

The second sentence lists concrete analytical use cases ('which items make money, most popular services, item profitability, catalog usage'), giving an agent clear context for when to reach for this tool. It stops short of naming exclusions or an alternative sibling, so no when-not guidance is provided.

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

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

Annotations already declare the safe read-only profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuinely non-obvious behavior: it returns raw rows with no aggregation, so the agent must sum and analyze itself — that shapes how the result is used.

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

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

Three short sentences, no filler, and the identity of the tool is front-loaded before the use cases and the return-volume caveat. Every sentence 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?

For a read-only list tool with a fully described schema and no output schema, the definition covers purpose, usage context, and the shape of the return (raw, unaggregated). Pagination behavior beyond the limit param and the payments-vs-invoices distinction are the only omissions.

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%, and the schema already documents every filter including the DATE REFERENCE guidance for dateFrom, so baseline 3 applies. The description contributes nothing about parameter semantics or defaults beyond what the schema states.

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

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

States a specific verb and resource ('Fetch payment records') and names concrete use cases (revenue questions, income tracking, payment history). It does not, however, draw a boundary against the nearby get_invoices or get_line_items siblings, which overlap on 'revenue questions', so an agent could still face ambiguity.

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 positive context for when to reach for this tool rather than a generic data-fetch. There are no explicit exclusions or named alternatives (e.g. 'use get_invoices for billed amounts'), so routing against the closest sibling is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so an agent knows the safety and repeat-call profile without the description. The description usefully conveys that these are static lookup tables, but adds nothing on auth, caching, or the shape/size of results, so with the annotation bar already lowered this is adequate but not rich.

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

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

Two short sentences: what it returns first, when to use it second. Every clause carries information (the three table names, the three use cases) and 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 read-only lookup tool with full annotation coverage, a 100%-documented schema, and no output schema required to be explained, the definition covers purpose, contents, and triggers. The only minor gap is that it does not describe the returned record shape (id/name pairs), which an agent might reasonably want before calling 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 100%, so all three parameters (types, search, includeArchived) are already documented in detail, including the unusual 'catalog marked incomplete' workflow for search. The description's 'map IDs to names' hints at a use for types but adds no syntax or format detail beyond the schema; 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?

Starts with a specific verb+resource ('Fetch lookup tables') and enumerates exactly what is returned: job types, job sources, catalog items. This cleanly separates it from sibling data-retrieval tools like get_jobs, get_customers and get_business_context, which return transactional or business records rather than reference data.

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 second sentence gives concrete trigger conditions: knowing what types/sources exist, catalog pricing, or mapping IDs to names. That is clear context for selecting the tool, but it names no alternatives or exclusions (e.g. when to prefer get_business_context for catalog-is-incomplete situations), so it stops short of 'when-not' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that availability is optionally calculated rather than always returned, but says nothing about output format, ordering, or whether empty slots are included.

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

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

Two tight sentences with zero waste; the returned content is front-loaded and the usage cues follow immediately. Nothing redundant to the title or annotations.

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

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

With no output schema, the description still names what is returned, and annotations plus a fully documented schema cover the rest. Only minor gaps remain around return shape and ordering, which an agent could reasonably 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 description coverage is 100%, so all three parameters are already documented, including the availability toggle and date constraints. The description adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb ('Get') and enumerates the exact resources returned: scheduled jobs, calendar events (time off, meetings, walkthroughs), and optional availability. This is far more specific than a generic 'get schedule', though it does not explicitly distinguish itself from a sibling like get_jobs.

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

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

Gives concrete usage triggers ('what's on the calendar', 'when am I free', scheduling questions), which clearly signals the intended context. It stops short of naming alternatives or stating when not to use it versus get_jobs or create_event.

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 state this is a non-read-only, non-idempotent mutation (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the agent knows it's a write with side effects. The description adds the important resolution rule that customerName finds the most recent scheduled job, which is behavioral context beyond the schema. However, it doesn't mention permissions, reversibility, or error modes, leaving some gaps.

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 identification rules, then moves to parameter usage and a concrete example. It is a bit long, but every sentence appears to serve a purpose (e.g., the durationMinutes example clarifies an edge case). No redundant or filler content.

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

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

Given the mutation nature, five optional parameters, no output schema, and annotations that signal non-destructive write, the description is nearly complete. It covers identification, required inputs, and special cases (duration-only updates). It could mention what happens on ambiguous customer matches or how errors are returned, but those are minor for a tool at this scope.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description reinforces the mutual exclusivity and usage patterns (e.g., customerName vs jobId, durationMinutes alone) but does not add syntax or format details beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description states a specific verb and resource (change the date, time, or length of an existing job) and names the updatable aspects. It distinguishes this from siblings like create_job (new job) and cancel_job (removal), making the boundary clear.

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

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

Explicitly tells how to identify the job (customerName finds most recent scheduled job, jobId for exact match), requires at least one of newDate/newTime/durationMinutes, and gives specific examples for when to use each mode. It also names the alternative pattern (durationMinutes alone) for pure length changes.

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 non-readOnly, non-idempotent, non-destructive. The description adds value beyond them by disclosing where the value lives (on the customer, not the job) and that every booked job counts toward that source—semantics an agent cannot get from annotations. It stops short of describing overwrite behavior for an existing source or any error conditions.

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

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

Two short sentences, front-loaded with the action and followed by the one piece of scope context that matters. No filler.

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

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

For a two-parameter mutation with no output schema, the description plus schema covers what an agent needs to invoke it correctly. Minor gaps remain about error behavior for an invalid source and whether an existing source is replaced or appended.

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%; sourceName even points to get_business_context jobSources and get_reference_data. The description adds no syntax or format detail beyond the schema, so the 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 names a specific verb+resource (set the customer's lead source) and clarifies the scope as customer-level attribution rather than job-level, which helps separate it from job-oriented siblings. It doesn't name an explicit alternative tool, so it falls just short of a 5.

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

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

Usage is only implied: the reader infers this is the tool for assigning or correcting a customer's attribution. There is no explicit when-to-use vs. when-not, no prerequisites, and no routing to a sibling for the job-level equivalent.

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