Bilflo MCP by usefulapi

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

The annotations already establish that this is a non-read-only, non-idempotent, non-destructive write with open-world effects. The description adds useful context beyond that: the new client is visible company-wide, is used for billing, and returns its id. It does not cover permissions or error behavior, but the annotation coverage lowers that burden.

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

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

The description is front-loaded with "WRITE" and packs purpose, visibility, duplicate guidance, return value, and endpoint into three tight sentences. There is no redundant or filler language.

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 one-parameter write tool with rich annotations and no output schema, the description provides what an agent needs: what it creates, what it returns, the duplicate risk, and the endpoint. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% and the sole parameter business_name is already documented in the schema. The description confirms that business_name is the input, but adds no format or validation detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: "creates a new client (customer) in Bilflo." It also identifies the required business name and return value (id), so an agent can distinguish it from sibling tools such as bilflo_get_client, bilflo_list_clients, and bilflo_update_client.

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

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

It gives a clear precondition: check bilflo_list_clients first to avoid creating a duplicate. The usage context is strong, though it does not explicitly say to use bilflo_update_client for existing clients instead of creating a new one.

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 useful context about the response containing addresses and contacts, but says nothing about missing-client behavior, permissions, 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, front-loaded with the result rather than the mechanics. The raw endpoint path is mild filler but not enough to hurt.

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 partially compensates by naming the embedded collections (addresses, contacts). For a read tool with full annotation and schema coverage this is close to adequate, but the shape of the returned client object remains undefined.

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

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

Schema description coverage is 100% and the single parameter is fully documented, including its provenance (from bilflo_list_clients). The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (one client) and clarifies the payload includes addresses and contacts. It is distinguishable from bilflo_list_clients by the singular client id, though it never names that sibling explicitly.

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

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

Usage is implied by the singular {clientId} path and the schema note pointing at bilflo_list_clients as the id source. There is no explicit when-to-use guidance versus siblings like bilflo_list_client_addresses or bilflo_list_client_contacts, even though the description notes those are bundled in the response.

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 returned data are static lookup/config lists rather than transactional records, which is useful context, but it says nothing about response shape, volume, or whether the lists can be empty.

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?

Very short and front-loaded with the set of valid settings. The trailing 'GET /v1/CompanySettings/{setting}' is largely redundant with the tool name and annotations, slightly diluting the value of the two sentences.

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?

Adequate for a one-parameter read with a fully documented enum and read-only annotations, but with no output schema the description should say more about what each list yields (e.g., codes, labels) so an agent can judge whether the call is worth making.

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 enum parameter is documented as 'Which list to read.' The description merely repeats the same enum values already in the schema, adding no new meaning about what each list contains.

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

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

Names the resource (company lookup lists) and enumerates the exact setting types, and the GET endpoint implies a read. It lacks an explicit verb like 'retrieve', but the resource and scope are unambiguous enough that an agent knows what it fetches.

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 guidance on when to choose this tool versus siblings such as bilflo_list_custom_field_items or bilflo_list_overtime_rules, and no preconditions or exclusions. Usage is only inferable from the word 'lookup lists' and the endpoint path.

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 context — that the response is a rich per-job dossier including overtime rule, timecard method, and workers' comp burden — but says nothing about auth requirements, rate limits, or behavior for an unknown job_id.

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

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

Two compact clauses front-load the entity definition and then the field inventory; nothing is redundant. The field enumeration is long but each item conveys real response content that has no output schema to carry it.

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 enumerated field list is doing important work in telling the agent what a successful read returns, and annotations cover the safety profile. Missing only the edge cases (not-found behavior, whether all listed fields are always populated).

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

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

Schema description coverage is 100%, and the single job_id parameter is already documented as 'Bilflo contract job id.' with a positive integer constraint. The description adds no format, sourcing, or lookup guidance beyond the schema, so the baseline of 3 applies.

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

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

The description states the resource precisely — a single contract job, glossed as 'a contractor placed with a client' — and enumerates the fields it surfaces, plus the backing endpoint. That gloss distinguishes it from the sibling bilflo_get_contractor and bilflo_get_direct_hire, though it never names those alternatives explicitly.

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

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

There is no when-to-use guidance: nothing says to call this to hydrate a job record before update/terminate/reopen, and no exclusions versus list-type or adjacent getters. The only usable cue is the singular jobId in the path, which implies single-record retrieval but leaves the routing decision to the agent.

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, and the description still adds genuinely useful behavior: SSN, date of birth, and bank details are stripped from the response. This redaction disclosure is exactly the kind of context annotations cannot convey. Auth requirements and error behavior remain unstated, so 4 not 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-load the returned fields and then the redaction caveat, with no filler. The trailing endpoint path (GET /v1/Users/contractors/{contractorId}) is mildly redundant with the tool name but provides useful provenance.

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

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

There is no output schema, and the description compensates by enumerating the returned sections and explicitly flagging which sensitive fields are omitted. Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% with a single documented integer id, so the schema does the heavy lifting and baseline 3 applies. The description adds no format, range, or lookup guidance beyond what the schema already states.

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

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

The description names the resource precisely ('One contractor') and enumerates the payload (profile, jobs, checks paid, work status, benefit settings, custom fields), so an agent can tell this is a single-record retrieval rather than a mutation like bilflo_update_contractor. It stops short of an explicit verb and never names a sibling to contrast with, which keeps it at 4 rather than 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?

'One contractor' implies fetching a single record by id, and the required contractor_id confirms that shape. However, there is no explicit when-to-use/when-not-to-use guidance and no pointer to an alternative sibling for related needs.

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

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

Annotations already cover the read-only, non-destructive, open-world profile, so the description's job is added context — and it delivers by enumerating the payload sections (header, fee/split data, contacts, custom fields) and noting they are returned 'as Bilflo returns them,' hinting at raw passthrough. It omits failure behavior (e.g., unknown job_id) which keeps it below a 5.

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

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

Two short sentences, zero waste, with the core payload description front-loaded before the endpoint reference. Nothing is padded or 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?

There is no output schema, so the description appropriately lists what the caller gets back (header, fee/split, contacts, custom fields), which is the key missing piece an agent needs. Only the absence of error/not-found behavior 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 coverage is 100% and the single parameter already documents itself as the Bilflo direct hire job id. The description's 'GET /v1/DirectHires/{jobId}' only restates that the id is the path segment, adding little 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 resource (one direct hire), helped by the parenthetical gloss 'a permanent placement' that disambiguates the Bilflo term. The singular 'One' signals fetch-by-id versus the list-style siblings, though the contrast with bilflo_get_contract_job is only implied by naming rather than stated.

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

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

Usage is implied: retrieve a single direct hire by its job id. There is no explicit when-to-use/when-not, no mention of when to prefer bilflo_get_contract_job for contract placements, and no statement of prerequisites such as required id validity.

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 nothing beyond restating the GET path—no return shape, pagination, or error behavior for an open-world read.

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, front-loaded sentences with no filler. The noun-phrase opener is slightly weak as a lead but the content is efficient and the endpoint is unambiguous.

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?

A simple single-param read tool with annotations covering safety; little is strictly missing. But with no output schema, the description could say what the custom field values look like, and it doesn't, leaving the agent to discover the response blindly.

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 job_id is fully documented as 'Bilflo contract job id', so the schema does the heavy lifting. The description only echoes jobId in the path template and adds no extra meaning, matching the baseline for full coverage.

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

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

States a clear resource and scope: 'custom field values of one contract job'. An agent can tell it retrieves data for a single job. However it never distinguishes itself from siblings like bilflo_list_custom_fields or bilflo_list_custom_field_items, which sound closely related.

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 guidance on when to use this versus the plural custom-field list tools or get_contract_job. The only hint is 'one contract job', which implies job-scoped retrieval but doesn't route the agent between 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it enumerates what the payload contains (profile, roles, compensation settings) and states a redaction guarantee (government ids and bank details removed), which an agent would not otherwise know. It stops short of describing error behavior for a missing/invalid id.

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

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

Three compact fragments with zero filler: the resource, the payload contents, the redaction caveat, then the endpoint. The most important information (which entity, what comes back) 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 one-parameter read with annotations covering safety and no output schema, the description covers entity, payload contents and data redaction — enough to call it correctly and interpret the result. Only the not-found/invalid-id behavior is left unstated.

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

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

There is only one parameter and schema description coverage is 100%, with the schema documenting it as 'Bilflo team member (user) id'. The description adds no format, range or lookup-source detail beyond restating the id via the '{id}' path placeholder, 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 names a precise resource — a single back-office team member (staffing company user) — and the endpoint GET /v1/Users/teamMember/{id} supplies the verb and the single-record scope. The parenthetical 'staffing company user' cleanly separates it from the contractor/client getters in the sibling list, though the verb itself is only implied by the endpoint line.

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?

Singular lookup-by-id is implied by '{id}' and the required team_member_id, so an agent can infer this is the detail fetch rather than a list call. However, no sibling is named as an alternative and no condition is given for choosing it over, say, bilflo_get_contractor or any list tool.

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 useful detail that results include both work sites and billing addresses, but says nothing about pagination, result ordering, or what happens for a client with no addresses.

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 the resource described first and the endpoint second, so nothing is buried. The raw endpoint path is of marginal value to an agent but is at least confined to one short clause.

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

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

For a simple read-only list tool with a fully documented single parameter, full annotation coverage, and no output schema, the description gives enough to call it correctly and knows what entities come back. Return shape and pagination details are the only notable omissions, and their absence 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 coverage is 100% and the single client_id parameter is documented in the schema, so the baseline of 3 applies. The description reinforces that the id refers to a single client and echoes it via the endpoint path, but adds no format or validity constraints beyond the schema.

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

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

The description names the specific resource (client addresses) and narrows the scope to one client, distinguishing it from siblings like bilflo_list_client_contacts and bilflo_list_client_agreements. It is stated as a noun phrase rather than a verb, but the tool name and the enumerated address types (work sites and billing addresses) make the intent unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as bilflo_get_client, and no stated prerequisites beyond the implied single-client scope. Usage must be inferred entirely from the tool name and the resource description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety profile is covered. The description contributes only the clarifying gloss that an 'agreement' means billing terms; it says nothing about result volume, pagination, or what happens when a client has no agreements on file.

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, front-loaded fragments with zero filler. It is arguably too terse, reading like a docstring fragment rather than guidance, but nothing is wasted.

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

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

For a single-parameter read tool with annotations and no output schema, the description is minimally adequate but leaves the return shape (what fields an agreement carries) and empty-result behavior unstated. An agent knows what to call and how, but not what to expect back.

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

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

Schema coverage is 100% and the sole parameter is documented as 'Bilflo client id.' The description's phrase 'for one client' reinforces single-client scoping but adds no format or sourcing 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?

Names the exact resource (agreements, glossed as billing terms) scoped to a single client, which distinguishes it from sibling list tools like bilflo_list_client_contract_pos and bilflo_list_client_invoice_groups. The verb is only implied by the name/title, not stated in the description text.

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 exclusions, and no pointer to related siblings such as bilflo_get_client or the contract-PO list. An agent must infer selection purely from the tool name and the required client_id.

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, destructive=false and openWorld=true, so safety is covered. The description goes further by disclosing the return payload fields and the HTTP endpoint — useful since there is no output schema. It stops short of pagination, ordering, or empty-result 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 compact sentences with the resource and its fields front-loaded, then the endpoint. Nothing is redundant, though the parenthetical field list is slightly dense for a single sentence.

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

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

For a trivial one-parameter read tool with annotations covering the safety profile, the description supplies the resource scope and the shape of the return data, which is the main thing missing given no output schema. Minor gaps remain around result ordering/pagination and behavior for an unknown client id.

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

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

The single parameter's schema description coverage is 100% ('Bilflo client id.', integer > 0), so the schema does the work. The description corroborates scope ('of one client') and the path placeholder {clientId}, but adds no format, sourcing, or lookup guidance beyond that.

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 the exact resource (contacts of one client) and even enumerates the returned fields (name, title, phone, email, active flag), plus the underlying endpoint. It does not explicitly contrast itself with the adjacent list_client_addresses / list_client_agreements siblings, but the resource noun is distinct enough that an agent can distinguish them.

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 when-to-use guidance, no stated preconditions (e.g. needing a valid client id or that it returns an empty list for clients without contacts), and no mention of alternatives. The only implicit signal is 'of one client', which the schema already conveys.

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 underlying endpoint (GET /v1/Clients/contractPOs/{clientId}) and a hint at returned fields, but says nothing about pagination, volume, or empty-result behavior for an open-world remote call.

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 front-loaded sentence stating the resource, scope, and payload, followed by the endpoint path. No filler, though the endpoint string is of marginal value to an agent compared with 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?

With no output schema, the description's 'PO numbers and amounts' is the only signal of return shape, and it is thin (no id fields, no list envelope, no pagination). For a simple single-parameter read with annotations this is borderline adequate but leaves gaps an agent must discover at call time.

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

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

Schema description coverage is 100% and the sole parameter client_id is documented as 'Bilflo client id.' with a minimum constraint. The description adds no format or sourcing guidance (e.g., where to obtain a client id) 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 resource (contract purchase orders) scoped to a single client and clarifies the payload (PO numbers and amounts used for billing). It is distinguishable from bilflo_list_job_purchase_orders only by inference from the word 'contract' and the client scoping, not by any explicit contrast.

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 single required client_id and the phrase 'of one client', so an agent can infer this is a per-client lookup. However, it never states when to choose this over bilflo_list_job_purchase_orders or the other client sub-resource listers (agreements, invoice groups), nor any prerequisites.

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 endpoint path and the semantic meaning of the returned groups, but says nothing about pagination, result size, or error behavior for an invalid client id.

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

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

Two compact sentences with zero filler; the resource is front-loaded and the endpoint reference trails as supporting detail. Nothing could be removed without losing information.

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

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

For a single-parameter read-only list tool with full schema coverage and annotations, this is nearly sufficient; the one gap is that with no output schema, the description does not indicate the shape of returned groups (e.g., ids/names of grouped jobs).

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

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

Schema description coverage is 100% and the single parameter (client_id, with type and bounds) is fully documented there. The description only echoes the client scoping via the path template, adding no format or constraint detail beyond the schema — baseline 3.

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

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

States the resource specifically ('contract invoice groups of one client') and adds a clarifying gloss — which jobs are invoiced together — that tells an agent what an invoice group actually is. It is distinguishable from the sibling list tools by resource, though the verb 'list' is only implied by the name/title rather than stated.

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

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

The 'of one client' phrasing implies the tool is scoped to a single client and that a client id is required, but there is no explicit when-to-use guidance or reference to alternatives (e.g., other client-scoped list tools or report tools). 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 establish the safe read-only profile. The description adds useful behavioral context beyond annotations: every client is returned at once, the tool filters and pages internally, each row carries counts, and include_details yields large payloads. It does not cover auth or rate limits, but that is a minor gap against 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?

The description is front-loaded, uses three tight sentences, and every element (returned fields, include_details behavior, internal paging) earns its place. The endpoint suffix is a small addition but not wasteful.

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

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

For a read-only list tool with full schema coverage and no output schema, the description sufficiently explains the return shape and paging. The one missing piece is guidance on when to use this versus the dedicated list_client_addresses or list_client_contacts siblings, which an agent might reasonably consider.

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

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

Schema coverage is 100%, so all five parameters are fully documented in the input schema. The description reinforces include_details and notes the internal paging behavior, but adds little beyond what the schema already explains for limit, offset, search, and active_only. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('clients') and enumerates the fields returned, so an agent can tell it is a list operation distinct from get_client. However, it does not explicitly name or contrast with the closest siblings (get_client, list_client_addresses, list_client_contacts), leaving some differentiation implicit.

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

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

The description implies when to use the tool (to retrieve all clients) and explains that filtering/paging happen inside the tool, but it never explicitly says when to prefer get_client or the dedicated address/contact list tools over this one. Parameter-level guidance for include_details is present, but tool-selection guidance is only implied.

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

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

Annotations already establish that this is a read-only, non-destructive operation, so the description's main added value is the privacy behavior: fields named like personal data are excluded from results. That is meaningful behavioral context that an agent would not infer from the annotations or schema.

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

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

The description is compact and front-loaded: it first states what is returned, then the prerequisite source of the id, then a notable filtering rule. There is no redundant or filler text.

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 one-parameter list tool with annotations and no output schema, the description covers the resource, the prerequisite id source, and an important privacy exclusion. It does not describe pagination or exact return shape, but the core information needed to invoke and interpret the tool is present.

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

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

Schema description coverage is 100%, and the single custom_field_id parameter is already well documented in the schema. The description reinforces that the id comes from bilflo_list_custom_fields but does not add format or constraint details beyond the structured field.

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

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

The description clearly identifies the resource and scope: selectable items belonging to one custom list field. It also ties the required id back to bilflo_list_custom_fields, which helps distinguish it from field-listing siblings, though it does not explicitly contrast with alternatives such as bilflo_get_job_custom_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 phrase 'id from bilflo_list_custom_fields,' which signals the prerequisite lookup tool. However, the description does not explicitly state when to use this tool versus other custom-field-related siblings, nor does it provide when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by disclosing that inactive fields are included and that list-type fields carry their selectable items — details an agent could not derive from annotations. It stops short of stating anything about pagination or response size.

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 dense sentence plus the HTTP endpoint — front-loaded and waste-free. The raw endpoint (GET /v1/CustomFields) is marginally redundant but small and aids traceability.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the attributes returned (type, requiredness per service offering, selectable items) and the active/inactive scope. Missing only pagination/shape detail for a potentially long list.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument, company-scoped call.

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 (the company's custom fields) and enumerates the content returned: type, requiredness per service offering, and selectable items for list fields. It does not explicitly name how it differs from siblings like bilflo_list_custom_field_items or bilflo_get_job_custom_fields, though the 'company-wide, active and inactive' framing hints at the distinction.

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 and no alternatives are named, so an agent must infer that this is the definitions-level lookup versus bilflo_list_custom_field_items (per-field values) or bilflo_get_job_custom_fields (job-scoped). The 'active and inactive' note is the only scoping cue.

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 elsewhere. The description adds the underlying endpoint and confirms it is scoped to a single job, but says nothing about pagination, result shape, or what happens when a job has no approvers.

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 very short sentences, front-loaded with the semantic meaning before the raw endpoint path. The endpoint is mildly redundant but still useful for API-literate agents; nothing bloats the definition.

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

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

For a single-parameter read tool with full schema coverage and complete annotations, this is largely sufficient. The one gap is that no output schema exists and the description does not describe what an 'approver' record contains, so the agent cannot anticipate the response.

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

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

Schema coverage is 100% and the single job_id parameter is already documented as 'Bilflo contract job id.' The description reinforces that the id identifies one contract job but adds no format or sourcing guidance 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?

Names a specific resource (approvers) scoped to a single contract job, with the clarifying detail that these are the people who approve timecards. That distinguishes it clearly from other job sub-resource tools like list_job_pay_bill_items or list_job_purchase_orders, though it never explicitly contrasts itself with them.

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 'of one contract job' implies usage is per-job and requires a job id, which is a reasonable contextual hint. However, there is no explicit when-to-use guidance, no mention of prerequisites (e.g., needing an existing contract job), and no named alternative.

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 and the description only needs to add operational context. It adds the REST endpoint and the nature of the returned entities (pay/bill rates such as Regular, Overtime), but says nothing about pagination, ordering, or behavior when a job has no items.

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

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

Two short, front-loaded sentences; the resource description comes first and the endpoint second. Compact with no wasted prose, though the raw REST path is marginal value for an agent that already has structured fields.

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 low-complexity, single-parameter read tool with annotations covering the safety profile and no output schema, the description gives enough to select and call it correctly. The only real gap is what fields a pay/bill item carries in the response, which is hinted at but not spelled out.

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

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

Schema description coverage is 100% and there is only one parameter, documented as 'Bilflo contract job id', so the baseline of 3 applies. The description reinforces that the id scopes to a contract job but adds no format or sourcing guidance beyond the schema.

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

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

Specific verb (list) plus resource (pay/bill items of one contract job), with concrete examples of item types (Regular, Overtime) and the underlying endpoint. It distinguishes itself from the other list_* siblings by naming the exact sub-resource, though it never explicitly contrasts with e.g. bilflo_list_job_purchase_orders.

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

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

Usage is only implied: the tool clearly targets a single job's pay/bill rates, and the required job_id makes the calling context evident. There is no statement of when to prefer this over fetching the contract job itself (bilflo_get_contract_job) or the other job-scoped list tools, and no prerequisites or 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 readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description only restates the REST path; it says nothing about pagination, result ordering, auth requirements, or what an empty response means for a job with no POs.

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?

Extremely short and front-loaded: the resource scope comes first and the endpoint follows. The raw GET path is arguably low-value for an agent but costs only a fragment, and nothing is buried.

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

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

For a simple single-parameter read with full annotation coverage this is close to sufficient, and no output schema exists to explain the return values. Still, a brief note on response shape or pagination would help the agent know what 'the purchase orders' actually yields.

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

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

There is a single parameter, job_id, documented at 100% schema coverage ('Bilflo contract job id'). The description's path template reinforces that the id identifies the job but adds no format, range, or sourcing guidance 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?

Names a concrete resource ('purchase orders') and scopes it to a single contract job, which distinguishes it from a global PO listing. It lacks an explicit verb, relying on the tool name 'list' and the raw endpoint path to convey that this is a retrieval operation, and it does not contrast itself with the similar sibling bilflo_list_client_contract_pos.

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 tool versus alternatives, no prerequisites (e.g., needing a valid contract job id), and no mention of the closely related bilflo_list_client_contract_pos tool. The agent must infer usage entirely from the resource 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 needs no restating. The description adds that results are id/name/state tuples, but says nothing about pagination, ordering, or whether the list is company-scoped beyond "the company's".

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

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

Three short fragments, zero filler, with the return fields and the follow-up tool front-loaded. Slightly telegraphese, but 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 no-param, read-only list tool with annotations covering safety and no output schema, the description supplies enough: what comes back, where it comes from, and what to do with the ids. Only pagination/size expectations are 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?

The tool takes no parameters, so the baseline is 4; the description correctly signals a parameterless list call rather than implying hidden filters.

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

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

Names the resource (company overtime rules) and enumerates the returned fields (id, name, state), plus the endpoint GET /v1/OvertimeRules. The verb is only implied by the tool name/title, but the scope is unambiguous and no sibling tool covers overtime rules.

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

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

"Use the ids with bilflo_update_contract_job" gives concrete downstream usage, which is genuinely helpful. However, it never states when an agent needs overtime rules or that there is no filtering/parameter variant; usage is implied rather than framed as a when/when-not decision.

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 enumerating the exact side effects: job becomes active, end date is cleared, contractor made active, and missing timecards from the reopen week are created. It also discloses both failure modes and confirms the underlying endpoint. The annotation set only says non-read-only, non-idempotent, non-destructive; the description supplies the real behavioral picture.

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

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

Front-loaded with a "WRITE:" marker, then a single dense sentence covering action plus all side effects, followed by failure conditions and the 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?

For a two-parameter mutation with no output schema, the description covers preconditions, side effects (including a non-obvious timecard backfill), and failure cases. An agent can decide whether to call it and predict the result without further context.

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 both parameters (job_id, reopen_date) carry descriptions including the 'not before job start' constraint and yyyy-mm-dd pattern. The description adds only an indirect hint via "reopen date's week," so baseline 3 is right.

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 (reopens) and resource (terminated contract job), and anchors it to a familiar UI action ("like the Open Job button"). This clearly distinguishes it from the sibling bilflo_terminate_contract_job without needing to open either schema.

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

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

Explicitly scopes applicability: only works on terminated jobs, and fails if the job is not terminated or the company plan lacks room for another active job. It doesn't name the alternative sibling (e.g., create/update contract job) for the non-terminated case, but the precondition is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description corroborates ('Reads data only') while adding non-obvious context: the call is a POST despite being a pure read, and the parameter bag is free-form and report-specific. It does not describe response shape or error behavior, but the safety profile is fully covered.

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

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

Three short sentences, front-loaded with purpose, then the parameter convention with an example, then the safety/endpoint note. Nothing is repeated and nothing is padding.

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

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

For a two-parameter tool with a nested free-form object and no output schema, it covers how to call it but not what the returned rows look like, nor how to obtain a valid report_id given that no sibling lists custom reports. Adequate but with a real practical 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 goes beyond it by exemplifying the parameter map with concrete keys and date-formatted values ({'Start': '2026-01-01', 'End': '2026-01-31'}), which the schema's generic additionalProperties constraints do not convey. It stops short of explaining which keys exist for each report.

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 ('Run one of the company's saved custom reports and return its rows'), and the notion of 'saved custom reports' cleanly separates it from every sibling, which are all get/list/create/update tools for concrete entities. An agent can identify it 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?

Usage is implied rather than stated: it tells the caller this consumes saved report definitions and report-specific key/value parameters, and gives a worked example. It does not say when to prefer it over a sibling resource list, nor where a valid report_id comes from (there is no list-reports sibling), leaving discovery 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 destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description still adds real context beyond that: downstream impact on payroll and invoicing, and that the operation is reversible via reopen, plus the underlying POST endpoint. It does not describe error/failure behavior, but the added value is substantive.

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 a "WRITE:" marker that signals mutation immediately, followed by meaning, consequences, recovery path and endpoint. 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?

For a 2-parameter mutation with rich annotations and no output schema, the description supplies what an agent needs: effect, blast radius (payroll/invoicing), and reversibility. Minor gap is the absence of any note on failure modes (e.g. terminating an already-terminated or invoiced job).

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 both parameters (job_id, end_date with yyyy-mm-dd pattern) are documented in the schema. The description reinforces that the date is the termination date, but adds no syntax or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("ends a contract job") plus the effective date, and the parenthetical defines the operational meaning (contractor no longer placed, no further timecards). It is clearly separable from bilflo_reopen_contract_job and bilflo_update_contract_job, which appear as 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?

The description makes the use case clear (ending a placement on a date) and names the reversal path, bilflo_reopen_contract_job, so an agent knows the escape hatch exists. It stops short of stating explicit preconditions or when to prefer update_contract_job over termination.

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=true and openWorldHint=true. The description adds real behavioral context beyond them: partial-update semantics (unspecified fields are untouched) and the concrete destructive consequence of is_active=false deactivating the client, which explains why destructiveHint is true. It doesn't cover permission requirements or failure modes.

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

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

Three short sentences, front-loaded with a 'WRITE:' marker and the partial-update rule before the field list and endpoint. Nothing is wasted.

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

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

For a mutation tool with no output schema, the description plus annotations cover the essentials: partial semantics, the destructive deactivation path, and the endpoint. Missing only peripheral details like error behavior or permission prerequisites.

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

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

Schema coverage is only 33%, so the description carries weight here and does: it enumerates all five writable fields (business name, client code, phone, fax, active flag) and explains that is_active=false deactivates while true reactivates. Length/format constraints remain schema-only, which is fine.

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 (partial update), the resource (client), the exact settable fields, and even the underlying PATCH endpoint. The 'changes only the fields you pass; the rest stay as they are' phrasing cleanly separates it from create/replace-style 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?

Makes the use case clear: partial modification of an existing client, including the deactivation path via is_active=false. It does not explicitly name alternatives (e.g., use bilflo_create_client for new clients) or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety bar is lower, and the description usefully adds true PATCH semantics ('the rest stay as they are') plus a payroll/invoice impact warning. However, the sentence 'Pay and bill rates change payroll and invoices' refers to fields that do not exist in this schema at all, which is a misleading behavioral signal for a mutation tool. No mention of failure modes for an invalid job_id.

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

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

Three tight sentences with the operation mode front-loaded and the endpoint last; almost every clause carries decision-relevant information. The pay/bill-rate clause is the one sentence that does not correspond to any schema parameter, so it is the sole dead weight.

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 destructive mutation with no output schema, the description covers partial-update semantics, the field scope, the excluded fields, and a user-confirmation requirement. An agent could call this correctly from the definition alone; only response behavior and error handling on a bad job_id are left uncovered.

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

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

At 40% schema coverage the description must compensate, and it does: it maps the updatable surface (title, overtime rule, workers' comp code, burden, per-diem/expenses/sick-time/meal-period flags) onto the nine optional properties and explicitly excludes the fields that look editable but are not. It stops short of explaining the boolean flags' on/off meaning or the burden_manual scale.

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?

Opens with an explicit 'WRITE:' marker, names the resource (contract job), and enumerates exactly which fields the call mutates, ending with the concrete PATCH /v1/ContractJobs/{jobId} endpoint. Among siblings like bilflo_create_contract_job, bilflo_terminate_contract_job and bilflo_reopen_contract_job, this is unambiguously the partial-field-mutation tool.

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 explicit non-goals ('Client, contractor, dates and status cannot be changed here'), which routes the agent to terminate/reopen or other tools, and adds a confirmation instruction for rate changes. What's missing is a named alternative for the excluded operations rather than an implicit pointer.

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 and idempotentHint=true; the description adds the genuinely useful behavioral fact that this is a partial PATCH — fields not passed retain their values — which the annotations cannot express. It does not explain why destructiveHint is set for a contact edit (e.g. overwrite risk) or any auth/permission requirement, leaving a small gap.

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

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

Two dense sentences, front-loaded with the WRITE marker and the partial-update guarantee, then exclusions, then the endpoint. No filler and 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 14-parameter PATCH with no output schema and only partial-update semantics at stake, the description covers field scope, exclusions, and HTTP semantics sufficiently to call it correctly. It omits only the response shape and validation/failure behavior, which is acceptable given 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 description coverage is only 21%, so the description must carry weight, and it does: 'name, title, email, phone, address, company' maps onto all 13 optional properties (first/middle/last_name, title, email_address, phone/phone_ext, address1/address2/city/state_code/zip_code, contractor_company). The remaining schema descriptions cover contractor_id semantics, so only format-level details (state_code two-letter, email pattern) rely on 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?

Opens with an explicit write verb and resource ('WRITE: changes... contractor contact fields') and pins the endpoint (PATCH /v1/Users/contractors/{contractorId}). The scope statement makes it trivially distinguishable from bilflo_update_client and bilflo_update_contract_job despite the shared 'update_*' naming pattern.

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 positive condition (use this for contact details) and an explicit exclusion list (tax, bank, SSN, activation are not changeable here), which prevents misfires. It stops short of naming the sibling tool that should be used for those excluded fields, so the agent must infer the redirect.

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