WorkWing

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). The description adds genuinely non-structured context: the note is visible to 'everyone working the job' and should preserve the user's own words. That audience/visibility disclosure is the kind of behavioral detail an agent cannot get from annotations.

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

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

Two sentences, zero filler, with the core action stated first and the content-quality instruction second. Every sentence earns its place.

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

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

For a simple three-parameter, non-destructive write with no output schema, the description covers purpose, audience, and content expectations. It omits any mention of failure modes (e.g. the brand mismatch refusal documented in the schema), but nothing essential to calling 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 67%, and the remaining coverage is largely in the schema itself (brand documents optionality and refusal behavior; content documents maxLength). The description's 'write what the user actually said' is content guidance but adds no parameter-level 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 ('Record a note against a job') so the agent knows exactly what happens. It does not explicitly contrast with siblings like add_project_crew or create_job, but the note-vs-job distinction is unambiguous.

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

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

The description implies usage by telling the agent what to write ('what the user actually said rather than your summary'), but gives no explicit when-to-use, when-not-to-use, or alternative tool routing. Guidance is inferred 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=false, idempotentHint=true and destructiveHint=false, so the mutation safety profile is covered. The description adds real semantic behavior beyond that: the operation grants eligibility rather than assignment, and the eligibility is scoped to unscheduled units. It does not mention failure modes (e.g. the brand mismatch) or side effects on existing crew, so it stops short of a 5.

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

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

Three short sentences, each earning its place: the positive definition, the disambiguating negation, and the routing rule. The core effect is front-loaded before the exclusions.

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 tool with no nested objects and full schema coverage, the description supplies the semantic model needed to call it correctly and to route away from schedule_job. It does not describe the return or confirmation behavior and there is no output schema, which is a minor 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 description coverage is 100%, and the schema already explains that brand is optional and refused if it differs, and that project_id/resource_id come from find_project and find_resource with a 'never guess' warning. The description adds nothing further about parameters, 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 ('Add an engineer to a project's crew') and immediately defines the effect ('lets them claim any of its unscheduled units'). It also explicitly distinguishes the operation from sibling schedule_job, so an agent can tell them apart without opening either schema.

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

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

Gives an explicit when-not clause ('This is NOT the same as booking them onto one'), names the alternative tool and the trigger for it ('If the user named a particular day or unit, use schedule_job on that unit instead'), and supplies a fallback for ambiguity ('When you cannot tell which they meant, ask'). This is about as complete as routing guidance gets.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not the sole safety carrier. It nonetheless adds meaningful context beyond the annotations: the exact irreversibility semantics ('a cancelled job cannot be moved back to any other status') and a required confirmation ritual before invocation.

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, zero padding, and the irreversible/destructive warning is front-loaded immediately after the purpose statement. Every clause carries actionable 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 destructive mutation tool with no output schema, the description supplies the critical missing pieces: irreversibility, the pre-call confirmation requirement, and the reason to forward. An agent has everything it needs to call this safely.

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%, between the low and high baselines. The description reinforces the reason parameter ('pass the reason they gave') and implies job identification, but says nothing about the optional brand parameter, whose refusal behavior is documented only in 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 ('Cancel a job'), which is unambiguous against siblings like create_job, get_job, and schedule_job. It does not explicitly name a sibling to distinguish from, but the verb alone is sufficiently distinct for selection.

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

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

It gives a clear precondition workflow: name the job and customer back to the user, get an explicit yes BEFORE calling, and pass the reason they gave. That is strong when-to-use guidance, though it names no alternative tool for cases where the agent should not cancel.

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 (which only say write/non-destructive/non-idempotent/closed-world): it discloses that this writes to a live system other people act on, that brand inheritance rules apply, that a brand mismatch is refused rather than silently relocated, and that the response carries a job number and a `warnings` array to relay to the user. That is exactly the operational context annotations cannot express.

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

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

Front-loaded with the action and the confirm-first rule, and every sentence carries a constraint or a consequence. It is dense and somewhat long for a single paragraph, with the brand/inheritance rules stacked toward the end, but there is little 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 high-risk mutation with 11 parameters and no output schema, it covers the decision inputs (confirmation, ID sourcing, site resolution, brand validation) and the return surface (job number, brand, warnings). Nothing an agent needs to call it safely appears missing.

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

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

Schema coverage is 73% and already documents brand, customer_id, location_id and project_id in detail. The description reinforces the highest-risk ones with rationale (why a site must be agreed rather than defaulted, why brand is passed for validation), adding judgment beyond the field text, though it says nothing about priority, custom_fields, or the scheduled_* timestamps.

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

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

States a specific verb+resource ('Create a job for a customer') and immediately distinguishes itself from sibling mutations like schedule_job, cancel_job and add_job_note by scoping the effect to a customer's live system. An agent can identify the operation without opening the schema.

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

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

Explicit preconditions and sequencing: confirm customer, site, work and time with the user BEFORE calling; source customer_id/location_id from find_customer and never guess; resolve the site when the customer has multiple. It names the sibling to use for sourcing IDs and the failure mode (job nobody can be sent to) that the guidance prevents.

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

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

Annotations already establish this is a read-only, non-open-world operation, so the bar is lower. The description adds a real behavioral constraint beyond the annotations: the id must be one returned by search, which establishes an upstream dependency the agent must satisfy.

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

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

Two short sentences with zero waste; the scoping and format rule comes first and the sibling routing second. Size is proportionate to a one-parameter tool.

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-id read tool with an output schema, the description covers purpose, id provenance, and alternatives adequately; return-value detail is legitimately left to the output schema. It could say more about failure behavior for a stale or unknown id.

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 fully documented there, including the same job:<uuid> format example, so the description adds essentially nothing new. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb and resource ('Fetch the full text of one document') and pins the input to an id from search. It is clearly distinguishable from siblings like get_job or find_customer without opening their 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?

It explicitly routes the agent away from this tool in a conversation, naming four concrete alternatives (get_job, find_customer, find_resource, find_project). The trigger condition ('in a conversation') is a little loose, and it doesn't state when fetch is unambiguously correct beyond 'document returned by search'.

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 only declare readOnlyHint=true and openWorldHint=false; the description adds substantial behavior beyond that: the 5-match cap, the presence of a guidance line, cross-brand search semantics (same name in two brands = two customers), and the locations array ordering with primary first.

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 and every sentence carries a distinct rule (matching, cap, disambiguation, brand, locations). It is dense and slightly run-on across six clauses, but 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?

With no output schema, the description still conveys the shape of the result (matches, guidance, brand, locations with primary first), so an agent knows what to expect and how to act on it. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and the single param is already documented as accepting any fragment. The description still adds value the schema does not: phone numbers match regardless of formatting, and the query spans name/phone/email/postcode uniformly.

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

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

Names a specific verb (look up) and resource (customer) plus the accepted search key types (name, phone, email, postcode). It is clearly distinguishable from siblings like find_project, find_resource, and search, which are not described with this customer-centric matching scope.

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 instructs how to behave on multi-match results ('tell the user who matched and ask which they mean - never pick one yourself') and routes the agent onward to create_job when a site is named. It also tells the agent to follow the returned guidance line, which is a concrete when-to-do-what 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real behavior: it searches every brand the user holds, each result carries a brand field, and pool units with no date are silently excluded when on_date is set. It does not mention result caps or pagination, so not a full 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?

Four compact sentences, front-loaded with the lookup keys and following with result shape, the on_date narrowing rule, and the multi-match instruction. Each sentence carries information, though the pool/date exclusion is stated twice (once in prose, once via the schema) causing 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?

With no output schema, the description carries the burden of describing returns and does so: a single match yields the crew and its units, the brand is included, and ambiguous matches require user clarification. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates that on_date narrows to one day and pool units are excluded. It adds no format or syntax detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (look up) and resource (a project), enumerates the three lookup keys, and defines the domain object ('a project groups jobs (its units) under a shared crew and window'). An agent can distinguish it from find_customer, find_resource, and the generic search siblings 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?

Gives clear operating context: use on_date to narrow units to a single day, and 'when several projects match, ask the user which they mean' – an explicit disambiguation instruction that many definitions omit. It never names a competing sibling tool or states when NOT to use this one, so it falls short of a 5.

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

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

Annotations only declare readOnlyHint and openWorldHint, yet the description discloses result cardinality (up to 5 matches), what each match carries (live availability, brands), the presence of a 'guidance' line the agent should follow, and a disambiguation policy. This is substantial behavioral context an agent could not infer from the annotations alone.

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

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

Four tight sentences with the purpose front-loaded, followed by return shape, the disambiguation rule, and the cross-brand scoping note. No sentence is redundant with the schema or annotations, and each adds a distinct actionable 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?

With no output schema, the description carries the burden of describing returns and does so: match count cap, availability, brands, and the guidance line. Combined with the explicit disambiguation instruction, an agent has everything needed to select and invoke this tool correctly.

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

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

There is one parameter with 100% schema description coverage, so the schema already documents that `query` accepts a name/display-name/email fragment. The description restates this rather than adding syntax, normalization, or matching behavior beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Look up an engineer (a resource) by any fragment of their name or email address'), and the parenthetical disambiguates 'resource' as an engineer versus the customer/project resources handled by sibling find tools. An agent can distinguish it from find_customer and find_project without reading 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?

Gives a clear usage condition (lookup by name/email fragment) and an explicit decision rule for ambiguous results: ask the user, never pick one yourself. It does not explicitly name when to prefer a sibling tool (e.g. find_customer for non-engineers), so it falls just short of the 5 bar.

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

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

With readOnlyHint/openWorldHint already covering the safety profile, the description adds substantial non-obvious behavior: gaps derive only from scheduled jobs and logged absences, working hours and travel time are excluded, and results are candidates rather than confirmed free time. It also points at a returned `note` field the agent should read, which annotations alone would not reveal.

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, both load-bearing, front-loaded with the core action and immediately followed by the most important caveat. No filler or restatement of the name.

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 four-parameter read tool with no output schema, the description covers the data-source limitation, the confirm-before-promising rule, and flags a return field. The only gap is the shape of the returned gaps themselves (e.g., list of intervals), which is a minor omission since the core semantics are conveyed.

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

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

Schema description coverage is 100%, so from/to/resource_id/slot_minutes are already documented in the schema. The description restates slot_minutes' filtering role ('ignoring gaps shorter than slot_minutes') but adds no format or edge-case 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: finding gaps in one engineer's day within a time window, with the slot_minutes threshold made explicit. The scope (one engineer, scheduled jobs and logged absences only) is distinctive enough that an agent can tell it apart from siblings like get_schedule or find_resource 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?

It gives downstream usage guidance ('treat a gap as a candidate to confirm with the user, not a promise') but never states when to choose this tool over get_schedule or find_resource, or any prerequisite for calling it. Usage is implied by the output caveat rather than explicitly framed as when-to-use.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavioral context: the search spans every brand the user holds, every job carries its brand, and an ambiguous search returns `matches` instead of `job`. With no output schema, that polymorphic return disclosure is important. Only the empty-result/error behavior is left unstated.

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 is front-loaded in the first clause, and the second sentence handles the ambiguous-match case with no filler. The first sentence is dense, packing scope, three modes and brand semantics into one run-on, but nothing is wasted.

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

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

Because there is no output schema, the description correctly spends its budget explaining the `job` vs `matches` response shape and the follow-up action for ambiguity. It is close to complete for a no-required-param lookup tool, missing only what happens when nothing matches.

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

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

Schema description coverage is 100%, so job_id, search and job_number are already documented, and the description largely restates them. It adds little syntax or format guidance beyond echoing that search matches title and customer name; 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 gives a specific verb set (fetch/search) plus the resource (job) and the three lookup modes (number, id, free text), which cleanly separates it from create_job, cancel_job and the project/customer finders. It also states the scope ('in every brand the user holds'), a detail not derivable from the name alone.

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

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

Usage is implied rather than stated: an agent can infer 'look up a job' and the multi-match fallback ('ask the user which they mean'), but there is no explicit when-to-use versus siblings such as search, fetch, find_project or find_customer, and no statement of when this tool is the wrong choice.

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 only declare readOnlyHint and openWorldHint, so the description carries the rest. It adds real behavioral context: overlap inclusion ('A job that merely overlaps the window is included'), brand scope ('Covers every brand the user holds'), and the fields returned per entry. Missing pagination/limits behavior keeps it from 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?

Four short sentences, front-loaded with the core action and scope before the detail sentences. Each sentence carries information (overlap rule, brand coverage, return fields) with no filler, though it is slightly denser than strictly necessary.

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

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

For a simple read tool with 3 fully-documented params and read-only annotations, the description covers the window semantics, overlap behavior, scope breadth, and return payload. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the times must be 'ISO 8601 with an offset' (tighter than the generic date-time format) and clarifies resource_id as an optional single-engineer filter.

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

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

States a specific verb ('List') and resource ('jobs scheduled between two times') with precise scope ('optionally for one engineer'). This is readily distinguishable from siblings like get_job (single job) and get_availability, and no schema-opening is needed to understand it.

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 the clear scope, but there is no explicit when-to-use vs alternatives guidance or exclusion of other tools. It never says to prefer this over search or get_job, or what happens if the window is huge.

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 safety (readOnlyHint=true, openWorldHint=false), but the description adds non-obvious behavior: fuzzy 'close spellings' matching means results are ranked guesses requiring user confirmation, and templates are brand-scoped so a job can only use a template from its own brand. That is substantive context beyond structured fields.

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 purpose and scoping, and each sentence carries a distinct instruction. However, the brand constraint is repeated from the schema and the passage runs five sentences for a two-parameter tool, so it is slightly longer than necessary.

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 explains what a template is, that results are ranked guesses, and what fields matter (brand), which is enough for correct invocation. It stops short of describing the result shape or pagination, a minor gap for a list tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates them (brand scoping, omitting query to sample). It reinforces intent but adds little syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the job templates') plus scope ('in every brand the user holds, ranked against what the user called the work'), which is more than a bare label. It also distinguishes itself from the sibling create_job by naming the dependency relationship ('create_job needs one wherever they exist').

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

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

Explicit when-to-use and when-not: name the intended result back to the user and get agreement before creating anything, and 'Call with no query only to sample what exists.' It also tells the agent how to pick the brand parameter relative to the customer/project. Nothing is left to inference.

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

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

Annotations only say non-readOnly, idempotent, non-destructive. The description adds genuinely non-obvious behavior: the booking proceeds even on a clash because that can be intentional, and the caller must read `warnings` in the result and relay every one to the user. That override-plus-warning contract is exactly the kind of context annotations cannot 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?

Three sentences, front-loaded with the action, then the confirmation precondition, then the clash/warning contract. Every sentence carries distinct operational information with 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 usefully explains the one return field that matters (`warnings`) and the confirmation requirement. It leaves some gaps for a mutation of a live schedule — e.g. whether an existing booking is overwritten, and any permission requirements — but the critical agent-facing behavior is covered.

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 60%; brand/job_id/resource_id are documented ('From get_job', 'Never guess this'), but the two date-time parameters have no schema description at all. The description only gestures at them via 'time window' and 'agree the time', adding no format, timezone, or ordering guidance beyond the pattern.

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 ('Set') and resource ('a job's time window') plus a second action ('assign an engineer to it'). This is clearly distinguishable from siblings like get_schedule, get_availability, and cancel_job 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?

Gives an explicit precondition — agree the engineer and time with the user BEFORE calling — which is strong usage guidance for a mutating tool. It doesn't name alternative tools or exclusions, but the schema descriptions point at get_job and find_resource for the required ids, so routing context exists 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 declare readOnlyHint=true and openWorldHint=false, and the description supplements them with non-obvious behavior: cross-brand reach ('every brand the user holds') and a hard result cap of 20 documents with ids to hand to fetch. It stops short of describing ranking, matching or failure 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?

Two sentences, both load-bearing: the first defines scope and the fetch handoff, the second redirects to the more precise task tools. Scope and constraints are front-loaded with no filler or restatement of the title.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to convey scope, limits and routing — all of which it does. Nothing required to select or invoke this tool correctly is missing.

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

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

Schema coverage is 100% and the single parameter's own description already enumerates the matched fields (job titles/numbers, customer names, emails, postcodes, engineer names, project names) in more detail than the tool description does. The phrase 'by free text' adds little beyond the schema, 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 (search) plus the exact resource scope: jobs, customers, engineers and projects, across every brand the user holds, by free text. It also identifies the audience ('research and knowledge features that expect a search-and-fetch connector'), which separates it from the task-oriented siblings at a glance.

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 routes the agent: 'In a conversation prefer the task tools: find_customer, find_resource, find_project and get_job answer more precisely and carry the guidance you need.' That names the alternatives and the condition that selects them, which is the strongest form of 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.