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

Annotations already declare that this is not read-only, is open-world, and is not idempotent. The description adds useful behavioral context: items are appended to the first section, the app computes totals, and the result includes saved items plus the new total. It does not discuss permissions or error behavior, but the annotations carry the safety profile.

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 with no filler. The core action and scope are front-loaded, followed by item details and return behavior.

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 annotations and no output schema, the description covers what is added, where it is added, that totals are computed, and what is returned. Minor omissions like item limits or error conditions are handled by the schema or are not essential for correct invocation.

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

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

Schema description coverage is 50%, so the description should compensate more than it does. It names most item fields and the allowed type values, which is helpful, but it omits the cost_code_id and description fields and does not clarify top-level parameters beyond their schema descriptions.

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

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

States a specific verb and resource: adds priced line items to a change order or change order request. It is clearly distinguishable from generic change-order tools, but it does not explicitly contrast with sibling item-adding tools such as add_estimate_items or add_invoice_items.

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 usage context is implied by 'adds line items at the end of the change order's first section,' but there is no explicit when-to-use guidance, prerequisites, or alternatives. An agent can infer this is for adding items to an existing change order, but the description does not route it against siblings.

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

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

Annotations declare the safety profile (mutating, non-destructive, non-idempotent, open-world), and the description usefully adds that items are appended rather than replacing anything and that the server computes totals and returns both the saved items and the new estimate total. This is genuine value beyond the annotations; it doesn't cover permission prerequisites or behavior against a locked/sent estimate.

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, purpose first, then mechanics and return value. No filler, no restatement of the schema's defaults and enums that would waste tokens.

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 3-parameter mutation with no output schema, the description covers purpose, insertion behavior, field meanings, ID provenance, and what comes back. The remaining gap is operational edge cases such as item limits, locked estimates, or partial-failure behavior, which an agent might want before calling.

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 67%, so the description has real work to do, and it does it: it enumerates the meaningful item fields, clarifies that unit_cost is the agent's cost in dollars while markup is applied server-side to produce totals, and ties cost_code_id and section_id to their source tools. The nested item object is the crux of the call and it is described accurately.

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 ('Adds priced line items to an existing estimate') and scopes it to existing estimates. An agent can distinguish it from siblings like add_invoice_items or add_change_order_items purely by the resource named, 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?

Explains the insertion point ('at the end of an estimate section (the first one unless section_id says otherwise)') and where prerequisite IDs come from (cost_code_id from list_cost_codes, estimate_id from list_estimates/create_estimate). It gives clear context but never names exclusions or alternatives, e.g. that update_estimate is the tool for editing existing items.

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 mutation, non-idempotent, non-destructive, open-world. The description adds real value beyond them: it discloses append-to-end semantics ('at the end of an invoice') and the response payload (saved items, new total, balance due), which matters because there is no output schema. It does not warn that retries duplicate items (only implied by idempotentHint=false), which keeps it off 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 short sentences, front-loaded with the action and followed by scope and return values. The item-field enumeration partially repeats the schema, but it is compact enough to justify its space.

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 correctly covers returns, and with 50% schema coverage it covers most item fields plus the append behavior. Only the undocumented cost_code_id/description fields and duplicate-on-retry behavior are left unaddressed, which are minor given the annotations.

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 50%, so the description needs to carry weight; it enumerates item fields (name, type, quantity, unit, unit cost in dollars, markup percent), which helps, but omits cost_code_id and the per-item description field and adds no syntax beyond the schema. Adequate but leaves gaps at a borderline coverage level.

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 (add priced line items to an invoice) and scopes it to 'plain priced lines,' explicitly noting that estimate / change order / schedule-of-values items are added in the app rather than here. That indirectly but effectively separates it from sibling tools like add_estimate_items and add_change_order_items.

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 condition for what belongs here ('plain priced lines at the end of an invoice') and an exclusion ('Items billed from an estimate, change order or schedule of values are added in the app'). It does not name alternative siblings directly or discuss when to use update_invoice instead, so it stops short of a full 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 establish mutation and open-world behavior, while the description adds concrete visibility ('company's users with access'), notification behavior ('Nobody is notified'), actor ('signed-in user'), and return value ('saved note'). It omits permission scopes and duplicate/rate-limit behavior, so it is strong but not exhaustive.

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 and generally concise. The first sentence largely duplicates the second ('Adds a note...' / 'Writes a note...'), which is a minor redundancy.

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

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

For a simple mutation tool with annotations but no output schema, the description covers purpose, visibility, notification, actor, and return value. Missing duplicate handling or edit restrictions are modest gaps.

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 33%; only project_id has a schema description. The prose mentions an optional title but does not explain text body semantics or limits, and does not compensate for the low schema coverage.

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

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

The description uses a specific verb and resource: 'Adds a note to a project's Notes tab.' The write operation is unmistakable, though it does not explicitly name the read sibling list_project_notes, so sibling differentiation is implicit rather than stated.

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?

No explicit when-to-use, when-not-to-use, or alternative tools are named. Visibility and notification details describe behavior, but they do not route the agent between add_project_note and list_project_notes or other note-related actions.

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 write/safe/idempotency profile, and the description adds genuinely new behavioral facts: the bill starts in Open status, nothing is paid or sent, and it returns the saved bill. It does not mention prerequisites such as the vendor record existing or any permission requirements, so a 4 rather than 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 one-line summary before the detail, and no filler. Mild redundancy between the opening sentence and the more specific second sentence keeps it from 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?

For an 8-parameter mutation with no output schema, the description covers the important unknowns: what the call creates, its initial state, and that it returns the saved bill. Missing are prerequisite notes (vendor must pre-exist) and any indication of failure modes, which keeps it just under complete.

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

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

At 75% schema coverage the schema does much of the work, but the description reinforces the non-obvious mappings ('the vendor's invoice number' for number, the line-item fields including cost type) and explains the consequence of project_id on job costing, which the schema only states flatly. It does not clarify defaults like bill_date=today beyond what the schema provides.

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 first sentence names a specific verb and resource ('Records a vendor bill with its line items, optionally against a project'), and the second expands on the exact payload. It never explicitly distinguishes itself from the sibling create_invoice, which is the nearest ambiguity, 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?

Usage is implied by 'Enters a bill from a vendor in Contractor Foreman' and by the note that supplying project_id routes the cost into job costing, which is real selection context. There is no explicit when-not-to-call or named alternative (e.g. create_invoice for customer-side billing, create_expense for non-vendor costs), so routing remains inferred.

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 write/safe/non-idempotent profile, and the description adds real context beyond them: the resulting status (open for change orders, draft for requests), that the app computes the total, and that nothing is emailed. It does not address duplicate-number behavior despite idempotentHint=false, which is the one meaningful gap.

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 core action and the no-send guarantee are front-loaded in the first two sentences, and the total length is appropriate for a seven-parameter create tool. The middle sentence about items is a dense parenthetical list that is slightly run-on but still readable.

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 nested line items and no output schema, the description covers the important semantics: what gets created, what status it lands in, how totals are derived, and that nothing is dispatched. The only missing piece is what the call returns (presumably the created change order with computed total), which an 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 a moderate 71% and the description largely restates what the schema already says about items (name, type, quantity, unit, unit cost in dollars, markup percent, cost code). The one genuine addition is 'description records the reason', but parameters like date, number, and kind are already documented in-schema, so this sits at the baseline.

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

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

The opening sentence gives a specific verb (creates) and resource (change order / change order request) with the key qualifier 'with line items'. The second sentence distinguishes the two variants by resulting status (open vs draft), and the closing sentence names the two adjacent tools (send_change_order, update_change_order) so an agent can place this tool in the workflow 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?

The last sentence explicitly routes the agent: 'Nothing is sent. send_change_order emails it after your OK, update_change_order sets the status' — a clear statement of what this tool does not do and which sibling does it. However there is no explicit guidance on prerequisites (project must exist, cost codes must be listed first) or exclusions beyond the send/update split.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing that the created record has no app access, no invitation email is sent, and login provisioning is out of scope. It also states the return value ('Returns the new contact_id'), which matters because no output schema exists.

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

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

Five tight sentences, front-loaded with the core action and followed by requirements then side-effect exclusions. 'Creates a Contractor Foreman Directory record as the Add drawer does' slightly restates the opening sentence but it establishes the UI-equivalence context.

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 non-idempotent mutation with no output schema, the description covers what is created, what is not created (access/invites), conditional field requirements, and the return value. It does not address duplicate handling despite idempotentHint=false, which is the one remaining 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?

With only 17% schema coverage across 12 parameters, the description compensates by spelling out the type-conditional requirements: employees need first and last name, contractors and vendors need a company name, others need a name or a company. That is the single most error-prone part of the call. The address/phone/email fields are left unaddressed, but they are self-explanatory.

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 ('Adds a ... contact to the Directory') and enumerates exactly which contact types are supported, matching the schema enum. An agent can immediately tell this is the create-side counterpart to get_contact/list_contacts 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?

Explains the operational context ('as the Add drawer does') and, importantly, the boundary conditions: no app access is granted, nobody is invited or emailed, and granting a login remains a separate step in the app. It does not explicitly name alternative tools, which keeps it from 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 non-readonly, non-destructive, open-world, non-idempotent, and the description adds real behavior: default arrival of 07:00, weather auto-recorded from the date/address, the notes non-empty constraint, and the visibility scope ('reaches no client or crew') that justifies running without confirmation. This is context beyond the annotation flags.

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?

Purpose is front-loaded in the first sentence and every sentence carries information (defaults, constraints, alternatives). It is dense and slightly run-on, packing several facts per sentence, but no line is wasteful.

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

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

For a 12-parameter creation tool with no output schema, the description covers return contract ('returns it as get_daily_log shows it'), required-field constraint, defaults, side effects (system weather recording), and visibility. Nothing an agent needs to call 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, but the description adds value the schema lacks: the 07:00 default for arrival_time, the notes-must-not-be-empty constraint, the headcount-per-crew-or-free-text shape of people, and that weather_notes sits beside the system-recorded weather. Only modest gaps (no format hints for delay fields) remain.

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 ('New daily log on a project') and enumerates the content it captures. It distinguishes itself from get_daily_log, update_daily_log, and list_daily_logs by name, so an agent can tell which daily-log tool to pick without opening schemas.

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 precondition ('check list_daily_logs first' since one project can have several logs on one date) and an explicit alternative ('update_daily_log can edit it'). Both the when and the why-not are named.

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

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

Beyond the annotations, the description discloses that the estimate is saved as a draft in Estimating status, uses unit-price billing, is dated today, and has totals computed by the app. It also clarifies that nothing is sent until send_estimate is invoked, which is important behavioral context for a create 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?

The description is front-loaded with the core action and then efficiently covers status, billing, required relationships, item structure, and next-step tools. There is no wasted text, and each sentence adds useful context.

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 annotations and no output schema, the description covers most critical behavior: draft status, billing mode, date, totals computation, and no automatic sending. It could be slightly more complete by indicating what is returned after creation or how the new estimate id is used, but the overall context is strong.

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 description adds useful meaning for the core inputs: items are priced lines with name, type, quantity, unit, unit cost, markup, and cost code, and project_id versus customer_id is explained. However, with schema description coverage at 38%, several optional parameters such as exclusions, inclusions, expire_date, and the required title are not clarified in the 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 gives a specific verb and resource: creates a draft estimate on a project or for a customer, with priced line items. It clearly distinguishes this from send_estimate, add_estimate_items, and update_estimate by describing their separate roles.

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

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

It explicitly states the project_id versus customer_id rule and names the alternative tools for sending, adding lines, and updating fields. The agent knows when to use this tool and when to use siblings instead.

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, idempotentHint=false, so the safety profile is known. The description adds genuinely non-obvious behavior: the expense feeds the project's job costing (a downstream side effect), the project is hard-required and rejected without one, the actor is the signed-in user, and no receipt file is attached. It does not address duplicate creation despite idempotentHint=false, which is the one material gap.

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 leading sentence is front-loaded with verb, resource and key fields, and the second sentence carries the behavioral detail. There is some duplication, since the field list appears in the first sentence and is re-enumerated in the second, but the total length is reasonable for an 8-parameter mutation.

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 non-idempotent create with 8 params and no output schema, the description covers the essentials: required project, actor identity, job-costing side effect, absence of receipt upload, and an explicit return statement ('Returns the saved expense'). Remaining gaps are duplicate handling and post-creation editability.

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%, so the schema already carries most parameter meaning (currency, enum values, vendor_id -> contact_id, project_id requirement). The description mostly restates the field list ('name, amount, date, vendor, project, cost type, reason and whether it is billable') rather than adding semantics beyond it; only 'no receipt file is attached' clarifies an absent field.

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 ('Records an expense') and enumerates the domain fields (receipt, purchase, fee; amount, date, vendor, project), so the agent knows this is a create operation aimed at cost entry, not a listing or retrieval. It does not explicitly contrast with create_bill or create_purchase_order, which are the genuinely confusable siblings in this domain, 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 useful preconditions: 'The project is required by the app' and 'No receipt file is attached', plus it runs 'as the signed-in user'. But it never says when to choose this over create_bill / create_purchase_order, which matters because all three create cost records in the same product. Usage is implied rather than routed.

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 give the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real value on top: the record is created in Draft status, no one is notified, the saved inspection is returned, and a separate tool must be called to set the outcome. Those are exactly the post-call state facts an agent needs. Minor gap: with idempotentHint=false, a note on duplicate handling would help.

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 but front-loaded with a sentence that repeats the field list that the next sentence lists again (type, date, agency, inspector, notes). That duplication is the main waste; the genuinely useful facts (Draft status, no notification, follow-up tool) are buried in the second paragraph.

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 mutation with no output schema, the description covers the important behavioral context: resulting status, notification behavior, return value, and the sibling needed to complete the workflow. The remaining gap is that one undocumented parameter (notes) is not explained anywhere.

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 67%, and the description mostly restates the field list already visible in the schema. It does add a bit of semantic gloss for agency (internal, county, city, independent agency), which clarifies the enum values. But notes has no schema description and the description supplies nothing about what belongs there, leaving the coverage gap unfilled.

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 (creates/logs) and resource (a Contractor Foreman inspection on a project) plus the identity fields that define the record. It explicitly distinguishes itself from the sibling record_inspection_result, which handles the pass/fail outcome, so an agent can pick correctly 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?

The description names the follow-up tool (record_inspection_result) and what it covers, and narrows the use case to a Draft-status inspection. It also says nobody is notified, which is useful for deciding whether an extra notification step is needed. It stops short of stating exclusions such as when to use get_inspection or list_inspections instead, but the create-vs-fetch split is fairly obvious from the names.

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 a non-read-only, non-destructive, non-idempotent, open-world write; the description adds the crucial behavior that the invoice lands in Draft and is not sent, and lays out the downstream lifecycle. It does not warn that repeated calls will create duplicate drafts (non-idempotent) or mention any limits, so it falls slightly short of full 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 core behavior is front-loaded in the first two sentences, and every subsequent sentence carries a routing rule. The later sentences are telegraphic fragments ('It is not sent.', 'send_invoice emails it after your OK.') and there is mild repetition around 'not sent'/'marks it sent', but the content density is high.

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 mutation with no output schema and no required parameters (conditional requirements instead), the description covers the draft state, the project/customer branch, line item shape, and the lifecycle to sending and payment. The main missing piece is what the call returns (e.g., the new invoice id) that later update_invoice/record_payment calls would need.

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 71%, and the description adds real meaning: the project_id/customer_id dependency, the description–due_date coupling, and the contents of each item line (name, type, quantity, unit, unit cost in dollars, markup percent). It omits number, invoice_date, and cost_code_id, so it does not fully compensate for the uncovered parameters.

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 first sentence gives a specific verb and resource ('Creates a draft invoice') plus scope ('for a project or customer, with priced line items'). It is immediately distinguishable from send_invoice and update_invoice by the explicit Draft status and 'It is not sent.'

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 the exact branching rule: with project_id the project's customer is billed; without one customer_id is required. It also names the follow-on tools (update_invoice with status submitted, record_payment, send_invoice) and the ordering constraint that description requires due_date in the same call.

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=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description still adds real value: 'Nobody is emailed' rules out a side effect the agent might otherwise assume, the default stage is called out, and the returned contact_id is named. It stops short of saying what validation happens if neither name nor company is supplied, despite the schema marking nothing as required.

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

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

Two sentences, front-loaded with the action and payload, then the behavioral caveats and return value. Nothing is repeated from the schema or annotations and no sentence is 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 twelve-parameter mutation with no output schema, the description is nearly sufficient: it explains what is created, that no one is notified, the default stage, and what is returned. The remaining gap is the 'a name or a company' constraint, which reads as a requirement but conflicts with a schema that marks nothing required, leaving the agent unsure what a minimal valid call looks like.

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

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

With 0% schema description coverage, the description has to carry the load and largely does: it groups the twelve fields into name/company, contact details, address and stage, and restates the 'received' default from the enum. It doesn't map the groups to individual parameter names (e.g. which of first_name/last_name/cell/phone counts as 'contact details'), which keeps 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?

States a specific verb and resource ('Adds a sales lead') and enumerates the payload it accepts — contact details, address, pipeline stage. It also names the sibling readers that consume the result (list_leads, get_contact), so an agent can place it in the workflow without opening another 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?

Usage is implied by 'Creates a lead in the Contractor Foreman Directory as the Leads Add drawer does', which frames the scenario, but there is no explicit when-to-use/when-not guidance. With siblings like create_contact, create_opportunity and create_service_ticket in the same space, an agent gets no routing rule for choosing this one over those.

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

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

The description adds substantial behavior beyond the annotations: it states that the record is assigned to the signed-in user, nobody is emailed, the opportunity number must be unique, a fallback number is generated from the UTC timestamp, and the saved opportunity is returned. These are exactly the side effects and postconditions an agent needs for a create operation, and none contradict 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?

The description is front-loaded with the purpose, followed by operational details and return behavior. It is appropriately sized for a create tool, though the 'Creates an opportunity ... as the Opportunities Add drawer does' sentence partially repeats the opening.

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

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

Given there is no output schema, the description usefully states that it returns the saved opportunity and covers assignment, email behavior, and numbering. It is nearly complete for the operation, with the main gap being that several of the 12 input parameters are only documented in 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 only 33% across 12 parameters, so the description needs to compensate. It helps by naming key fields, tying customer_id to the Directory, and explaining number uniqueness/default generation, but it leaves address fields, project_type, name requirements, and stage/score semantics largely to the schema.

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

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

The description opens with a specific verb and resource: 'Adds a sales opportunity' for a customer, and names the core fields stage, score, budget and expected sale date. That is enough for an agent to distinguish this create tool from get_opportunity and list_opportunities 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?

It gives clear usage context: the customer must come from the Directory, the opportunity is assigned to the signed-in user, and it mirrors the Opportunities Add drawer. It does not explicitly say when to use this instead of create_lead or another create sibling, but the context is strong enough that an agent should not confuse the use case.

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 that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds practical behavior: default status, automatic project numbering, the manual-numbering exception, no external visibility, no confirmation prompt, and that the result matches get_project. It does not reconcile the openWorldHint=true annotation, but the added context is substantial.

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

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

The description is compact and front-loads the core purpose before adding defaults, numbering behavior, safety context, and return shape. The first sentence is slightly fragmentary, but overall every sentence carries useful 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 13-parameter create tool with no output schema, the description covers the essential operational context: required customer source, default stage, numbering behavior, no external side effects, and return shape. The main remaining gap is detailed semantics for the address and date parameters, but the schema provides field names and formats.

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 only 23%, so the description must compensate, and it does add meaning for key fields: customer_id comes from the Directory, number has automatic default behavior, and status defaults to pending. It still leaves many of the 13 parameters such as address fields, dates, and description without added semantic guidance beyond the schema.

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

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

The description clearly states a specific verb and resource: it creates a new project for a customer, and it names the main data categories (number, type, stage, address, dates). It is distinct enough from siblings like update_project, but it does not explicitly contrast itself with related creation tools such as create_lead or create_opportunity.

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 useful creation context: the customer must come from the Directory, the project is created in the specified stage with pending as default, and manual-numbering accounts must supply a number. However, it does not explicitly say when to use this rather than update_project, list_projects, or other create tools.

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

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

Adds real context beyond the annotations: the created object is empty, it cannot be populated here, no one is assigned or notified, and it can run without confirmation. Those are exactly the side-effect facts an agent needs. It does not address what happens on duplicate names or whether repeats create multiple punchlists, despite 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?

Short and front-loaded, with the scope statement first and limitations after. The opening sentence is a fragment ('New, empty punchlist on a project.') that reads slightly as a title restatement rather than a full clause.

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 saying the result is what get_punchlist returns, and it covers side effects and limitations. Only re-creation behavior for non-idempotent calls is left unexplained.

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

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

Schema coverage is 100%, with both project_id and name documented in the schema, so the baseline applies. The description adds only the 'empty' characteristic and no naming or format guidance for the two parameters.

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 ('Adds an empty punchlist to the project') and scopes it with 'empty', which differentiates it from get_punchlist/list_punchlists. It references get_punchlist only to describe the returned shape rather than to route the agent, so sibling differentiation is implied 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?

Gives a clear when-not: items cannot be added through this tool, they must be added in Contractor Foreman. That is actionable context an agent would otherwise have to guess. It stops short of naming sibling alternatives such as list_punchlists or get_punchlist for follow-up.

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 non-read-only, open-world, non-idempotent, non-destructive mutation. The description adds important behavior beyond that: the order is created in Draft status, ordered by the signed-in user, the supplier is not notified, and sending remains a separate app step. It also says the saved order is returned.

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 and appropriately sized for a create tool. There is some redundancy between the first sentence and the second sentence, which both say it creates a purchase order, but the repetition is minor and the key behavioral caveats are clear.

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 six-parameter mutation tool with no output schema, the description covers the core behavior: draft status, supplier notification, sending as a separate step, and returning the saved order. The return value is only described as 'the saved order' without shape details, but the essential call context is present.

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 67%, and the description lists the main fields (subject, supplier, project, order date, notes, line items and line-item fields) but mostly restates what the schema already documents. It adds little detail about required fields, vendor_id semantics, date formatting, or constraints beyond the schema.

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

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

The description states a specific verb and resource: creates a draft purchase order to a supplier with line items, optionally for a project. It also distinguishes the action from sending the PO, which it explicitly says remains an app step. An agent can tell what this tool does 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?

The description makes clear this is for creating a draft PO, not for sending it, and notes the supplier is not notified. That provides useful usage context. It does not explicitly compare against sibling creation tools such as create_bill, so it falls short of full when/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?

Adds real behavioral context beyond the annotations: the record is created in Draft status, attributed to the signed-in user, dated now, and no notification is dispatched — none of which the readOnly/destructive/openWorld hints convey. It does not address what happens on repeat calls, which matters given idempotentHint=false, leaving a small gap.

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 front-loaded sentences with no wasted filler, and the critical 'not sent to anyone' caveat is prominent. There is mild redundancy between the opening sentence and the second sentence's field enumeration.

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 correctly closes the loop with 'Returns the saved RFI,' and it covers status, attribution, and notification behavior. It omits failure modes (e.g., an invalid project_id) but nothing essential for a correct call 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 83% and five of six properties already carry descriptions, so the schema does the heavy lifting. The description only restates the field set (title, question, area, plan sheet, reply-by date) in prose without adding format or constraint detail beyond what the schema provides — 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 and resource ('Creates a Contractor Foreman RFI ... on a project') plus the resulting status ('Draft'), which distinguishes it from get_rfi/list_rfis and from the many other create_* siblings. An agent can tell exactly what is produced 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 bounds the tool's role: 'It is not sent to anyone. Submitting it to the architect or owner stays a step in the app,' which tells the agent when this tool suffices and when a further app-side action is needed. It doesn't name a sibling alternative (none exists for send), so it falls slightly 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?

Goes well beyond the annotations: it discloses that technicians are assigned in the app rather than here, that the customer is not notified, that the service address is inherited from customer or project, and that the status is derived from presence of a date. It even flags that service_time is echoed back on a 12-hour clock while the input takes 24-hour, a non-obvious format switch an agent would otherwise get wrong.

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, then the operational details, with no filler. The opening clause is somewhat restated by the following sentence, a minor redundancy in an otherwise dense and purposeful paragraph.

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, and the description compensates by describing the return value ('returns the saved ticket, with service_time on the 12-hour clock'). Combined with the notification and assignment caveats, an agent has everything needed to call it and interpret the result.

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 83%, so the schema already carries most parameter meaning; the description adds value by explaining the customer/project address inheritance and the date-drives-status relationship. It doesn't restate constraints like maxLength or the time pattern, which is appropriate given the schema handles those.

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 ('Opens a service ticket for a customer') and scopes it to a Contractor Foreman service ticket built from a Directory customer. It is trivially distinguishable from get_service_ticket, list_service_tickets, and update_service_ticket_status.

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 context for when the tool applies: customer from the Directory, optional project, and an optional planned visit that flips the ticket between Scheduled and Unscheduled. It does not, however, mention alternatives or exclusions (e.g., when to use create_work_order instead), so it stops short of a full routing statement.

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 mutation profile: readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds critical access-control behavior—only signed-in company members can open the link, it is not a public customer page—which is not captured in 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?

The main purpose is front-loaded in the first sentence. The second paragraph contains useful exclusions but slightly repeats the opening idea before adding the important customer/PDF alternative.

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 description covers what the tool does, who can access the link, and what the return value is (a short URL). With no output schema, it adequately indicates the result, though it does not mention whether links expire or what happens if called repeatedly.

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 50%: record_id is documented, and record_type has an enum but no description. The description names the supported record types (estimate, change order, invoice), but does not add format or mapping details beyond what the schema already provides.

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: makes a short internal link that opens an estimate, change order, or invoice. It also distinguishes the tool from the public-facing send_* siblings by explaining that this link is only for signed-in team members.

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

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

Explicitly says when to use this tool (internal team sharing) and when not to use it (customer-facing delivery). It names the alternative tools send_estimate, send_change_order, and send_invoice for the customer PDF scenario.

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

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

Beyond the annotations, the description discloses that the result is created in Draft status, issued by the signed-in user, that the subcontractor is not notified, and that no signature workflow is triggered. These are meaningful behavioral consequences for a mutation tool.

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

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

The description is front-loaded and well organized, but the first sentence largely duplicates the second sentence's summary of the same action. It is still efficient and readable, with only minor redundancy.

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

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

For a draft-creation tool with no output schema, the description covers creation status, required contextual inputs, workflow limitations, notification behavior, and the returned object. An agent has enough information to invoke it correctly and understand what will not happen.

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 most parameter meaning is already documented. The description reinforces that the subcontractor must come from the Directory and lists the key inputs, but it does not add substantial 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?

The description uses a specific verb and resource ('Creates a draft sub-contract') and clearly distinguishes this operation from retrieval siblings like get_sub_contract or list_sub_contracts. It also states the creation context: project, subcontractor from Directory, subject, agreement number, and date.

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

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

It explicitly limits scope by saying the API cannot add scope items, terms, or send for signature, and notes those remain app steps. It also states the subcontractor is not notified, giving clear when-not guidance and setting expectations about what must happen elsewhere.

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 disclose that this is a non-idempotent, destructive, open-world write. The description adds valuable context beyond that: it states the return shape ('returns it as get_todo shows it') and a side effect ('Assignees see it in their Contractor Foreman app'). It does not explain why the operation is destructive, but the annotations carry that signal.

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. The first sentence front-loads what the tool does and key optional fields; the second efficiently adds return behavior and visibility. No wasted words.

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 7 parameters, 1 required, no output schema, and annotations covering safety and openness, the description is nearly complete. It covers return behavior and a key side effect, though it could explicitly note that 'name' is the only required field and what happens if an invalid project_id is supplied.

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 57%, so several parameters (name, project_id, assignee_ids) are documented in the schema. The description groups the optional fields ('optionally on a project, with due date, priority and assignees') but adds no syntax or format details beyond what the schema provides, leaving due_time and description unmentioned.

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 ('New') and resource ('to-do') and lists optional fields (project, due date, priority, assignees). This clearly distinguishes it from get_todo, list_todos, and update_todo, though it does not explicitly name alternatives.

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

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

The description implies this tool is for creation but provides no explicit when-to-use guidance, no prerequisites, and no comparison to sibling tools like create_punchlist, create_rfi, or update_todo. An agent must infer its place in the workflow.

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

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

Beyond the annotations, it discloses the created status (Open), issuer (signed-in user), recipient (project's customer), that there are no line items, that nobody is notified, and that the order is returned on success. This is rich mutational context the annotations do not carry.

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 outcome, but the second sentence re-states subject, description and dates already given in the first, wasting space. It is efficient in tone but contains noticeable redundancy.

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

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

For a create tool with annotations covering safety and no output schema, the description supplies the full behavioral picture plus a return-value note ('Returns the saved order'). 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 80% and already documents project_id, subject, description, and date defaults/format. The description names the same fields but adds no syntax or constraint detail beyond the schema, so it sits at the baseline.

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

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

States a specific verb (Creates) and resource (work order) with the resulting status (Open) and key fields, and distinguishes the operation from the large create_* sibling set. An agent can tell exactly what it produces 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?

Routes the agent to update_work_order_status for advancing status and clarifies that sending to the customer 'stays a step in the app', implicitly steering away from any send tool. No explicit when-not guidance, but the lifecycle 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the basic safety profile is covered. The description adds important behavioral detail by stating that associated items are also deleted and that the deletion is permanent, though it does not mention permissions or confirmation requirements.

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 with no wasted text. The irreversible consequence is front-loaded, followed by cascade behavior and the safer alternative.

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 destructive delete tool with no output schema, the description covers the essential decision context: permanence, cascade deletion, and the recommended alternative. The parameter source is already covered by 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 100%, and the single parameter is documented in the schema as coming from list_change_orders. The description does not add meaning beyond that, 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 states a specific verb and resource: deleting a change order or change order request, including its items. It clearly distinguishes deletion from the sibling alternative update_change_order.

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

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

It explicitly says the action cannot be undone and names the exact alternative for preserving the record: update_change_order with status denied. This gives the agent a clear when-to-use versus when-not-to-use rule.

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 destructiveHint=true and non-idempotent, but the description adds what annotations cannot: line items are destroyed, downstream records (projects, change orders, invoices) survive, and the deletion mirrors the UI's Delete menu item. It also states irreversibility in plain words.

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 short sentences, front-loaded with the action and consequence, then the cascade scope, then the safer alternative. 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 one-parameter destructive mutation with no output schema, everything an agent needs is present: what is destroyed, what is preserved, irreversibility, and the non-destructive alternative.

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

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

Schema coverage is 100% and the only parameter is documented as 'From list_estimates,' so the description need not repeat it. Baseline would be 3; the description earns a point for making clear the single identifier targets the estimate whose children are also deleted.

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 ('Deletes an estimate for good') and immediately disambiguates from sibling delete tools (delete_invoice, delete_change_order) by naming the exact object and its cascade semantics.

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-not with a named alternative: 'To keep the history, use update_estimate with status lost instead.' An agent has a clear decision rule between hard delete and status change.

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, but the description adds substantive detail: cascading deletion of invoice items, irreversibility ('cannot be undone'), and the payment-based guard. That is exactly the extra context the annotations cannot convey.

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

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

Front-loads the core action and scope in the first sentence, then adds the irreversibility warning and the fallback path. Four short sentences, none 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?

For a single-parameter destructive tool with no output schema, the description covers consequences, preconditions, and the alternative route. An agent has everything needed to call it safely or avoid 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?

Only one parameter with 100% schema coverage, and the schema already states it comes from list_invoices. The description adds no format or sourcing detail beyond that, 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?

States a specific verb and resource (deletes an invoice) plus a distinguishing precondition (has no payments, for good). It is clearly separable from sibling deleters like delete_change_order and delete_estimate by naming the resource.

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 names the case where the tool refuses (invoice with payments recorded) and routes the agent to a concrete alternative: update_invoice with status write_off or denied. Both when-to-use and when-not 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the useful disclosure of what the response contains (line items with description, cost type, quantity, unit, unit cost, total, cost code) — genuine value beyond annotations, though permission or rate-limit behavior isn't mentioned.

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, front-loaded with the outcome and immediately followed by the concrete returned fields. 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the line-item fields and header fields. Combined with annotations covering the safety profile, an agent has enough 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 description coverage is 100% and the single parameter already says 'bill_id from list_bills'. The description repeats the same provenance without adding format, range, or failure 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?

States a specific verb and resource ('Reads one Contractor Foreman bill by bill_id') and explicitly positions it relative to the list tool: 'what list_bills gives plus the payment terms and every line item'. An agent can tell it apart from list_bills and other get_* siblings without opening a 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?

The reference to list_bills ('bill_id from list_bills', 'what list_bills gives plus...') makes the list-then-detail workflow clear. It never states an explicit exclusion or when-not-to-use case, 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 declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds useful behavioral context by enumerating what is returned: description, status, total, project, customer, date, reason, source estimate, time delay, and priced line items.

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-loaded, with the main purpose in the first sentence and return details in the second. There is minor repetition between 'One change order or request' and 'Everything on one change order or change order request', but the field enumeration 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 single-record retrieval tool with no output schema, the description provides enough detail about the returned fields and the annotations cover safety and idempotency. It does not mention not-found behavior, but that is a minor gap for this retrieval operation.

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

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

There is only one parameter and the schema describes it fully as coming from list_change_orders, giving 100% schema coverage. The description adds no additional parameter semantics beyond what the schema already states, so the baseline 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 clearly identifies the resource as a single change order/change order request and enumerates the data returned, distinguishing it from list_change_orders by emphasizing 'One'. It lacks an explicit action verb like 'retrieve', but the tool name and content make the purpose unambiguous.

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

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

Usage is implied by 'One change order or request' and the schema note that the ID comes from list_change_orders, but the description itself gives no explicit when-to-use guidance or alternatives. An agent can infer this is for fetching a single record rather than listing or mutating.

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 safety is covered by structured data. The description adds real value by disclosing the backing source ('Contractor Foreman Time Cards dashboard') and the exact shape of what comes back, which matters because there is no output schema. It does not mention permission scoping (e.g. whether results are limited to projects the user can see).

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 lead sentence front-loads the three things an agent gets, and the second sentence supplies detail. The second sentence is long and enumerative, but given the absence of an output schema that detail earns its place.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly — current clock-ins, the caller's own status plus card id, and week-over-week hour breakdowns by category. What is missing is any note on empty-state behavior (what happens when nobody is clocked in) or scope/visibility limits.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, framing the call as a context-free snapshot.

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 concrete verb+resource ('Who is clocked in right now... crew hours') and enumerates exactly what is covered: current clock-ins with project and time, the signed-in user's own status and card id, and team/user regular/overtime/total hours for this and last week. It is clearly distinct from list_time_cards and list_project_crew_hours in substance, though it never names those siblings, which is the only thing keeping it from 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?

'Right now' implies the snapshot use case, but there is no explicit statement of when to call this versus list_time_cards or list_project_crew_hours, and no prerequisites or exclusions are given. Usage is inferable from the described output 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description usefully adds a disclosure the annotations cannot: login details, wages and personal ids of employees are deliberately omitted, which tells the agent not to expect those fields. It says nothing about permissions or pagination, so a 3 is fair.

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 the resource and full field set front-loaded, followed by the exclusions. The opening fragment 'One Directory record in full' is slightly clipped as a sentence but functions well as a headline; nothing is padded.

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 enumerating the fields returned and explicitly naming what is omitted. For a one-parameter read tool with strong annotations, an agent has everything needed to call it and interpret the result.

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 single parameter's description already names its source. The description's mention of list_contacts only restates that origin and adds no format or edge-case detail (e.g. what happens with an id from list_leads), 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?

States a specific verb ('Reads one ... Directory record by contact_id') and a concrete resource, and the field inventory ('second phone, fax, website, status, services, tags, default payment terms...') makes it unmistakably the single-record counterpart to list_contacts. An agent can distinguish it from sibling get_* tools purely by resource name.

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 phrase 'everything list_contacts gives plus...' implicitly routes listing to list_contacts and detail to this tool, and the schema note points at list_leads as another id source. There is no explicit 'do not use when' statement or guidance on lead vs contact selection, keeping it below 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 safety profile is covered. The description adds useful detail about what fields are returned, but 'Read only' merely repeats the annotation and it does not discuss behavior for invalid IDs, missing permissions, or not-found cases.

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 definition is front-loaded and appropriately sized for a retrieval tool without an output schema. It has minor redundancy between 'One daily log' and 'Returns one daily log in full,' plus a trailing 'Read only' that repeats the annotation, but it remains readable and efficient.

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?

Because there is no output schema, the description carries the burden of explaining return contents and does so thoroughly: work notes, crew, visitors, materials, equipment hours, weather, address, and delays. It is complete enough to call correctly, though it does not address error cases or access requirements.

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 single parameter has 100% schema description coverage, and the schema explains that daily_log_id comes from list_daily_logs. The description itself does not add any parameter meaning 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?

The description clearly states a specific retrieval action: it returns one daily log in full and enumerates the included data such as work performed, visitors, materials, equipment, weather, and delays. It distinguishes a single daily log from the list-oriented sibling conceptually via 'One daily log,' but does not explicitly name list_daily_logs or update_daily_log as alternatives.

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

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

Usage is implied by 'One daily log' and 'Returns one daily log in full,' suggesting it is used to fetch details for a specific daily log ID. However, the description does not explicitly say when to use this tool versus list_daily_logs, create_daily_log, or update_daily_log, nor does it state prerequisites beyond 'Read only.'

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 safety is covered. The description adds real value beyond that by disclosing the shape of the payload — totals in dollars, line items grouped by section with their fields — which matters since no output schema exists.

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 statement, then a dense but purposeful inventory of returned fields. The long parenthetical enumerating line-item fields is justified given there's no output schema, though it reads as a list dump rather than structured prose.

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 heavy lifting by describing return contents in detail, plus it links section_id to add_estimate_items for follow-up actions. Missing only edge details such as behavior when estimate_id is invalid or permission requirements.

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 single estimate_id parameter is documented as coming 'From list_estimates,' so the description has little left to add. The section_id explanation is about the return payload, not an input parameter, so it doesn't lift this above baseline.

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

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

States a specific verb+resource: fetches a single estimate and enumerates what comes back (customer, dates, terms, totals, line items). The singular framing implicitly contrasts with list_estimates, but it never names that sibling as the way to discover IDs the way a top-tier definition would.

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 — an agent infers this is the detail-fetch for one estimate. The one explicit routing hint ('section_id is what add_estimate_items takes') gives a useful workflow link, but there is no statement of when to prefer this over list_estimates or update_estimate.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds useful field-level context (cost code, reason) but says nothing about error behavior for an invalid expense_id or whether the record is scoped to a contractor. Adequate but with clear gaps for a read tool with annotations present.

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 returned field set and followed by the sibling comparison. There is mild repetition between 'One expense with...' and 'Reads one ... expense', but no wasted 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?

For a single-parameter read with full annotation coverage and full schema coverage, this is close to complete: it names the resource, the identifier, and the returned fields. Only minor behavioral details (invalid ID handling, scoping) are absent, and no output schema exists, so the field list is a helpful substitute.

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 single expense_id parameter is already documented as coming from list_expenses. The description reinforces the provenance ('Reads ... by expense_id') but adds no syntax, format or constraint 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?

States a specific verb and resource ('Reads one Contractor Foreman expense by expense_id') and enumerates the returned fields. It explicitly differentiates itself from the sibling list_expenses by noting it adds the cost code and reason.

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 clarifies that this tool returns what list_expenses gives plus extra detail, which strongly implies when to choose it over the list tool. It stops short of an explicit 'use this when you need X, not Y' instruction but the routing signal 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 declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds the field list returned and the source system, which is useful since there is no output schema, but it omits behavior on a missing ID or permission errors.

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 field inventory, with no filler. The trailing clause 'with the same fields as list_inspections' slightly repeats the opening list.

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 with no output schema, enumerating the returned fields gives the agent what it needs to decide whether to call or list first. Only failure-mode behavior is left out.

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 single parameter is already documented as 'inspection_id from list_inspections.' The description only restates that the read is keyed by inspection_id, adding no new syntax or format detail.

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 ('Reads one Contractor Foreman inspection by inspection_id') and enumerates the returned fields. It is clearly distinguishable from list_inspections, though it never names sibling tools explicitly.

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 reference to inspection_id implies a lookup-after-list workflow, but there is no explicit when-to-use, when-not-to-use, or statement of what to do if the ID is unknown or invalid.

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, so the safety profile is covered. The description adds genuine value by disclosing the exact contents of the response (payments with date, amount, method, status; retainage; balance due in dollars), which matters because there is no output schema. It omits error behavior for an invalid/missing invoice_id.

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

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

Two sentences, front-loaded with the resource and its scope. The second sentence largely restates the first's field list with more detail, so there is mild redundancy, but no filler.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly. What's missing is minor: behavior on a nonexistent invoice and any permission/scope requirements.

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?

Only one parameter and schema coverage is 100% – the schema itself says 'From list_invoices.' The description adds no format or constraint detail for invoice_id, 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?

States a specific verb (get) and resource (invoice) and enumerates the payload: status, project, customer, dates, terms, retainage, totals, line items, payments. An agent can tell it returns a single fully-hydrated invoice rather than a list, though the description never names list_invoices as the contrasting sibling.

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?

No when-to-use or when-not-to-use guidance, and no explanation of the relationship to list_invoices or update_invoice. Usage is only inferable from the name and the detailed field list; the only routing hint ('From list_invoices') lives in the schema, not the description.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, yet the description still adds substantial interpretive context: what each cost bucket contains, that negative difference means over budget, that unpriced costs fall under Unassigned, that time card hours are priced via labor_rate, and that amounts are dollars. This is exactly the behavior an agent needs to interpret the numbers 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 first sentence front-loads the result shape, and the second packs the derivation rules. It is dense but every clause carries information; only the trailing 'Read only' repeats what the annotations already declare.

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 the returned fields, and it does: contract value, estimated, actual split, difference, and invoiced amount. For a 3-parameter aggregation tool this leaves no material 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 the baseline is 3, but the description genuinely adds meaning: it clarifies that labor_rate prices time card hours and defaults to burden_rate, and that budget_from draws from the Schedule of Values or approved estimates plus change orders. That goes beyond the schema's terser wording.

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 resource and scope: estimated vs. actual cost per cost code for one project, with difference and totals. That is far more precise than the sibling list_cost_items or get_estimate, though it never names a sibling to contrast with explicitly.

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 identifying its source (the Job Cost Actual report) and its aggregate nature, so an agent can infer this is the reporting/roll-up tool rather than a line-item lister. However, it never says when to prefer it over list_cost_items, get_estimate, or get_change_order, and gives no prerequisites beyond the schema's project_id note.

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, non-destructive, so the safety profile is covered; the description adds that this is a single-record read keyed by ID and spells out the extra fields returned beyond the list view. It does not say what happens if the ID is unknown or belongs to another tenant, which is the one behavioral gap.

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?

Field list is front-loaded and the two sentences are short. There is mild redundancy: the second sentence re-describes the same payload ('what list_opportunities gives plus…') already implied by the first, costing a few words 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?

With no output schema, the description carries return-value disclosure and does so adequately by naming the fields an agent will receive. For a one-parameter read-only getter it is nearly sufficient; error/not-found behavior is the only missing piece an agent might need.

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 sole parameter already documents 'opportunity_id from list_opportunities.' The description restates the same keying ('by opportunity_id') without adding format, range, or sourcing detail 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+resource ('Reads one Contractor Foreman opportunity by opportunity_id') and enumerates the returned fields in the opening line. It also distinguishes itself from the sibling list_opportunities by describing this as 'what list_opportunities gives plus' the customer's email/phone, notes and last activity subject.

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 clearly implied: this is the single-record counterpart to list_opportunities, and the description ties itself to that sibling both for purpose and for sourcing the ID. It stops short of an explicit 'use this when you already have an ID, otherwise call list_opportunities' exclusion, but the routing is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered; the description adds real value by defining what the returned figures mean (revised contract = original + approved change orders, costs split budgeted/committed/actual, billing split invoiced/paid/outstanding, retainage shown apart) and that amounts are in dollars. It stops short of noting error behavior for an unknown id or any limits, keeping it below 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?

The field list is front-loaded and the semantic clarifications are compact, with every sentence carrying information. The opening fragment 'One project:' and the following 'Returns one project' are mildly redundant, costing a small amount of efficiency.

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 carry the return semantics, and it does so thoroughly for a single-record read tool. What is missing is minor: behavior on a nonexistent id and whether any related collections are truncated.

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

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

With one parameter at 100% schema description coverage, the schema already documents project_id including its numeric pattern. The description repeats the same 'project_id from list_projects' guidance without adding format or edge-case meaning, 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 states the resource ('One project') and enumerates the returned facets (customer, address, stage, dates, contract amounts, costs, billing, retainage), which lets an agent distinguish it from list-style siblings. It is specific, though it never uses a crisp verb like 'fetch' and leans on the name for the action.

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 directs the agent to 'Use project_id from list_projects,' which implicitly defines the browse-then-fetch workflow against the sibling lister. However, it states no conditions for when not to use it and does not address alternatives such as get_job_costing for cost detail.

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 non-destructive, and the description is consistent ('Read only.'). It adds real context beyond them: which fields come back, and the important caveat that line items are excluded and must be viewed in Contractor Foreman.

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 and short, but the first fragment largely restates the second sentence ('project, address, customer' and 'open and completed' appear twice). One sentence of duplication keeps it from 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?

There is no output schema, so the description carries the burden of describing return values — which it does thoroughly, including the notable absence of line items. Only error behavior for an invalid id is 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 coverage is 100% and the single punchlist_id parameter is already documented with its source ('from list_punchlists'). The description adds no syntax or format guidance beyond what the schema provides, 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 states a specific verb and resource ('Returns one punchlist') and enumerates the fields returned: project, address, customer, open/completed item counts, creator and timestamp. The singular 'one punchlist' implicitly separates it from list_punchlists, but no sibling is named outright.

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 id comes 'from list_punchlists', and the description warns the items themselves are not returned. It never explicitly says when to call this vs. list_punchlists, but the limitation note effectively steers the agent away from expecting item detail.

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 safety (readOnly, idempotent, non-destructive), so the description spends its words on what extra data comes back – every line item with description, cost type, quantity, unit, unit cost, total and cost code. It omits behavior on a missing/invalid id, which is the main remaining gap.

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 identity of the returned object, then the detail expansion. No filler or repetition of annotation facts.

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-value burden and does so by enumerating line-item fields, though it partly defers to 'what list_purchase_orders gives' rather than naming those base fields outright.

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?

Only one parameter with 100% schema coverage and the schema already says 'purchase_order_id from list_purchase_orders'. The description reinforces that the id identifies a single PO and names its provenance, adding small but consistent meaning.

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

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

States a specific verb+resource ('one purchase order with supplier, dates, status and its line items') and explicitly contrasts it with the list sibling ('what list_purchase_orders gives plus every line item'), so an agent can distinguish the two without opening schemas.

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 comparison to list_purchase_orders makes the selection context clear: use this when you need a single PO expanded with line items. It doesn't state exclusions or error conditions, but the sibling contrast does most of the routing work.

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, so the safety profile is fully covered. The description's added value is listing which fields come back and noting parity with list_rfis; it says nothing about what happens on an unknown rfi_id (error vs empty) or about auth scope.

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 lines, zero waste, with the resource and returned fields front-loaded. The opening line is a verbless fragment, which slightly blunts the action framing but keeps it compact.

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

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

For a one-parameter idempotent read with no output schema, the description adequately conveys what comes back and where the id originates. Only edge-case behavior (invalid id, missing RFI) is left unaddressed, which is a minor gap given the rich annotation set.

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

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

There is a single parameter with 100% schema description coverage, and the schema already says 'rfi_id from list_rfis.' The description repeats that the lookup is by rfi_id but adds no type, format, or provenance detail 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 ('Reads one Contractor Foreman RFI by rfi_id') and enumerates the fields returned (question, dates, answer, status). It implicitly separates itself from the plural list_rfis and the create_rfi write path, though it never names those siblings directly as alternatives.

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

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

Usage is implied: fetch a single RFI when you already have an rfi_id, vs list_rfis for enumeration. There is no explicit when-to-use/when-not statement or naming of the alternative tool, so the agent must infer the routing.

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 and non-destructive, so safety is covered; the description adds value by enumerating the payload contents (priority, planned duration, service address, customer phone, logged hours), which is exactly the sort of return-shape context annotations cannot convey.

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

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

Two compact sentences, front-loaded with the resource and key fields. There is mild repetition between the first sentence's field list and the second sentence's 'plus' clause, but nothing wasteful enough to obscure the call.

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 right work by naming the notable fields returned, and the single-parameter surface needs little more. It stops short of describing shape or depth of nested entities (customer, technicians), which would be the remaining 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% and the single parameter already documents its own provenance ('service_ticket_id from list_service_tickets'), so the description merely echoes the schema rather than adding format or lookup guidance. 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 states a specific verb and resource ('Reads one Contractor Foreman service ticket by service_ticket_id') and explicitly positions it relative to list_service_tickets, so an agent can tell the two apart 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?

It establishes the relationship to list_service_tickets ('what list_service_tickets gives plus...' and 'service_ticket_id from list_service_tickets'), implying the list-then-get workflow, but never states an explicit when-not or an alternative for bulk retrieval.

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 (readOnly, idempotent, non-destructive), and the description adds the context they cannot: that paid and balance return null from this endpoint, that scope of work comes back as HTML exactly as saved, and that line items include quantity, unit cost, total and cost code. The nullability caveat is exactly the kind of trait an agent would otherwise misread as missing data.

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 paragraphs, front-loaded with the one-line summary followed by the read semantics and the sibling comparison. No filler sentences; every clause carries either scope or a field-level fact.

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 carry the return shape, and it does: the field groups returned, the HTML format of scope of work, and which fields are null. For a single-parameter read tool this is complete enough to call correctly and interpret the response.

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

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

Schema coverage is 100% and the schema description already says 'sub_contract_id from list_sub_contracts'; the description restates the same provenance without adding format, sourcing, or error behavior. Baseline 3 is appropriate since the schema does 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?

States a specific verb and resource ('Reads one Contractor Foreman sub-contract by sub_contract_id') and enumerates the payload: subcontractor, amounts, retainage, scope of work, items. The second sentence explicitly positions it against list_sub_contracts ('what list_sub_contracts gives plus...'), so the agent can distinguish it from the sibling without opening schemas.

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 clear from context: this is the detail fetch complementing list_sub_contracts, and the note that paid/balance are null here while list_sub_contracts has them is an implicit routing rule for financial totals. It stops short of an explicit 'use X when / do not use this when' statement, so the agent must infer the boundary.

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, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that by enumerating the returned content, including nested submitted items with manufacturer, status, and return date — filling in for the absent output 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?

Two sentences, front-loaded with the key outcome (what fields come back) before the mechanism (lookup by submittal_id). There is mild redundancy between the first sentence's field list and the second sentence's restatement, but no wasted framing.

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 correctly takes on the burden of describing return values and does so with a concrete field inventory. It stops short of noting failure behavior (e.g., invalid or missing submittal_id), which is the only material gap for a single-record read.

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 single parameter already carries a description pointing back to list_submittals. The description restates the same provenance ('by submittal_id') without adding format or edge-case details, so the schema does the heavy lifting — 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 ('Reads one Contractor Foreman submittal by submittal_id') and immediately distinguishes itself from list_submittals by describing the extra fields it returns (plan sheet, specification section, items with manufacturer/status/return date). An agent can tell exactly what this returns versus the list sibling.

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 framing 'what list_submittals gives plus ...' implicitly tells the agent this is the detail follow-up to list_submittals, and the schema reinforces the dependency ('submittal_id from list_submittals'). It lacks an explicit when-to-use/when-not statement (e.g., 'use only when you need item-level detail'), 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 declare readOnly, idempotent, non-destructive, open-world, so the safety profile needs no restating. The description adds substantive non-annotated context about the payload shape — one entry per employee and cost code with hours and per-entry notes, plus the crew-sheet distinction.

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

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

Front-loaded with the core purpose in the first sentence, followed by return-shape detail. 'A crew sheet lists every crew member' is slightly tangential but cheaply disambiguates a domain term; otherwise no wasted prose.

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?

No output schema exists, so the description carries the burden of describing the return value, and it does so usefully (per-employee/cost-code entries with hours and notes). It stops short of detailing error behavior for an invalid timecard_id or pagination, which for a single-record read is a minor 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?

With one parameter at 100% schema coverage, the schema already documents timecard_id and even its provenance from list_time_cards. The description reinforces that provenance but adds no format or validation detail beyond the schema, 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 and resource ('Reads one Contractor Foreman time card by timecard_id') and clarifies the payload relative to the list tool ('what list_time_cards gives plus one entry per employee and cost code'). It is clearly the single-record detail fetch complementing list_time_cards, though it never explicitly contrasts itself with siblings in the same way.

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