Synchroteam MCP by usefulapi

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

Goes well beyond the annotations by disclosing external side effects the agent could not infer: completion may fan out 'job completed' notifications via email/SMS/webhook to managers, technicians or the customer depending on account configuration. It also warns about a partial-failure mode (provider refusing a call with only one timestamp) and the XOR identifier rule, which the schema does not encode.

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 operation class and action, then ordered by importance: optional timestamp contract, notification side effects, identifier selection, endpoint. Every clause carries information an agent needs; nothing is padding.

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

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

No output schema exists, yet the description still covers the effect of the call, the notification fallout, the identifier constraint, the timestamp pairing rule and the underlying endpoint — everything needed to invoke a 5-parameter write tool with only the identifiers being optional.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema omits: the mutually-exclusive identifier rule across id/my_id/num and the pairing requirement for actual_start/actual_end. The timestamp format itself is already in the schema, so no further credit there.

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 ('mark a job as completed') and prefixes it with the operation class ('WRITE:'), which immediately separates it from read-side siblings like get_job and from the adjacent lifecycle tools start_job/schedule_job. An agent can tell what this 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?

Gives concrete invocation conditions: identify the job by exactly one of id, my_id or num, and supply actual_start/actual_end together because Synchroteam may refuse a lone timestamp. It stops short of naming alternatives (e.g. start_job vs complete_job) or stating when completing is inappropriate, so it is clear context without explicit exclusions.

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 non-idempotent write behavior, so the bar is lower. The description still adds real behavioral value: duplicate my_id causes a hard failure with no creation, and the endpoint is POST /customer/send. It does not describe permissions or what the response contains.

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

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

Three tightly packed sentences: the WRITE prefix, the required-input note, the failure/alternative rule, and the endpoint. Nothing is filler and the most important constraint is front-loaded.

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

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

For a 10-parameter mutation with no output schema, the description covers the primary required input and one important failure mode, but omits permissions, response shape, and the meaning of the many contact/* fields. Adequate but visibly thin against the schema's surface area.

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 name, address and my_id get any mention, and the claim that 'an address are required' conflicts with the schema where address is optional and only name is required. With 40% schema coverage and 10 parameters, the description leaves most optional fields (vat_number, contact_*) undocumented anywhere.

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 new customer') and prefixes it with 'WRITE:' to make the mutation nature unmistakable, which cleanly distinguishes it from get_customer/list_customers/update_customer siblings. The required inputs are named up front.

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

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

It gives a concrete routing rule for the my_id collision case: nothing is created, an error returns, and the agent should use synchroteam_update_customer. It stops short of stating when to create a customer versus other entity types (site/depot), but for this tool family that's inferable.

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=true, idempotentHint=false and openWorldHint=true, covering the write/safety profile. The description adds genuinely new behavior — the duplicate-myId refusal returns an error and nothing is created — but says nothing about auth requirements, side effects on the parent site/customer, or the response.

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 tight clauses with the operation type front-loaded as 'WRITE:' and the key constraint in parentheses. No filler; every clause carries a rule the agent needs.

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 nested-object create tool with no output schema and annotations covering the write/safety profile, the description covers the two things an agent would most likely get wrong (the site/customer exclusivity and duplicate myId). It omits permissions and return shape, which are minor given the rich 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 100%, so each field is already documented at the parameter level (including the nested 'exactly one of id or myId' rules). The description adds the cross-field constraint that site and customer are mutually exclusive, which is real added meaning, but it doesn't explain the required 'name' or the my_id semantics.

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 ('create a new piece of equipment') plus where it lives (under a site or a customer), and even names the endpoint. It is clearly distinguishable from the get/list/update siblings, though it never explicitly names a sibling to differentiate against.

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

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

Gives explicit applicability constraints: exactly one of site or customer must be supplied and both is refused, and a duplicate myId short-circuits with an error. It stops short of naming alternative tools or when not to create at all.

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=true, idempotentHint=false, openWorldHint=true), yet the description still adds real value beyond them: it discloses that account 'job created' notifications (email/SMS/webhook, possibly to the customer) may be triggered, and that a duplicate myId silently produces no record plus an error. It stops short of noting auth/permission requirements, so 4 rather than 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 WRITE marker and core action, then routing guidance, then preconditions and side effects. Every sentence carries information; the trailing endpoint notation is the only near-redundant element.

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 must carry the return expectations; it does tell the agent the created job is unassigned and that a duplicate myId returns an error, but does not say what identifier or body comes back. For a 15-parameter mutation with nested objects, this is nearly 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?

Schema description coverage is 67% and nested 'exactly one of id/myId/name' semantics are already documented in the schema itself. The description restates the customer-identification forms and the required/optional split but adds no new syntax or format detail, so the baseline 3 is correct.

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 ('create a new job for a customer') plus the resulting state ('status created, not yet scheduled'), and explicitly contrasts with the sibling synchroteam_schedule_job. An agent can distinguish it from other create_* tools without opening any schema.

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

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

Names the alternative tool and the condition that selects it ('use synchroteam_schedule_job to assign a technician and time'), and gives the required/optional input split plus the myId duplicate-precondition. No exclusions are left to inference.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false. The description adds value beyond them by disclosing the myId uniqueness rule ('if myId already exists nothing is created and an error is returned') and the underlying endpoint (POST /site/send). It does not explain the error shape or what happens to the partial creation, but with strong annotation coverage this is a solid additive block.

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 tight sentences, no filler, and the operation class plus core requirement are front-loaded. Every sentence carries either purpose, prerequisite, or a behavioral rule.

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

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

For a write tool with a nested customer object and no output schema, it covers the essentials (required fields, uniqueness behavior, endpoint) but is silent on the return value, on the optional contact/addressComplement fields, and contains a mild mismatch about address being required.

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

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

Schema coverage is 56%, so the description partially compensates by naming name, address, customer (id or myId) and the my_id collision semantics. However it says an address is 'needed' while the schema marks only name and customer as required, and the six contact/addressComplement fields are undocumented in both places.

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 new site') and immediately disambiguates the resource's domain meaning ('a location of a customer'), which separates it from sibling create_customer and from get_site/list_sites. The 'WRITE:' prefix signals the operation class up front.

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?

Conveys prerequisites (needs a name, an address and the customer), which is implicit usage guidance, but never states when to choose this tool over alternatives or what must exist beforehand (e.g. the customer must already exist). No exclusions beyond the myId collision 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 declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered without the description. The description contributes only the underlying endpoint (GET /customer/details) and the returned field groups, adding modest value but no auth, rate-limit, or not-found behavior.

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?

A single compact sentence that front-loads the resource and identifier modes, then the return payload, then the endpoint. No filler sentences and nothing repeated from the schema.

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

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

For a two-parameter read tool with full schema coverage, annotations carrying the safety profile, and no output schema, the description covers inputs, return contents, and the backing endpoint. It omits only failure-mode behavior (unknown id, ambiguous name), which keeps it from a 5.

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 enum of by-values is already self-documenting, so the baseline is 3. The description adds genuinely new semantics by requiring an 'exact' match for the name and e-mail modes, which the schema does not convey.

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 (one customer), enumerates the accepted identifier types, and previews the returned payload fields. The singular 'One customer' implicitly contrasts with synchroteam_list_customers, but no sibling is named explicitly, 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?

The phrase 'exact name or e-mail' gives a real precondition (no fuzzy/substring matching), which is implied usage guidance. However, it never states when to prefer this over synchroteam_list_customers or what to do when no exact match exists, so it lacks explicit when-to-use/alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds the concrete endpoint (GET /depot/details) and a hint at the returned content (per-part quantities), but says nothing about auth needs, rate limits, or pagination.

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

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

Two short sentences with no filler; the core purpose and returned content are front-loaded, and the endpoint is a compact trailer.

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

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

For a simple read-only getter with full parameter coverage and annotations carrying the safety profile, the description is nearly sufficient, and its mention of per-part quantities compensates for the absence of an output schema. Only minor gaps remain around error cases and auth.

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 id parameter is fully documented there, including its GUID source tool. The description only restates 'by id' and adds no format or constraint 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?

The description names a specific verb and resource ('get depot') and states the payload contents ('quantity of each part it holds'), which an agent can act on without opening the schema. It does not explicitly contrast itself with the closest sibling synchroteam_list_depots, so it falls short of the top band.

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 'by id' implies the single-record lookup use case, but the description gives no explicit when-to-use guidance or naming of the alternative list_depots tool for broader queries. Usage is only inferable, which matches the minimum-viable band.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds useful behavioral context by stating the response includes the owning customer and site, plus the underlying endpoint (GET /equipment/details), but says nothing about errors when the exact name matches nothing or misses.

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 filler; the lookup keys and the returned context are front-loaded and the endpoint reference trails. Every clause 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?

No output schema exists, so the description's note that the result carries the customer and site is the only return-value signal and it is adequate. Combined with annotations covering the read-only profile and a fully documented schema, the definition is nearly complete, lacking only fallback behavior for a name that doesn't match exactly.

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 enum documents id/myId/name, so the baseline is 3. The description mirrors those three keys and adds the qualifier 'exact' for name matching, which is a small but genuine clarification 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 ('Get') and singular resource ('One piece of equipment') and enumerates the three lookup keys. The singular framing implicitly distinguishes it from the sibling synchroteam_list_equipment, though it never names that sibling for explicit differentiation.

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

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

Usage is only implied by the phrase 'One piece... by id, myId or exact name', which signals a single-record lookup rather than a list. There is no explicit when-to-use statement, no exclusions, and no named alternative such as list_equipment for browsing.

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 destructiveHint=false, so the safety profile is covered. The description adds that the response includes the invoice's lines and names the underlying endpoint (GET /invoice/details), but says nothing about auth, error cases, or pagination – adequate against the lowered bar.

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 terse fragments with zero waste and the key scoping detail (lookup keys, included lines) front-loaded. Slightly telegraphic, but every element 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 read tool with a complete two-parameter schema and full annotation coverage, the description supplies what is needed: what it fetches, how to identify it, and that lines are included. No output schema exists, so return detail is only lightly sketched.

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 self-documenting fields ('by' enum and 'value'). The description's 'id, reference or number' merely echoes the enum values already in the schema, adding no syntax or format detail beyond it; 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 adds scope: lookup by id, reference, or number, returning lines. This clearly distinguishes it from the sibling synchroteam_list_invoices, which returns multiple invoices.

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

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

The phrase 'One invoice' implies single-record retrieval versus the list alternative, but no explicit when-to-use, when-not-to-use, or named alternative is given. Usage is inferable but not spelled out.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /job/details) and enumerates the returned content (time entries, parts used, report, custom fields), which is meaningful behavioral context given there is no 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?

A single front-loaded sentence carries the resource, the identifier modes and the returned facets, followed by the endpoint tag. The field enumeration is long but earns its place because no output schema exists; nothing is redundant.

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

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

With no output schema and only two parameters, the description supplies what an agent needs: the retrieval key options and an inventory of the returned job data. It omits failure behavior (e.g., what happens with an unknown identifier) but is otherwise sufficient for calling the 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?

Schema coverage is 100%, so the baseline is 3, but the description earns above that by explaining what 'num' actually is ('the job number shown in the app') and by listing the three accepted identifier kinds together with their scope (job, id, myId). It clarifies the enum meaning beyond the terse schema text.

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

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

States a specific verb and resource ('One job by num/id/myId') and enumerates the facets returned. It implicitly separates itself from the many list_* siblings by emphasizing 'One job', but never names synchroteam_list_jobs, so the differentiation is left to inference.

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

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

There is no explicit when-to-use guidance or reference to alternatives such as synchroteam_list_jobs or the other get_* tools. The parenthetical about 'the job number shown in the app' helps pick between num/id/myId, but that is parameter help rather than usage 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds genuinely useful context beyond them: 'Image bytes are never returned', which tells the agent it only gets links and should not expect binary payloads. It stops short of noting pagination or link expiry.

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 that lead with what is returned, then the key constraint, then the endpoint. No filler, nothing repeated from the schema or annotations.

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

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

For a simple read-only tool with fully documented parameters and no output schema, the description covers the essential unknowns: the returned fields and the fact that bytes are excluded. Only extra context like pagination or auth requirements is absent, which is minor here.

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

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

Schema description coverage is 100%, with both 'by' (enum of num/id/myId) and 'value' documented in the schema itself. The description adds no additional meaning about the identifier 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 resource and shape: 'Photo links of a job (url, file name, comment, report iteration)', which tells the agent exactly what comes back. It implicitly distinguishes itself from the sibling synchroteam_get_job, but never names or contrasts it explicitly, keeping it 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?

The description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as synchroteam_get_job or the list_* tools. The agent must infer from the name alone that this is the tool for a job's attached photos.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description adds only that this is a single-record fetch against a specific endpoint; it says nothing about behavior on a missing or invalid id, which is the one gap an agent would care about here.

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 resource and then the lookup keys, with zero filler. The trailing raw endpoint path is slightly redundant but not disruptive.

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

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

For a two-parameter read tool with high schema coverage and an annotations-declared safety profile, this is close to adequate. The gap is that there is no output schema and no description of what a part/service record contains or how the two are distinguished, leaving the return shape undocumented.

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 "by" enum is fully documented in the schema, so the parameters already carry their own meaning. The description's "by id or reference" merely restates the enum values rather than adding format, constraint, or ambiguity guidance.

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

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

The description names the resource precisely ("One part or service by id or reference") and clarifies that parts and services share this endpoint, which distinguishes it from a generic getter. It doesn't explicitly name the sibling to use for collections (synchroteam_list_parts), so it falls 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?

There is no statement of when to use this tool versus synchroteam_list_parts or the other get_* siblings. The phrase "by id or reference" implies a single-record lookup, but that is inferred rather than stated, and no prerequisites or exclusions are given.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two useful bits beyond that — the returned payload includes line items, and the underlying endpoint is GET /quotation/details — but says nothing about pagination, error behavior when the identifier is not found, or field completeness.

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?

A single front-loaded sentence plus an endpoint reference; every clause carries information and nothing is padded. Slightly telegraphic phrasing ('One quotation by id...') costs a little readability but not correctness.

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 full schema coverage, complete annotations and no output schema, the description covers what is returned ('with its lines') and how to identify the record. It is nearly complete, missing only edge-case behavior such as not-found handling.

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 enum on `by` plus the `value` constraint are fully documented in the schema itself. The description's mention of 'id, reference or number' merely restates the enum, adding no new format or constraint detail, 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 concrete retrieval action ('One quotation') and resource, plus the identifier options (id/reference/number) and that line items come back. It implicitly contrasts with the plural synchroteam_list_quotations sibling, but never names it, so the differentiation is inferred 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?

The singular 'One quotation ... by id, reference or number' implies use when a single quotation must be fetched rather than enumerated, but there is no explicit when-to-use or when-not-to-use statement and no reference to the list/gather alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine context the annotations lack: it enumerates the returned fields (address, contact, customer, custom fields, tags), which matters because there is no 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?

One compact sentence front-loads the lookup modes and the payload, followed by the raw endpoint. No filler; every clause carries 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 usefully lists the fields a caller should expect, and annotations cover safety. It omits edge behavior such as not-found handling or identifier precedence, but that is a minor gap for a simple read 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 coverage is 100%, so the two parameters and the by-enum are already documented. The description still adds the 'exact name' qualifier, telling the agent that name matching is exact rather than fuzzy — a nuance the schema's generic 'name' enum value does not convey.

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 ('One site') plus the three accepted identifier modes, and names the returned fields. This clearly distinguishes it from synchroteam_list_sites and the other get_* siblings without needing to open 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?

Usage is implied by the singular 'One site by id, myId or exact name', which signals single-record retrieval rather than enumeration. However, it never names list_sites as the bulk alternative or states when to prefer one identifier mode over another.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path (GET /user/details) with no error behavior, not-found handling, or authentication context, so it contributes little beyond the 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?

Two short fragments with no padding, front-loading the identifier modes ahead of the endpoint reference. Nothing is wasted, though the telegraphic style costs some readability.

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

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

For a simple two-parameter read with full schema coverage and no output schema, the description is minimally viable. It omits the sibling relationship and any not-found semantics, which are the remaining gaps an agent would want.

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%: the schema already explains that 'by' selects which identifier 'value' is, and enumerates login/id. The description mirrors this without adding format constraints or examples, 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 identifies the resource (a single user) and the two lookup modes (login or id), which distinguishes it from bulk retrievals. However, it never names the obvious sibling synchroteam_list_users as the alternative, and 'One user' is a fragment rather than a stated verb+resource 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?

There is no guidance on when to use this versus list_users, nor on prerequisites such as whether the id is internal or external, or what happens when the login doesn't exist. The agent must infer the use case entirely from the name.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the notable range behavior ('return anything overlapping that range') but omits return shape, pagination behavior, and any auth/rate-limit context, so it adds only modest value beyond the annotations.

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

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

Two tight sentences plus the endpoint, with the resource and its sub-types front-loaded before the range rule. The trailing 'GET /activity/list' is mildly redundant but costs nothing.

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 11-parameter, zero-required listing tool with no output schema, the definition covers what activities are and how the date range behaves, and the schema carries pagination and sorting. It does not describe what a returned activity record contains or how the filters (team, user, activity type) combine, which matters more here because no output schema exists.

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 55% across 11 parameters, so roughly half the filters (team_id, user_id, sort, activity_type_name, activity_type_category) rely on the agent inferring meaning. The description contributes genuine added semantics for the date pair (mutual requirement plus overlap selection), which the schema only partially expresses, but it leaves the remaining filters unexplained.

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 concrete verb+resource ('List time entries and unavailabilities of technicians') and disambiguates the vague tool name 'activities' by enumerating the four activity categories. An agent can tell this apart from sibling list tools such as list_users or list_teams 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?

It states the coupling rule for start_date/end_date and the overlap semantics, which is real usage guidance, but it offers no when-not-to-use conditions and never names an alternative sibling (e.g. when to use list_users vs this). Usage is implied rather than fully directed.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds only the HTTP endpoint (GET /contract/list) and nothing else behavioral, such as the default active=true filtering or how paging continues across calls.

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 resource and filter scope are front-loaded ahead of the endpoint detail.

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, no-output-schema list tool the description is serviceable but thin: it omits paging behavior, sort options, the dual id/my_id identifier scheme, and the default active filter. Nothing is misleading, but an agent would need the schema 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 50%, so half the parameters (name, site_id, site_my_id, customer_id, customer_my_id, sort) are undocumented in both places. The description partially compensates by naming filter groups (name, customer, site, period, active), but it does not explain the id vs my_id distinction or the sort 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 (List) and resource (service contracts) and enumerates the filter dimensions the caller can narrow by. There is no sibling contract tool to distinguish from, so the main gap is that the filter nouns ('period') are looser than the schema's start/end fields.

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 filter list: use it to find contracts by customer, site, date range, or active state. No explicit when-to-use vs alternatives, no note that inactive contracts are hidden by default, and no pagination guidance, though the absence of a competing contracts tool lowers the burden.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes the return-field set and the underlying endpoint, which is useful context, but says nothing about pagination behavior, result caps, or permission requirements beyond what the schema states.

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 tight sentences, front-loaded with the action and filters before the return payload and endpoint. Nothing is padding, though the trailing 'GET /customer/list' is of marginal value to an agent choosing a 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?

With 8 optional parameters, no required inputs, a rich 88% schema and full annotation coverage, the description is nearly sufficient, and it helpfully compensates for the absent output schema by naming the returned fields. The remaining gap is sibling differentiation from get_customer and create_customer.

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 88%, so parameters (wildcard name, exact e-mail, active flag, changed_since, paging) are already well documented in the schema. The description only restates a subset of these filters ('name wildcard, e-mail, active flag, change time') without adding syntax, defaults, or edge-case behavior. 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 ('list or search') and resource ('customers'), enumerates the filterable dimensions, names the return fields, and even cites the backing endpoint GET /customer/list. It stops short of distinguishing itself from the sibling synchroteam_get_customer, so an agent still has to infer that this is the bulk/collection variant.

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 'list or search' plus the parenthetical filter list implies when filtering is appropriate, but there is no explicit when-to-use statement, no prerequisites, and no pointer to the single-record alternative synchroteam_get_customer. Usage must be inferred rather than read.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful domain context (depots include vans as well as warehouses) and the GET /depot/list endpoint, but does not describe pagination or result shape beyond what the schema implies. Adequate, not rich.

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

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

Two short sentences with zero filler; the resource definition is front-loaded and the cross-reference to the sibling follows. Every clause 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 read-only list tool with no output schema, the description covers identity, scope and the sibling handoff, and annotations carry the safety profile. The main remaining gap is any explicit statement about pagination, which the schema only partially covers via page/page_size.

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 71%, so most parameters (name wildcard search, page/page_size, sort, sort_order, is_provider, is_default) are already documented in the schema. The description adds no parameter-level meaning at all, so it neither compensates for the uncovered params nor exceeds 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 and resource ('List stock depots') and immediately disambiguates the resource by defining depots as warehouses and technician vans. It also explicitly distinguishes itself from the sibling synchroteam_get_depot, which retrieves part quantities for one depot.

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

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

The description routes the agent: use this to enumerate depots, use synchroteam_get_depot when the part quantities of one depot are needed. It gives clear context and a named alternative, but offers no explicit exclusion or prerequisite guidance (e.g. filtering behavior of the name param, pagination expectations).

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds essentially only the HTTP route (GET /equipment/list), which is redundant with readOnlyHint, and says nothing about result limits, default paging behavior, or how the wildcard name search behaves.

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 filler; the capability and the filter dimensions are front-loaded and the endpoint is relegated to a trailing clause. Every phrase 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 zero-required-parameter list tool with 11 params, no output schema, and only 55% schema coverage, the definition leaves the agent without any description of the response shape, paging results, or defaults. Adequate to invoke, but not complete for this complexity level.

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 55% across 11 parameters, and the description names roughly half the filter concepts (name, customer, site, active, change time) but omits sort, sort_order, page, and page_size entirely. It therefore partially compensates for the coverage gap rather than fully filling it, which is the baseline 3 case.

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

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

States a specific verb (list/search) and resource (equipment/assets), and enumerates the filterable dimensions, so an agent immediately knows this is a filtered-collection read. It does not explicitly contrast with the sibling pair get_equipment or create_equipment, so it falls just short of the top band.

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 list of filterable fields ('by name, customer, site, active flag, change time') implies the intended use case of browsing/filtering equipment, but there is no explicit when-to-use statement, no exclusion of alternatives (e.g. use get_equipment when you already have an ID), and no guidance on pagination for large result sets.

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, destructiveHint=false and openWorldHint=true, and the description merely restates this with '(read only)'. It adds no behavioral context beyond the endpoint path — nothing about pagination behavior, rate limits, or result-size caps — despite 14 filter/paging parameters where such context matters.

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 dense sentences, zero waste: the purpose and returned fields come first, then the filter dimensions. Nothing redundant given the schema does the rest.

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 field enumeration (number, status, customer, job, lines, totals) usefully compensates. Combined with the read-only statement and filter categories, an agent has enough to call it correctly, though pagination expectations remain only in the schema param descriptions.

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 43% schema description coverage, the description carries extra burden. It names the filter families (status, customer, site, job, time) which maps to status/customer_id/site_id/job_id/paid_since/changed_since/created_since, but it does not clarify the id vs *_my_id duplication or the page/page_size/sort_order mechanics, leaving material gaps.

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 invoices') and enumerates the returned fields (number, status, customer, job, lines, totals), so the agent knows exactly what this returns. It implicitly separates itself from the singular synchroteam_get_invoice sibling, but never names that alternative, so it falls short of full sibling differentiation.

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

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

'Filter by status, customer, site, job or time' tells the agent what filtering is possible but not when this tool is preferable to get_invoice or the other list_* siblings, nor any exclusions or prerequisites. Usage is implied by the filter list 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 readOnly=true and destructive=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations by disclosing that results are simplified and exclude report, parts, and time entries, which shapes what the agent can rely on. It omits rate-limit or auth notes, keeping it just short of 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?

Two tight sentences front-loaded with the crucial simplification note, followed by a compact endpoint reference. Every element earns its place, with only the raw 'GET /job/list' being marginal.

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 25-parameter, zero-required list tool with no output schema, the description conveys content scope, filter surface, and the sibling for full records. Pagination semantics are left to the schema, which is acceptable; nothing critical is missing.

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

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

Schema coverage is 72% with 25 parameters, so the schema documents most fields itself. The description adds conceptual grouping of the filter dimensions (status, schedule window, technician, team, customer, site, equipment, job type, project) but no format or interaction semantics beyond what the schema provides. 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 jobs'), explicitly scopes the content as simplified (no report, parts or time entries), enumerates the filterable dimensions, and names the sibling synchroteam_get_job as the full-record alternative. An agent can distinguish this from both get_job and the other list_* tools.

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 to synchroteam_get_job when the full record is needed, establishing the when-to-use contrast. It lacks explicit when-not conditions or references to the other list_* siblings, but the primary alternative is named with clear rationale.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the GET /jobtype/list endpoint and the returned field set; it says nothing extra about pagination limits beyond what the schema documents. Adequate but not additive.

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 purpose and result fields, then the downstream-use hint. Zero 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 read-only list tool with three optional, fully documented parameters and complete annotations, the definition covers purpose and return shape (which partly compensates for the absent output schema). Minor gap: no note on paging behaviour or total counts in the description, though the schema handles next_page.

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 name, page and page_size are already fully documented (including the 'pass the previous reply's next_page' instruction). The description's 'id or name when creating a job' hints at the identity semantics of results but adds no parameter-level detail. Baseline 3 is correct.

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 job types') and enumerates the fields returned (name, default duration, priority, skills, default report). It also names the endpoint and ties the result to a downstream action ('use their id or name when creating a job'), which separates it cleanly from the create/update siblings.

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

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

Gives clear context: call this to obtain the ids/names needed by create_job. It does not state when the name filter is preferable to unfiltered paging, nor any exclusions, but no ambiguity about when the tool applies.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally; the description adds essentially nothing behavioral beyond the name and the GET endpoint path. It does not mention result shape, pagination semantics beyond what the schema documents, or any scoping of the returned 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 compact sentences with the purpose front-loaded and no filler; the endpoint path is a small but useful addition. There is no bloat to trim, though the parenthetical reads as a terse parameter dump rather than deliberate structure.

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 9-parameter, zero-required listing tool with no output schema, the description is minimally adequate: filters and pagination are covered by the schema, but it never clarifies what a part request contains or how the result set is bounded. Annotations cover safety, so nothing critical is wrong, but the definition does just enough.

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 56%, leaving the four status booleans (is_sent, is_urgent, is_complete, is_deleted) undocumented in the schema; the parenthetical '(urgent, sent, completed, deleted flags)' maps to exactly those and compensates partially. The remaining parameters (changed_since, created_since, sort_order, page, page_size) are already well described in the schema, so the net addition is modest.

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 ('List technicians' part requests') and names the entity being listed, which separates it from synchroteam_list_parts (the catalog of parts) and other list_* siblings. It stops short of explicitly contrasting with list_parts or explaining what a 'part request' is versus a part.

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 guidance, no mention of prerequisites, and no reference to alternatives such as synchroteam_list_parts or synchroteam_get_part. The parenthetical flag list hints at filtering but never tells the agent when this tool is the right 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's field list partially compensates for the absent output schema, but it says nothing about pagination behavior, result caps, or ordering defaults that matter for a listing 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?

A single tight sentence with the resource and field coverage front-loaded; nothing is padded. The trailing 'GET /part/list' endpoint note is mildly redundant for an agent but costs little.

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 11 optional parameters, no output schema, and 45% schema coverage, the description supplies the useful return-field list but omits any explanation of filtering, sorting, or paging semantics. It is minimally adequate rather than complete for a tool of this complexity.

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 45% (below the 50% threshold), and four enum parameters plus category_id/category_name have no documented meaning. The parenthetical field list describes output columns such as price and tax, which are not parameters at all, so the description does not compensate for the filter-semantics gap.

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

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

States a specific verb ('List') and resource ('the parts and services catalog') and enumerates the returned fields, so an agent can distinguish it from get_part and list_part_requests. It does not explicitly contrast itself with those siblings, but the catalog-scope verb is clear.

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

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

There is no statement of when to use this tool versus get_part (single item) or list_part_requests, and no prerequisites or exclusions. The agent must infer usage entirely from the name and schema.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the GET endpoint and the filterable dimensions but says nothing about pagination behavior, result caps, or what 'projects' contain beyond being groups of jobs. Useful but modest added context.

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

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

Two short sentences, front-loaded with the action and resource, with the disambiguating parenthetical placed where it matters. No filler.

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

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

For an 11-parameter, zero-required read tool with no output schema, the definition covers the verb, the object, and the filter axes but omits pagination guidance and any hint of the returned record shape. Adequate to invoke, not complete for a broad list endpoint.

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 27%, so the description must compensate, and it does partially by naming the four filter dimensions (customer, site, equipment, project type) that map to customer_id/equipment_id/site_id/type_id. It does not explain the _id vs _my_id parameter pairs, type_name vs type_id, or the zero-required-parameter nature, leaving several undocumented parameters unresolved.

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 projects') and immediately disambiguates the domain object as 'groups of jobs,' which distinguishes it from the sibling synchroteam_list_jobs. It also gives the underlying endpoint. It stops short of naming siblings explicitly, so it is clear but not maximally differentiated.

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?

Listing the filter dimensions (customer, site, equipment, project type) implies when this tool is appropriate, but there is no explicit when-to-use versus list_jobs guidance and no note that all filters are optional. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so '(read only)' merely restates structured data. The description adds nothing about pagination behavior, filtering constraints, or result volume that would help an agent call it 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?

A single tight sentence with the field list front-loaded and the endpoint appended. No wasted words, though the field enumeration arguably belongs in an output schema that does not exist here.

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 list tool with no output schema and low schema coverage, the description omits the filter semantics, pagination expectations, and the default descending sort. It is too thin to let an agent use the tool fully without opening 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 38%, so the description must compensate for the 13 mostly undocumented filter parameters. Instead it lists returned fields rather than explaining filters like status, job_id, customer_id, changed_since, or sorting, leaving most parameters unexplained.

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 quotations') and enumerates the returned fields (number, status, customer, job, lines, totals). The verb 'list' implicitly separates it from the sibling get_quotation, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

There is no guidance on when to use this versus get_quotation or list_invoices, and no mention of prerequisites or filtering context. The endpoint 'GET /quotation/list' is the only routing hint.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds little beyond that, only the backing endpoint 'GET /site/list' and the fact that results can be filtered; it says nothing about pagination or result shape that the annotations don't already imply.

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?

A single compact sentence that front-loads the action and resource, then lists filter axes, then names the endpoint. No filler and nothing redundant.

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

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

For a 9-parameter read-only list tool with strong schema coverage, the description plus annotations give an agent enough to invoke correctly. It stops short of describing the return payload or pagination flow at any point, which matters slightly given there is no output schema, but the 'page' parameter's next_page hint partially compensates.

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 89%, so the schema already documents the 9 parameters in detail (defaults, ranges, wildcard search, next_page chaining). The description merely names filter categories that map onto those same parameters, adding no syntax or format detail beyond the schema.

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

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

States a specific verb pair (list/search) and resource (sites), plus a helpful gloss that a site is a customer's location. It does not, however, distinguish itself from close siblings like synchroteam_get_site or synchroteam_list_customers, so the agent must infer the boundary.

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 mention of search dimensions (name, customer, active flag, change time) implies when this tool is useful, but there is no explicit when-to-use versus get_site (single-record retrieval) or any stated exclusions. Guidance is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results include member counts and tags, plus the underlying endpoint, which is useful context beyond annotations but not rich behavioral detail (no rate limits, no pagination behavior).

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: the return-value hint is front-loaded and the endpoint trails. Zero filler, easily scannable.

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 partially compensates by naming the returned fields, but says nothing about pagination responses (next_page is referenced only in the schema) or the meaning of the deleted/active filter. Adequate but with clear gaps for a paginated 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 coverage is 75%, so the schema largely documents the parameters itself; the description adds nothing about filtering semantics. Notably the 'show' enum (active/deleted/all) has no description anywhere, so the description misses a chance to compensate on that one gap.

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

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

States a specific verb+resource ('List teams') and even names the return payload ('member counts and tags'), which is more than most list tools offer. It is unambiguous against siblings, though it does not explicitly distinguish itself from other list_* tools since no competing team tool exists.

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 context, prerequisites, or guidance on filtering versus pagination is given. The usage is only implied by the 'List' verb and the optional filter parameters in the schema.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured context — that passwords are never returned, and that this maps to GET /user/list — which is exactly the kind of extra disclosure that earns credit above the annotation baseline.

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 plus the endpoint path, with the verb+resource front-loaded and no filler. Every clause carries information: returned fields, a privacy constraint, and the underlying HTTP route.

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 enumerates returned fields and the profile values, and the schema fully documents all six parameters, so an agent has enough to call it correctly. It doesn't mention pagination behavior or the default 'active' filtering, but those live 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 100% with all six filter/pagination parameters documented in the schema (page, show enum, team_id, team_name, page_size, skilled_trade). The description adds no parameter-level detail, so the baseline 3 applies even though the field list tangentially hints at what can be filtered.

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 users") and enumerates the fields returned (login, name, profile, teams, skills, location), which makes the tool's scope concrete and distinguishes it from singular reads like get_user. It never explicitly contrasts itself with siblings such as list_teams or get_user, 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?

No explicit when-to-use or when-not-to-use guidance is given; the agent must infer from the name that this is the enumeration tool and that get_user is for a single record. Usage is implied but not stated, matching a 3.

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 by disclosing side effects: Synchroteam may notify technicians and/or customers via email/SMS/webhook per account settings, and SMS consumes paid credits. It also names the underlying POST endpoint. It stops short of stating permission requirements or failure modes, so not a 5.

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

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

Three tight sentences, front-loaded with the 'WRITE:' marker and the core action, followed by the side-effect caveat and the endpoint. Every clause carries distinct 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?

For a 7-parameter mutation with a nested technician object and no output schema, the description covers the identity constraint, timing semantics, re-scheduling behavior, and notification side effects. It omits auth/permission requirements and any error handling, which is the main 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%, so the baseline is 3, but the description adds a real constraint absent from the schema: the job must be identified by exactly one of id, my_id or num. It also reinforces the technician lookup route, adding meaning beyond the field 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 with scope: 'schedule a job for a technician between two times', and explicitly notes it also re-schedules scheduled or paused jobs. This distinguishes it from create_job, start_job, and complete_job without the agent needing to open 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 operating context (schedule/re-schedule a job, identify the job by exactly one of id, my_id or num) and names synchroteam_list_users for technician lookup. It does not explicitly say when to prefer this over start_job or create_job, but the write-vs-lifecycle distinction is inferable.

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 starting a job pauses the technician's other started job, that account-level 'job started' notifications (email/SMS/webhook) may fire to managers, technicians or the customer, and names the underlying POST /job/start endpoint. These are non-obvious side effects an agent must anticipate before invoking, and they align with (rather than merely repeat) destructiveHint/readOnlyHint.

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?

A single dense paragraph with zero filler: the mutation flag and outcome are front-loaded, followed by side effects, then the identifier rule and endpoint. Every clause carries information an agent needs.

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

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

For a mutation tool with no output schema, the description covers outcome, side effects and identifier selection, which is most of what is needed. It stops short of stating what happens on an already-started job (annotations say idempotentHint=false, but the description stays silent) or what response/record is returned.

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 a constraint the schema does not encode: the three identifiers are mutually exclusive and exactly one must be supplied. That is real added value for a schema with zero required parameters and no oneOf/anyOf construct.

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 (mark a job as started) and clarifies the concrete effect (status 'started', actual start timestamp now), which is more than the name and title convey. The 'WRITE:' prefix plus the start-state semantics cleanly separate it from siblings such as synchroteam_complete_job, synchroteam_create_job and synchroteam_schedule_job.

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

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

It gives a concrete selection rule for identifiers ('exactly one of id, my_id or num'), which is genuinely useful. However, it never states when to choose this tool over synchroteam_complete_job or synchroteam_schedule_job, nor any precondition (e.g. only for jobs in a pending/assigned state). Usage is only implied from the verb.

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 carry destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the write profile is known; the description adds genuinely new context by clarifying PATCH-style semantics ('only the fields you pass are changed; nothing is cleared') and the failure mode for an unknown id. It also exposes the underlying endpoint (POST /customer/send), though it is silent on permissions or response shape.

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 write nature and the update semantics; each sentence carries a distinct fact (verb/resource, partial-update behavior, precondition, transport). 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 mutation tool with no output schema, the description covers the essential agent-facing facts: it is a write, it is a partial update, and it requires an existing id. The remaining gap is parameter-level documentation, which the low schema coverage leaves partially 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?

Ten parameters with only 30% schema description coverage, and the description documents none of them at the field level beyond restating that 'id' is a numeric identifier. The unlabeled fields (name, vat_number, contact_* ) rely entirely on self-explanatory names and maxLength constraints, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('change fields of an existing customer'), adds the 'WRITE:' prefix that immediately separates it from the read-oriented siblings, and names the addressing key ('by its numeric id'). An agent can distinguish it from synchroteam_create_customer and synchroteam_get_customer 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: the id must already exist (unknown id fails) and only passed fields are changed, which is exactly what an agent needs to decide between a partial update and a create. It does not, however, name an alternative tool or state when to prefer create/get instead, so it stops short of explicit routing.

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