Field Service Business Platform by Doing Work

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

With no annotations provided, the description carries the full behavioral burden and does well: it explains the returned user_code and verification_uri, what the human must do, the subsequent token polling step, and the important side effect that reusing the same claim_token cancels the old code and issues a fresh one. It omits code expiration, error behavior, and permission requirements, keeping it from a 5.

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

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

The description is appropriately sized and mostly front-loaded: purpose, parameters, output/instructions, next polling step, and idempotency note. The opening 'auth.md claim' is slightly cryptic, and the long grant_type string is heavy, but no sentence 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?

Given that there are no annotations, no parameter descriptions in the schema, and an output schema exists, the description is sufficiently complete for an agent to execute the flow. It covers the human handoff and polling step, though it lacks details on code expiry, error cases, and where the token endpoint URL is defined.

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 0%, so the description must compensate for both parameters. It explains that claim_token is the caller's token and email identifies the shop owner who should claim the agent, and it additionally clarifies reuse semantics for claim_token. It does not explain where the claim_token comes from or any format constraints.

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

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

The description clearly states that this tool initiates an agent claim flow: pass a claim_token and the shop owner's email, receive a user_code and verification_uri, and then poll the token endpoint. It is specific about the action and outcome, but it does not explicitly distinguish itself from sibling tools like agents_register or auth_oauth*.

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 flow implies when to use it—when an agent needs a shop owner to claim it—but there is no explicit guidance on when to choose this over agents_register or other auth tools. It gives operational context and a reuse caveat but no exclusions or named 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?

Without annotations, the description does disclose notable behavior: shop creation when scope is omitted, a duplicate-registration guard, claim-token conditions, and verification_uri truncation handling. However, it omits auth requirements and rate limits, and includes confusing guidance such as "identity_assertion is not accepted" despite the enum permitting it.

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 a dense run-on paragraph of operational instructions, not front-loaded with purpose. It jumps among response fields, claim flow, scope side effects, and type rules, making it hard to follow despite containing some useful content.

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

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

For a 6-parameter registration tool with no annotations, the description leaves several parameters unexplained and never clearly states the tool's overall purpose or authentication expectations. The output schema reduces the need to explain return values, yet the description spends much space on response-field handling instead of completing parameter and behavioral 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 0%, yet the description only partially clarifies type and login_hint, mentions a scope side effect, and refers to read_only even though no such parameter exists. It leaves assertion, assertion_type, and client_name undocumented and contradicts the enum by rejecting identity_assertion.

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 never plainly states that this tool registers an agent; it opens with a usage condition ("Preferred when you know the owner's email") and then focuses on response fields and claim flow. The name and token references imply registration, but the purpose remains vague and is not clearly differentiated from agents_claim.

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 explicit type selection guidance (service_auth with login_hint, anonymous without email), when not to re-register, and when to call the claim endpoint. These are actionable conditions, though the prose is hard to parse and does not explicitly name agents_claim.

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

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

With no annotations, the description carries the full burden, and it does disclose genuine behavioral traits: role-based visibility (owner and office see any, a field worker only their own) and that the action result exists only after approval and execution. It says nothing about what happens for a nonexistent or unauthorized id (error vs. not-found), which matters for a permission-scoped 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 sentences, both load-bearing, with the return content front-loaded and the access rule second. It opens with a noun phrase rather than a verb, but there is no filler at all.

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

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

For a one-parameter read with no annotations and no output schema, the description covers what is returned and the visibility model behind it. The remaining gap is error/permission-failure behavior, which is minor given the tool's simplicity.

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 0% for the single approval_id parameter, and the description adds no clarification about it. The parameter is nonetheless self-evident from its name and the schema's `format: uuid`, so the practical gap is small rather than severe.

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 a specific resource (one approval request) and states what comes back (status, plus the action's result once approved and run). The word "One" implicitly distinguishes it from approvals_list, but the sibling is never named, so the differentiation is inferred 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 only implied: a singular-resource tool taking an approval_id is obviously the lookup-by-id counterpart to approvals_list. The only explicit guidance is about visibility scoping, not about when to choose this tool over approvals_list or audit_list.

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

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

With no annotations, the description carries the full burden and does well: it discloses sort order (newest first), expiry normalization (requests past expiry read as expired), and — most valuably — a visibility model (owner/office see all; field workers see only their own or their agents' requests). It stops short of describing pagination or result shape, which is the main remaining gap.

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

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

Three tight sentences, front-loaded with purpose, then the optional filter, then behavior. Every sentence contributes new information with no waste.

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 and no annotations, the description covers purpose, filtering, ordering, expiry handling, and access scoping well. The absence of any pagination/result-size guidance is the only notable omission.

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 0%, so the description must compensate. It maps shop_id to 'for a shop' and status to 'optionally by status' with the enum values, adding the important 'optional' nuance — but the enum values merely repeat the schema and shop_id's scope isn't elaborated. It adds only modest meaning beyond structured fields.

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

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

States a specific verb+resource: lists approval requests for a shop, newest first. Clear what the tool returns and its default ordering. It does not explicitly differentiate from the close sibling approvals_get, but 'list ... newest first' makes the plural/collection nature evident.

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 — you list approvals for a shop, optionally filtered by status — but there is no explicit statement of when to use this versus approvals_get or when a filtered vs. full list is appropriate. No exclusions or prerequisites 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?

No annotations are provided, so the description carries the full behavioral burden, yet it never states that this is a read-only query, whether results are paginated, whether it returns all rules or only enabled ones, or what permission level the caller needs. The only value added is the semantic gloss on what an approval rule is.

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 short, front-loaded sentence with no waste. It is a noun fragment rather than a complete statement of behavior, which is the only structural weakness.

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 list tool with no output schema, the description covers the 'what' reasonably well, but with no annotations and no parameter documentation the agent still cannot tell read-vs-write, result shape, or scope rules.

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 0% for the single required shop_id parameter, so the description must compensate and does not. The possessive 'shop's' weakly implies shop scoping but never names or explains shop_id, its UUID format, or whether it must be the caller's own shop.

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?

It clearly identifies the resource (the shop's approval rules) and explains what those rules mean — 'which agent actions wait for the owner' — which is genuinely informative. However, there is no verb, so it never states whether it lists, gets, or summarizes rules, and it does not differentiate itself from the sibling tools approvals_list and approvals_get.

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 never names an alternative such as approvals_list or approvals_get. The agent must infer usage entirely from the tool 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?

With no annotations, the description does real work by disclosing that this is a read, that results are ordered newest first, and that it requires owner-level permission. It does not cover pagination behavior, what fields an audit entry contains, or retention limits — meaningful gaps for a log-retrieval tool whose output shape is undocumented.

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 short sentence with zero waste, front-loading the resource and tucking the two key constraints (ordering, permission) into a compact parenthetical. Nothing is padded.

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

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

For a three-parameter tool with no annotations, no output schema, and no parameter documentation, a single sentence is thin. An agent still doesn't know how cursor paging works, whether limit is capped, or what a response looks like.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it covers only shop_id implicitly via "a shop's audit log." The limit and before_id parameters — the latter clearly a cursor for the "newest first" ordering — go entirely unexplained, leaving an agent to guess at paging 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?

The description gives a specific verb and resource ("read a shop's audit log") plus the result ordering ("newest first"), which is enough to distinguish it from the sibling logs_list and logs_add/remove. It stops short of explicitly contrasting itself with those siblings, so it falls just under 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 parenthetical "(owner only)" usefully states an access prerequisite, which is more than most definitions offer. However, it never says when to reach for this versus logs_list or search_global, and gives no guidance on how to page through results.

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

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

With no annotations, the description carries the full burden. It discloses key behavior: requires a browser session, returns a redirect with a one-time code, uses PKCE S256, and binds the token to the MCP endpoint via the resource parameter. It lacks error-case or permission details, but covers the essential operational 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?

Four short sentences, each front-loaded with purpose, return behavior, requirement, and resource binding. No wasted words; the structure is efficient and easy to parse.

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

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

The description covers the tool's core purpose, return format, and auth requirement, which is useful given no output schema. But with 9 parameters and 0% schema coverage, it omits enough parameter detail that an agent must infer several inputs, leaving a completeness gap.

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

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

Schema description coverage is 0% across 9 parameters. The description only explains `resource` (RFC 8707) and implicitly clarifies `code_challenge_method` (S256). It leaves parameters like `client_id`, `redirect_uri`, `state`, `scope`, `shop_id`, and `response_type` undocumented in both schema and description.

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

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

The description states a specific action: 'A signed-in person approves an agent client' and clarifies the output ('Returns the redirect with a one-time code'). It distinguishes itself from a token endpoint by focusing on the authorization step, though it does not name sibling tools like auth_oauthToken or auth_oauthRegister.

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 condition: 'Needs a browser session, not an agent token,' which is a strong usage constraint and exclusion. However, it does not explicitly mention when to use this versus related OAuth siblings (e.g., auth_oauthToken for token exchange).

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?

No annotations exist, so the description carries the full burden. It usefully discloses that only public clients are supported, that no client secret is issued, and the redirect URI validation rules, but it omits whether registration requires authentication, what credentials are returned (client_id/registration access token), and whether registration is open or gated.

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

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

Two short sentences, front-loaded with the core action and followed by the key constraints. No filler or repetition.

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

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

For a 13-parameter creation tool with no annotations, no output schema, and 0% schema description coverage, two sentences are not enough. Critical gaps remain around parameter meanings, required authentication, and the response payload the caller must handle.

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 0% across 13 parameters, so the description must compensate and largely does not. It adds meaning only for redirect_uris (https or loopback) and implicitly for token_endpoint_auth_method/grant_types (public clients, PKCE), leaving the other parameters 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 and resource ('Register an OAuth client') and pins it to RFC 7591 dynamic registration, which clearly separates it from the sibling authorization and token tools. An agent can identify the operation without inspecting the schema.

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

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

The phrase 'Public clients only: PKCE, no secret' is an explicit applicability constraint that tells an agent not to use this for confidential clients, and the redirect rule sets a further precondition. It does not name an alternative tool or state when in the auth flow registration should occur, but the exclusions are clear.

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

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

With no annotations at all, the description carries the full behavioral burden and does so well: refresh tokens rotate and each works only once, reuse revokes the entire token chain, claim-flow polling has explicit terminal and retry states, shown_once appears only on success, and the claim success path returns a named agent key that never expires until revoked. These are exactly the non-obvious, safety-relevant traits an agent cannot infer from the 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 information-dense and front-loads the core exchange operation before the flow-specific rules. Nearly every clause carries operational meaning, though the single run-on paragraph mixes three distinct flows and the parenthetical '(auth.md)' reference adds noise without telling the agent where to look.

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 nine-parameter, security-sensitive, no-annotations, no-output-schema tool, the description covers the hard parts: flow selection, retry/terminal conditions, rotation, and success semantics. It stops short of the complete picture because scope/resource usage is undocumented and the error surface for the authorization_code and refresh_token paths (beyond chain revocation) is not described.

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 0%, so the description has to explain parameters, and it largely does: it binds code and code_verifier to the authorization_code path, refresh_token to the refresh path, and claim_token plus the urn:workos:agent-auth:grant-type:claim enum value to the claim path. Two of the nine parameters, scope and resource, are never mentioned anywhere, leaving the agent guessing when they are needed.

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 operation and resource: exchanging an authorization code plus PKCE verifier, a refresh token, or a claim token for agent access tokens. It also enumerates the three grant_type values inline, so an agent knows exactly which flows the tool serves. It falls short of 5 because it never distinguishes itself from neighbors like auth_oauthAuthorize, auth_oauthRegister, or agents_claim, which appear to sit on adjacent edges of the same OAuth/agent-auth flow.

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 guidance is strong for the claim flow: poll every interval only while the error is authorization_pending, wait longer on slow_down, and stop on access_denied, expired_token, invalid_grant, or once expires_in has elapsed. It also implicitly tells the agent when to use the refresh_token path via the rotation rule. What is missing is any routing language telling the agent when to pick this tool instead of siblings (auth_oauthAuthorize, agents_claim, agents_register).

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely valuable trait: the call always returns ok and deliberately does not reveal whether the email has an account. It leaves out other mutation-relevant behavior such as rate limiting, link expiry, and what side effect the email send has, so the disclosure is partial.

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

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

Two tight sentences with no waste; the action comes first and the non-obvious response behavior follows immediately. Nothing could be cut 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?

There is no output schema and no annotations, so the description must cover purpose, safety, and parameters. It handles purpose and response behavior well but omits the 'next' parameter entirely and says nothing about abuse controls or link lifetime, which matter for a public-facing auth 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 0%, so the description must compensate, and it does not. The required email parameter is only obliquely implied, and the optional 'next' parameter is never mentioned — an agent has no idea it is a post-sign-in redirect target.

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 plus resource: email a one-time sign-in link. That is concrete and actionable, but it never distinguishes itself from the sibling auth_sendLink, which sounds like the same operation, so an agent cannot choose between them from this text alone.

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

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

The sign-in context is implied by 'one-time sign-in link', but there is no explicit when-to-use statement and no mention of auth_sendLink or auth_oauthAuthorize as alternatives. The safety note about always answering ok is helpful, but it is behavioral, not routing 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?

With no annotations, the description carries the full burden and does so well: the link works once, in any browser, expires in 15 minutes, and the tool always answers ok so it never reveals whether an email has an account. It also notes the destination page still checks permissions.

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 purpose is front-loaded and every sentence carries routing, behavior, or parameter information. It is dense and slightly run-on, and the full screen list partly repeats the schema enum, which keeps it from being a clean 5.

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

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

The tool has a nested params object and an output schema, and the description covers behavior, expiry, account privacy, screen-specific parameter requirements, and the sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 33%, but the description compensates by mapping screens to the params they read: shop_id for shop screens, job_id for capture and subcontractors, shop_id plus optional date for board, kind and id for override, and keys for card and hub. This adds substantial meaning beyond the generic params object schema.

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

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

States a specific verb and resource: email a one-time sign-in link that opens a named Doing Work screen for a human. It also explicitly distinguishes itself from members.sendPage and explains that the claim screen is refused because the agent connect flow sends its own link.

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

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

Explicitly says when to use it (to hand the agent's person straight to a page needing a human) and names the alternative for shop-member pages with role checks: members.sendPage. It also excludes the claim screen and explains why.

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?

No annotations exist, so the description carries the full burden and it discloses almost nothing: no permissions/role requirements, no collision handling with existing visits or open slots, no duplicate/idempotency behavior, no indication of what is returned. For a mutation on scheduling data, these omissions matter.

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 short sentence, front-loaded with the verb and resource, with no filler. Its brevity is appropriate in structure even though the content is thin.

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

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

Given a 5-parameter mutation with zero schema documentation, no annotations, and no output schema, the description leaves an agent without enough to call it correctly or predict side effects. Substantially more disclosure is warranted 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 0% across 5 parameters, so the description must compensate and does not. "Worker" loosely maps to person_id, and the examples loosely map to reason, but shop_id scoping, the starts_at/ends_at date-time format expectations, and the fact that person_id is optional (only 3 of 5 required) are never explained.

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

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

Specific verb+resource ("Add time off for a worker") with parenthetical examples of the kinds of time off. It is clearly distinguishable from availability_removeTimeOff and availability_setHours by name and description, though the description itself never names those alternatives.

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

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

No guidance on when to use this versus availability_setHours or availability_removeTimeOff, no preconditions (e.g. must the person be a member of shop_id?), and no stated exclusions. Only the parenthetical examples hint at appropriate use.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the maximum window and default person behavior, but does not mention permissions, pagination, error behavior, or the exact 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?

The description is a single efficient sentence that front-loads the returned data, then adds the key window constraint and default behavior. Every phrase adds useful information.

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

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

For a four-parameter read tool with no annotations and no output schema, the description is only partially complete. It covers the return categories and window limit, but omits shop_id semantics and response format details.

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 0%, so the description must compensate. It explains the person_id default and the from/to window constraint, but it never explains the required shop_id parameter.

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

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

The description clearly states the resource and returned data: a worker's weekly hours, time off, and booked visits within a date window. It is specific enough to distinguish this as an availability-read tool, but it does not explicitly contrast with siblings like availability_setHours or availability_addTimeOff.

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

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

It gives useful context with the 62-day window limit and the 'defaults to me' behavior, implying this is for retrieving availability. However, it does not state when to use this versus related tools such as schedule_events or availability_setHours.

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

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

With no annotations, the description carries full behavioral burden, and it discloses almost nothing. 'Remove' implies a destructive mutation, but it doesn't say whether the deletion is permanent or reversible, whether it requires permissions, or what happens if the entry is already applied to scheduled visits.

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 one-sentence description is front-loaded and free of waste, but that brevity is under-specification rather than true conciseness. It is appropriately sized only in the sense that nothing useful was said.

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

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

For a destructive single-parameter mutation with no annotations and no output schema, the description should cover irreversibility, side effects on existing schedule, and error behavior. All of that is absent, leaving an agent unable to call this safely with confidence.

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

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

The single parameter has 0% schema description coverage, and the description never mentions time_off_id, its UUID format, or where to source it. The only inference is that the id identifies a time-off entry, which adds essentially nothing 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 plus resource ("Remove a time-off entry"), so an agent can tell it deletes availability time-off rather than adding or setting it. However, it offers no scope or sibling differentiation beyond what the name 'availability_removeTimeOff' already conveys.

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 alternatives such as availability_setHours or availability_addTimeOff, and no prerequisites. The sentence gives no exclusions, no context about whether the entry must be pending vs approved, and no hint about how the identifier is obtained.

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

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

With no annotations, the description carries the full burden and does disclose the most important trait — a destructive overwrite ('replacing what was there'). It also documents the empty-list edge case. It omits permission/authorization requirements and whether omitted person_id defaults to the caller.

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

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

Three short sentences, front-loaded with the action and overwrite warning, followed by format and edge-case detail. 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 3-param tool with no annotations and no output schema, the description covers the destructive semantics, value formats, and empty-list behavior. Remaining gaps are person_id handling and validation limits (maxItems 28), which are minor but real.

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 0%, so the description must compensate; it explains the nested hours array semantics (weekday 0=Sunday..6, HH:MM in shop-local time) and the empty-list meaning, which the schema cannot convey. However, the optional person_id parameter is never mentioned, leaving the agent unsure whose hours are set when it is omitted.

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: 'Set a worker's weekly hours', which distinguishes it from the shop-level sibling schedule_setShopHours and from the additive availability_addTimeOff/removeTimeOff. The replace-vs-add semantics are 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?

Clear context is given: this replaces existing hours, and an empty list clears them to always-available. That tells the agent when to use it for wholesale rewrites, but it never names an alternative for partial edits (e.g., addTimeOff) or states when not to call it.

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

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

With no annotations, the description carries the full load and does it well: it discloses determinism (same period yields the same file and sha256), a 60-minute / 5-download link with a warning that anyone holding it can download, and the 5 MB ceiling when delivery is inline. These are exactly the operational and security traits an agent needs before calling.

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

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

The core purpose is front-loaded in the first clause and every sentence carries information. The colon-chained construction ('a ledger CSV of every invoice, void, payment...') makes it dense to parse, but nothing is truly 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 six-parameter export tool with an output schema, this covers everything an agent needs: period selection, output contents, size limits, link expiry and sharing risk, determinism, and the preferred alternative path. Return value details are additionally spelled out even though the output schema already 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 only 33%, but the description adds real meaning for the ambiguous parameters: month versus from/to, and the link-vs-inline delivery tradeoff including the inline size cap. include_imported is not addressed in the description, although the schema itself documents it as history-only payments defaulting to false.

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 verb and resource: it exports one month (or a from/to range) of the shop's money as a ZIP containing a ledger CSV, QuickBooks Online invoice import files and bank upload files. It explicitly contrasts itself with the sync path (sync.changes). The one gap is that it never distinguishes itself from the near-identically named sibling books_exports, which an agent could easily pick by mistake.

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

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

Gives an explicit when-not rule: 'Use this only when the shop has no agent QuickBooks sync; the sync (sync.changes) is the main way.' The alternative and the condition that selects it are both named, so the routing decision needs no 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?

With no annotations, the description carries the burden and does well: it discloses ordering (newest first), the fields returned, the authorization scope (owner or office), and the important limitation that no download link is produced here. Pagination/default behavior of the result set is the main unstated trait.

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 clauses, front-loaded with the access scope and resource, with zero filler. The colon-chained telegraphic style is efficient but slightly harder to parse than plain 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?

An output schema exists, so return shape needn't be spelled out, and the description still names key fields. For a two-parameter read tool, the only meaningful gap is how limit affects the result set.

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

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

Schema description coverage is 0%, so the description must compensate. shop_id is self-evident from the phrase 'the shop's', and 'newest first' hints at ordering, but the limit parameter's meaning, default, and paging behavior are explained nowhere.

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 specific resource (the shop's past books exports) and the returned fields (period, row counts, sha256), and implicitly contrasts with books_export for downloads. The listing verb is only implied, but the resource and scope are unambiguous and separable from the sibling.

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

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

Gives a concrete use case (verify a file you were sent via sha256) and explicitly routes to books.export when a fresh download link is needed, plus an access condition ('Owner or office'). It doesn't state exclusions beyond that, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden but does disclose meaningful behavior: a 200-record cap, that each item is evaluated against the shop's approval rules just like a single call, and that results can be done, approval_required or failed, implying per-item partial outcomes. It omits atomicity guarantees, error/retry semantics, and permission requirements, 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 sentences, zero filler, with the scope constraint and action list front-loaded before the outcome semantics. 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 five-parameter mutation tool with no annotations and no output schema, the description covers action scope and the per-item result model adequately, but leaves the parameter contract (tags/person_ids conditionality, max tags, uuid formats) undocumented. An agent could still call it, but would be guessing on key inputs.

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 0% across five parameters, so the description should explain them, but it only restates the action enum already present in the schema. It never explains what shop_id, ids, tags, or person_ids mean, nor that tags are required for addTags/removeTags actions or that person_ids apply to visits.assign.

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

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

The description opens with a specific verb and resource ('Run one safe action on up to 200 records') and then enumerates every permitted action value, so an agent knows exactly what this tool does. The batching scope distinguishes it from single-record siblings like customers_archive or visits_assign.

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

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

The description implies usage (batch a single action across many records) and notes that items follow shop approval rules, but it never states when to prefer this over looping single-call tools, nor when not to use it. There are no named 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?

With no annotations, the description carries the full behavioral burden and discloses several important traits: the feed is read-only, the link is shown only once, and creating a new feed disables that person's old one. It does not cover edge cases such as feed expiration or whether revocation is immediate.

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 three short sentences, front-loaded with the core action and then immediately covering the important parameter default and side effects. Every sentence adds useful information with no redundancy.

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

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

Given a simple two-parameter tool with an output schema, the description covers the key behavioral context and person_id usage well. The main remaining gap is that the required shop_id parameter is not mentioned in the description, though the schema marks it as 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?

The description fully explains the optional person_id parameter, including its default and permission implications. However, with 0% schema description coverage, the required shop_id parameter is not described at all, leaving half the parameters without added semantic 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 states a specific verb and resource: making a calendar feed link (.ics) of one worker's visits. It also clearly distinguishes this create operation from the sibling list and revoke operations by describing the subscription artifact being created.

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

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

It gives clear context for person_id: omit it for your own feed, or use it for another current member if you are an owner or office. It does not explicitly name calendar_listFeeds or calendar_revokeFeed as alternatives or state when not to use this 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?

With no annotations, the description carries the full burden. It does add real value beyond the name: result ordering, the fields returned, per-role visibility scoping ('field workers see only their own'), and that the feed link is intentionally withheld on subsequent reads. However, it says nothing about pagination or limits on a list operation, which matters for an unbounded feed list.

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

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

Three short sentences, no filler, with the scope and ordering front-loaded. The closing sentence 'The link is not shown again' is slightly cryptic in isolation but earns its place by flagging a security-relevant return behavior.

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

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

An output schema exists, so return-value shape is covered, and the description adds useful scoping and visibility context. Gaps remain around pagination and the role of person_id, which for a two-parameter list tool with zero annotation coverage is a meaningful omission.

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 0%, so the description must compensate. It never mentions shop_id or person_id. The field-worker scoping sentence gestures at the person_id filter but never explains whether person_id is an admin-only filter or a required pairing with shop_id, leaving the second parameter entirely opaque.

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 resource and scope: calendar feeds within a shop, with ordering (newest first) and returned attributes (active status, fetch frequency). This clearly distinguishes it from siblings like calendar_createFeed and calendar_revokeFeed. It stops short of stating the verb outright ('List'), but the intent is unambiguous.

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

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

No explicit when-to-use or when-not-to-use guidance, and no named alternatives. The reader must infer that this is the read counterpart to createFeed/revokeFeed. The only contextual hint is the visibility rule for field workers.

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

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

With no annotations, the description carries the safety burden and usefully discloses that future feed requests return 410 and stop showing new visits. However, it does not state whether revocation is permanent, whether the feed can be re-enabled, or what permissions are required.

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

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

Two short sentences, front-loaded with the action and followed by the key behavioral consequence. No sentence 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?

An output schema exists, so return values need not be explained. For a one-parameter revocation tool, the description covers the core action and effect, though it could say more about reversibility and permissions.

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 0% and the description does not explain feed_id beyond its name. The single required UUID is obvious from the schema, but the description adds no semantic detail to compensate for the missing schema description.

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

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

States a specific verb and resource: turn a calendar feed off. The description clearly distinguishes this from calendar_createFeed and calendar_listFeeds by naming the exact operation and object.

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?

Implies the tool is used when a feed should stop serving new visits, and notes that future fetches receive 410. It does not explicitly compare alternatives or state when not to revoke, so usage 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?

No annotations are provided, so the description carries the burden. It usefully discloses the returned data shape (brand/last4/expiry + auto-pay status), which signals a read-only lookup. However it says nothing about behavior when no card exists, error conditions, or that this exposes sensitive payment data, leaving real gaps for an unannotated 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 compact sentence with the key information front-loaded and no wasted filler. It is appropriately sized for a simple lookup, though the lack of a leading verb slightly weakens the front-loading.

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 no annotations, the description does the right thing by enumerating return fields. But it omits the one input (customer_id) and the no-card/error case, so an agent still guesses at edge behavior for this one-param 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 0%, and the description never mentions customer_id, so it adds no meaning over the schema. The single param is a self-explanatory UUID, so the gap is minor, but the description does nothing to compensate.

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 (the customer's card on file) and enumerates its fields (brand, last 4, expiry, auto-pay owner/office), so an agent can tell what this returns. It is a noun phrase rather than a verb like 'Fetch', but the combination of name and field list makes the operation unambiguous and distinct from siblings cards_remove and cards_setupLink.

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

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

No when-to-use or when-not-to-use guidance. It mentions auto-pay but doesn't route the agent to customers_setAutopay for changing that state, nor explain what to do if a card isn't found. The agent is left to infer usage 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that auto-pay turns off as a side effect, but does not state whether removal is irreversible, what permissions are required, or what happens if the customer has multiple saved cards.

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 a single front-loaded sentence with no wasted words. The key action and side effect are both stated immediately.

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

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

For a destructive operation with no annotations and no output schema, the description is too thin. It omits irreversibility, permissions, and the critical ambiguity of whether customer_id removes a specific card or all saved cards.

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 0% and the single parameter is undocumented. The description implies a customer context but does not explain customer_id, its UUID format, or whether it removes one card or all saved cards for that customer.

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: remove a customer's saved card. It is clear enough to distinguish from cards_get and cards_setupLink, though it does not explicitly name sibling alternatives.

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

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

It implies the tool is used to remove a saved card, but gives no explicit when-to-use guidance, no when-not-to-use conditions, and no alternatives such as cards_get or customers_setAutopay.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully discloses that Doing Work never sees the card number and that saving a new card replaces the old one, but it omits link expiration, single-use behavior, required permissions beyond "owner or office," and what the tool actually returns.

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

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

Three short sentences, front-loaded with the core action and followed by the most important behavioral caveat (security) and replacement rule. No wasted 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 no-annotation, no-output-schema tool with one parameter, the description covers the conceptual purpose and key security guarantees. It still leaves gaps around permissions, link lifecycle, and return value, which matters because no structured fields fill those gaps.

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

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

Schema coverage is 0% and the only parameter, customer_id, is not explicitly mentioned in the description. The phrase "the customer" hints that the link is scoped to a customer, but it does not explain the parameter's role, required status, or UUID format.

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 action: generating a secure page/link for a customer to save a card. It implicitly distinguishes this from cards_get and cards_remove by focusing on card collection rather than retrieval or removal, though it never names those 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?

It gives one clear usage instruction ("Send the link to the customer"), which implies when to use it. However, it does not state when to use this instead of cards_get, cards_remove, or other link-generating tools, nor does it describe 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?

With no annotations, the description carries the burden and does well: it discloses the cascading side effect (open signature request cancelled, link stops working) and the state constraint blocking approved orders. It omits permission/auth requirements and whether cancellation is reversible, keeping it short of a 5.

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

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

Two sentences, both load-bearing: the first covers the action and its side effect, the second covers the restriction and the remedy. No filler and the key 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 mutation tool with no annotations, the description covers side effects, eligibility, and the alternative path, and an output schema exists so return values need not be explained. The remaining gap is the undocumented 'reason' parameter.

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 0% across two parameters, so the description must compensate and it does not. The 'reason' parameter is never mentioned, and change_order_id is only implied by the tool's purpose rather than explained (e.g., what states/IDs are acceptable).

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 (cancel) and resource (change order) plus the scope of eligible states (draft or sent). It is clearly distinguished from siblings like changes_create, changes_send, and signatures_cancel by naming the downstream signature-request effect.

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 states the when (draft or sent change orders), the when-not (approved change orders cannot be cancelled), and the alternative procedure (write a new change order that takes the work back out). This is exactly the routing guidance an agent 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?

No annotations exist, so the description carries the load, and it discloses several behaviors: the record starts as a draft (not sent), tax defaults to shop rate unless overridden, and the total can be negative (a credit). It doesn't mention permissions/auth or cancellation, but core mutation behavior is well 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?

Front-loaded with the core action and definition, then adds the essential behavioral notes in dense but purposeful clauses. No wasted 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?

For a mutation tool with no annotations, an output schema present, and 5 params, the description covers the key behavioral facts (draft status, tax defaulting, credit possibility) plus the follow-up tool. Permissions and edit/cancel mechanics are not covered but are secondary.

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 20%, so the description must compensate and does: it explains discount lines ('take work out'), credit totals, and tax semantics ('shop default rate unless tax_rate_id is given; null for no tax'). It says less about title/description/job_id, which are largely self-evident.

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 (write) and resource (change order on a job), and defines what a change order is ('a priced change to its scope'). It also distinguishes itself from the sibling changes_send by noting it 'starts as a draft' and is sent later via changes.send.

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?

Clear workflow context: use this to create a draft, then call changes.send to send it to the customer. It doesn't explicitly enumerate when NOT to use it, but the alternative action and staging behavior make the intended usage 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?

With no annotations, the description must carry the full behavioral burden. It usefully discloses that the record includes lines, totals, status, signature and invoice, and 'One change order' implies a read operation, but it does not explicitly confirm read-only behavior, permission requirements, or not-found handling.

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

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

It is a single compact sentence with no filler, and the returned components are front-loaded. The fragment style without a verb is slightly less scannable but still efficient.

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

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

For a simple single-record read with an output schema, the description is adequate on the return side. It is incomplete regarding the only parameter and lacks explicit confirmation of read-only behavior, but the tool's simplicity limits the severity of those gaps.

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

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

Schema description coverage is 0% for the sole required parameter, change_order_id. The description never mentions the parameter, its UUID format, or what identifier is expected, so it does not compensate for the schema 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?

The description identifies a single change order and enumerates what it contains (lines, totals, status, signature, invoice), which distinguishes it from the bulk-oriented changes_list. However, it uses a noun phrase without an explicit retrieval verb, so the purpose is clear but slightly less crisp than it could be.

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 phrasing ('One change order') implicitly signals use when fetching a specific record by ID, but the description never mentions the sibling changes_list or states when not to use this tool. Guidance is only inferable, not explicit.

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

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

With no annotations, the description carries the full burden and discloses key behavior: it creates a draft invoice, copies change order lines labelled by number, treats negative change orders as discounts, and requires priced work on the same invoice. It doesn't cover permissions or idempotency, but the main mutation semantics are explained.

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 dense but front-loaded, starting with the core action before constraints. Every sentence contributes useful information, though the phrasing is compact enough that some readers may need to reread the credit/discount 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?

An output schema exists, so return values need not be described. For a mutation tool with no annotations, the description covers draft status, line copying, default selection behavior, and discount handling, though it omits guidance on memo, due_on, and permission requirements.

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

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

Schema description coverage is 0%, so the description needs to compensate for all parameter meaning. It explains change_order_ids well, including the omit behavior and tax-rate constraint, but job_id is only implied, and memo and due_on receive no explanation at all.

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

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

The description uses a specific verb and resource: 'Bill approved change orders on a normal invoice'. It also clarifies the output is a draft and that sending is handled by a different tool, so an agent can distinguish it from sibling tools like invoices_create or changes_send.

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

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

It gives clear usage conditions: omit change_order_ids to bill every approved uninvoiced change order on the job, and all included orders must share one tax rate. It doesn't explicitly name alternatives beyond invoices.send for sending, but the context needed to choose this tool is largely present.

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?

No annotations are provided, so the description carries the burden. It does valuable work explaining that the money picture is derived (signed quotes = contract_minor, plus approved change orders = revised_total_minor), which is genuinely behavioral information. However it omits whether the call is read-only (only implied by 'list'), the permissions needed, and pagination/limits.

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 sentence, front-loaded with the resource, but the semicolon chain of status categories ('pending ...; invoiced ...; unbilled; ...') is dense and hard to parse on a single read. It's compact but not well structured.

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?

An output schema exists, so the entire description is spent explaining return values that the output schema already defines, while omitting usage guidance and any behavioral caveats. For a financial-summary tool with no annotations, it leaves real gaps.

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

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

Schema coverage is 0% for the single job_id parameter, but the description's 'A job's ...' framing makes the scoping clear enough. It adds no format or validation detail (uuid is only in the schema), so it's adequate rather than compensatory.

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?

It names the resource (a job's change orders) and describes the financial figures it returns, but never states the verb or that it's a list operation, and it doesn't distinguish itself from changes_get, changes_invoice, or changes_send. An agent can infer the domain but not the exact operation.

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 prerequisites (e.g. must you be job owner?), and no reference to any sibling such as changes_get for a single change order. The agent must guess.

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

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

With no annotations, the description carries the burden and does well: it discloses the write side effect (document with lines/totals and before/after job total), the single-use sign_url return, and the hosted-page signing that flips the order to approved. It stops short of failure modes — e.g. what happens when the order is already approved or the caller lacks the role.

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?

Dense and front-loaded: the action and its effect come first, the re-send and alternative-link rules come last. Each clause carries distinct information — 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?

An output schema exists, yet the description still usefully explains the returned sign_url and its single-use nature, plus the approval lifecycle. Only the error/permission edge cases are left implicit, a minor gap 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 coverage is 67%, with link_days and signer_email already documented in the schema. The description adds nothing about these parameters (link lifetime, signer binding) and change_order_id is undocumented, but that parameter is self-evident from context. 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 — asking the customer to approve a change order — and describes the concrete outcome (document written, sign_url returned, order becomes approved). It also distinguishes itself explicitly from signatures.newLink, so an agent can route between them without opening either schema.

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

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

Explicit when-to-use guidance: call again after a cancellation, and use signatures.newLink for a fresh link on an open request. It also names the caller role (owner or office), which removes ambiguity about who may invoke it.

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?

No annotations are provided, so the description carries the full burden. It discloses append-at-end behavior and alludes to locking via "same locks as ticking," but that reference is opaque—it never says what the locks are, what permission or concurrency constraints apply, whether duplicates are allowed, or what happens on failure.

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

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

Two tight sentences with the core action and scope front-loaded. Nothing is wasted, though "same locks as ticking" is a cryptic aside that spends words without clarifying.

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?

An output schema exists, so return values need not be described. However, for a mutation tool with no annotations, the description omits permission model, lock semantics, item limits, and failure behavior—gaps an agent needs to call it safely.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. It does not explain the items array shape (label/required), the 1–200 item limits, or what checklist_id must reference, leaving the agent to infer everything from the raw schema.

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

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

States a specific verb and resource (add items) plus an ordering detail (to the end) and scope (owner or office checklists). It distinguishes itself from sibling checklists tools like checkItem and create, though it does not explicitly name which sibling to use instead.

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?

"(owner or office)" hints at which checklist kinds this applies to, and "Same locks as ticking" points at checklists_checkItem as a related operation. There is no explicit when-to-use/when-not or prerequisites, so the 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?

With no annotations, the description carries the burden and does add real value by disclosing the key side effect: existing checklists created from the template are unchanged. It does not say whether archiving is reversible, whether permission/ownership is required, or what happens to in-flight sign-offs.

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 primary effect stated first and the non-obvious guarantee second. Nothing to trim.

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?

An output schema exists so return values needn't be explained, and for a single-param tool the description is close to sufficient. Still missing any note on reversibility/restore path and how this relates to the sibling template tools, which an agent needs before mutating state.

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 0%, but there is only one parameter and its name (checklist_template_id, uuid) is self-explanatory. The description adds no format or sourcing guidance (e.g. where to obtain the id from checklists_listTemplates), so it neither compensates nor harms.

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 ('Archive a checklist template') plus the effect ('no longer offered'). It does not name a sibling such as checklists_saveTemplate or forms_archiveTemplate, but the action is unambiguous on its own.

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?

Implies the condition for use (when a template should stop being offered) but never states alternatives or exclusions — e.g. whether to archive vs. delete, or how this differs from forms_archiveTemplate. The agent must infer routing from sibling names alone.

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

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

With no annotations, the description carries the burden well: it discloses authorization rules, the scope widening for job checklists (any visit of the job), and the lock conditions that cause rejection. It stops short of saying what a locked-item call returns or how errors surface, which the output schema may partly cover.

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

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

Three short sentences, front-loaded with the action and the boolean convention, followed by permissions and then constraints. Every sentence adds distinct information with no repetition.

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

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

An output schema exists so return values needn't be explained, and the description supplies the permission model and lock states that annotations would otherwise carry. Only the failure behavior when an item is locked is left implicit.

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 must compensate; it does explain done (true = tick, presumably false = untick) and mentions the optional note. However checklist_item_id is never elaborated and no format/behavior for the note beyond 'optional' is given, leaving gaps against the low coverage 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 pair (tick/untick) with the exact boolean convention (done true) and the target resource (an item), plus an optional note. This clearly separates it from sibling tools such as checklists_addItems and checklists_requestSignOff without 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 the actors who may call it (the worker on the visit, or the office for a job checklist) and the exact states in which it must not be used (visit/job done, sign-off waiting, after sign-off). It does not name sibling alternatives, but the when-not conditions are unusually explicit.

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

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

With no annotations, the description carries the burden well by disclosing the gating semantics: a visit checklist blocks that visit's done, a job checklist blocks jobs.complete, and the job also waits on checklists of not-yet-done visits. That is non-obvious production behavior an agent could not infer from the schema. Missing: whether a duplicate checklist on the same job/visit errors, and any permission requirements.

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

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

Three short sentences, each carrying distinct information, with the core action front-loaded and consequences following. No filler or repetition of schema facts.

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

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

An output schema exists so return values need no explanation, and the description completes the picture with the done-gating behavior. The remaining gap is edge-case behavior on duplicate or conflicting checklists, which is minor for a create tool at 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 17% (only items.required and signoff_required are documented), so the description must compensate. It explains visit_id and checklist_template_id as a mutually exclusive choice and clarifies items as the alternative source, covering the parameters that matter most; it adds little for name, which is self-evident.

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 a specific verb+resource ('Put a checklist on a job, or on one visit') and immediately distinguishes the two attachment scopes. It does not name sibling tools (checklists_saveTemplate, checklists_addItems) explicitly, but the creation/attachment framing is distinct enough that an agent can tell it from template or item-management 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?

Gives clear selection logic for the tool's own modes: attach to job vs. one visit via visit_id, and populate via template (checklist_template_id) or inline items. It also states the downstream consequence of each choice (visit gate vs. jobs.complete gate), which guides the decision. No explicit alternatives or exclusions against sibling tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that removed items are included and marked, and that tick timestamps and sign-off are returned, but it omits read-only status, permissions, and not-found/error 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?

The description is a single front-loaded sentence with no filler. Every clause adds useful scope or behavior detail: items, removed-item marking, tick history, and sign-off.

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?

An output schema exists, so the return shape need not be fully restated, and the description does convey the key contents. However, for an unannotated tool with 0% parameter description coverage, it leaves gaps around the identifier's meaning and operational expectations.

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 0% for the single required checklist_id parameter, and the description never mentions the identifier or its expected UUID format. The schema supplies the name and type, but the description does not compensate for the missing parameter documentation.

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: one checklist including every item, removed items marked, tick history, and sign-off. The singular 'One checklist' implicitly distinguishes it from checklists_list, though it does not name any sibling or use an explicit retrieval verb.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as checklists_list or checklists_requestSignOff. The agent must infer that this is the detail-view tool from the phrase 'One checklist'.

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

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

With no annotations, the description carries the full burden: it discloses the access scoping rule ('workers see the checklists of the jobs they can see') and the summary payload (counts of open required items, sign-off state), which is real behavioral value. It omits whether a missing identifier means 'all visible jobs' or an error, and says nothing about result volume 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 sentences, front-loaded with the scope decision, then the access rule. 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?

An output schema exists, so return-shape detail is not required and the description's mention of counts/sign-off state is supplementary. But for a two-optional-parameter list endpoint with no annotations, the missing behavior for the empty-parameter case leaves a real gap in what an agent needs 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 0%, so the description must compensate. It does explain that a job returns both job-level and per-visit checklists while a visit narrows to that visit, which is genuine semantic content the schema lacks. However it never clarifies that both parameters are optional, nor what each does when the other is present.

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 (checklists) and an explicit scope split: job-level plus per-visit checklists for a job, or a single visit. It clearly differs from checklists_get (one checklist) and checklists_listTemplates without naming them, so an agent can route here confidently.

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 implies the two calling modes ('checklists on a job' vs 'on one visit') but never states that both parameters are optional, nor what happens when neither is supplied. No explicit alternatives or exclusions are given, so usage must be inferred from the parameter narrative.

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?

No annotations, so the description carries the full load. It usefully discloses two behavioral facts: templates are returned with their items nested, and archived templates are hidden unless opted in. It says nothing about read-only safety, result size, or ordering/pagination for what could be a large template set.

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, no filler, with the archived-filter rule placed where it will be read. The telegraphic phrasing is efficient but slightly clipped, and the primary action is never stated as a verb.

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?

An output schema exists so return format needn't be spelled out, and the tool is simple (2 params). Still, the description omits what 'items' means in practice and gives no hint about ordering or volume, which are the main unknowns for a template-listing call.

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 0%, so the description must compensate. It does explain include_archived meaningfully (default excludes archived, opt-in includes them), but shop_id — the required scope parameter — is never described beyond its obvious name, leaving half the surface documented only by inference.

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 specific resource ('checklist templates') and states that items are included, which separates it from checklists_get and checklists_list (instances). It's a noun phrase rather than a verb, so the 'list' operation is inferred from the name, but the resource and scope are unambiguous.

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

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

The clause 'Archived ones only with include_archived' gives a concrete selection rule for one parameter, but there is no explicit when-to-use vs. siblings such as checklists_get or forms_listTemplates, and no stated prerequisites. Usage is implied rather than guided.

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

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

With no annotations provided, the description carries the full burden and delivers real behavioral facts: removal is non-destructive (item stays in history, marked removed), authorization is role-gated, required items have an extra restriction, and the action is audited. It stops short of stating whether removal can be undone/re-added or what happens if the item is already removed or does not exist.

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

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

Two compact sentences, front-loaded with the action and its non-obvious soft-delete behavior, then the permission and audit facts. 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?

An output schema exists so return values need not be described, and the description covers the destructive-semantics and auth dimensions an agent needs. Remaining gaps are the failure modes (nonexistent/already-removed item) and the id's provenance.

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 0% and the single parameter (checklist_item_id, uuid) is undocumented in both schema and description. The description adds no meaning about how to obtain the item id or whether it is the checklist-item id versus a template item id, though with one obvious required id the gap 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 and resource ("Remove an item from a checklist") plus the key scope detail that removal is soft (history retained). That is clear enough to distinguish it from checklists_checkItem or checklists_archiveTemplate, but it never names those siblings, so differentiation is inferred 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 description gives eligibility rules (owner or office; required items owner-only) which implies when the call will succeed, but it never says when to prefer this over checklists_checkItem (mark done) or archiving the whole checklist. Usage is implied by permission constraints, not by explicit 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?

With no annotations, the description carries the burden and does well: it discloses the locking side effect ('items lock while the sign-off waits'), the unlock path, and who signs by default. It omits whether the signer is notified, what permissions the caller needs, and what state the checklist lands in after signing.

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: action and payoff first, prerequisite second, state/lifecycle caveat last. No filler and nothing that could be cut without losing meaning.

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 mutating, side-effect-heavy tool with no annotations and a 4-param schema, the description covers the essentials, and an output schema exists so return values need not be explained. Gaps are notification behavior and caller permissions.

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 50%, but the description compensates for the undocumented signer_role enum by explaining the default ('the customer by default, or a shop member'). link_days and signer_email are already documented in the schema, and checklist_id is self-evident.

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 ('Ask for a sign-off on a finished checklist') plus the outcome ('get the signing link'), which separates it from the checklist CRUD siblings. It does not explicitly contrast with the nearby forms_requestSignOff or signatures_request tools, so the agent must infer the boundary from the resource name.

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

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

Gives a concrete precondition ('Every required item must be ticked') that tells the agent when the call will succeed, and names the escape hatch ('signatures.cancel unlocks'). It lacks an explicit statement of when to prefer signatures_request or forms_requestSignOff instead, so it stops short of full routing 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?

With no annotations the description carries the full burden, and it discloses two non-obvious traits: item ordering, and that checklists already instantiated from the template keep their own copy (snapshot semantics). It omits whether replace discards the template's prior items wholesale and says nothing about permissions or auth requirements.

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

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

Three tight sentences: the action and its two modes first, then item semantics, then the non-obvious snapshot behavior. No filler, and every sentence contributes information 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?

An output schema exists, so return values need no explanation, and the description covers the mutation's key semantics for a 6-parameter tool. For a no-annotation mutation, it could still say what a replace does to existing template content and whether elevated permissions are needed.

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 17%, so the description has to compensate. It does add meaning for checklist_template_id (activates replace mode), for items ordering, and for the required-item default and its consequence of blocking job/visit completion. But shop_id, name, and description get no treatment beyond their schema types.

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 checklist template, or replace one') and gives the exact condition that selects replace mode ('give checklist_template_id'). The word 'template' plus the explicit upsert mode separates it from checklists_create, checklists_listTemplates, and checklists_archiveTemplate.

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 create-vs-replace branch is explicitly routed by the presence of checklist_template_id, which is the main decision an agent faces here. It does not name alternative tools or state exclusions (e.g., when to use checklists_archiveTemplate instead), 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?

With no annotations, the description carries the burden and does real work: it discloses ordering, that rows contain both change and rejection rationale, and a non-obvious visibility rule (a field worker sees full rows of their own, while recap/quote drafts carry the shop-wide lessons de-identified). It omits pagination/default-limit behavior and what an empty result looks like, so it is strong but not complete.

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: what it returns, when to read it, then the visibility caveat. Front-loaded and free of filler, though the closing sentence is dense enough that its privacy rule takes a second read.

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?

Purpose, usage trigger, and visibility behavior are covered, and the output schema handles return shape. The gap is the input schema: for a 3-parameter tool with zero schema descriptions, the description should define what kind filters and how many rows limit returns.

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 0%, so the description must explain all three parameters and doesn't. It gestures at 'recent' (a limit implication) and mentions the draft types that correspond to the kind enum, but never states that kind filters results or what the enum's 'other'/'task' values mean, and says nothing about limit's range or default.

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 (corrections), the scope (the shop's, to drafts you made), and the ordering (newest first), plus what each row contains ('what was changed or rejected and why'). It reads as a read/list operation and is clearly the counterpart to the sibling corrections_record, though no explicit verb like 'list' or 'returns' is used and the write sibling is never named.

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?

'Read these before you draft a quote, a recap or a reply for this shop, and follow them' is an explicit trigger condition tied to concrete workflows. It stops short of full when-not guidance and never names corrections_record as the alternative for recording corrections, but the intended moment of use 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?

“Save” establishes that this is a persistent write, and the final sentence discloses that corrections are retained for use before future drafts. With no annotations, however, it leaves behavior such as whether records are append-only and whether the source draft itself remains unchanged to inference.

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 sentences cover the operation, exact usage triggers, payload expectations, and downstream purpose. The primary action is front-loaded, and each sentence contributes useful information.

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

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

For a correction-logging tool, the description adequately covers the trigger, content, and purpose, while the output schema removes the need to document return values. Naming the retrieval sibling and clarifying action-specific optional fields would make invocation guidance more 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?

The description adds meaning for `action` through its three triggers, supplies examples for `kind`, and explains the intended `before`, `after`, and `reason` content. Given only 29% schema coverage, it still leaves `subject_id` unexplained and does not clarify how `before` and `after` should be populated for rejections or errors without replacement 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?

The description clearly states the verb and resource: saving corrections to agent-made drafts, with concrete examples such as quote lines, recaps, tasks, and replies. It implies a distinction from retrieval through “You read these,” but does not explicitly differentiate itself from the sibling `corrections_recent`.

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 precise triggers: use it when the worker edits, rejects, or identifies an error in a draft. It also explains when the saved information matters later, but provides no exclusions and does not explicitly route the agent to `corrections_recent` for retrieval.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the permission prerequisite ('needs seeing costs and prices', 'Owner or office') and precisely how the numbers are derived (approved and pending time at each entry's cost rate, materials at cost, Doing Work fees). It stops short of stating that this is a non-mutating read or how it behaves for jobs with incomplete 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?

It is compact and front-loaded: the first phrase names the operation and scope, then the cost components, then the permission note. The middle enumeration is dense and clause-heavy, but every element is substantive rather than 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?

An output schema exists, so return structure needn't be described, and the description covers the computation inputs, the permission gate, and the resulting metrics (profit and margin). For a single-parameter read-style reporting tool this is sufficient 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 coverage is 0% for the single job_id parameter, so the schema contributes nothing and the description must compensate. 'For one job' does imply the id identifies a single job, but it adds no detail on format (UUID), lookup behavior, or what an invalid/foreign job identifier does.

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

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

The description gives a specific verb-plus-resource ('Job costing for one job') and enumerates exactly which financial components are rolled up, so an agent knows this is a per-job cost/profit breakdown rather than a list. It only implicitly differentiates from the sibling costs_jobs via 'for one job' — it never names the plural tool outright.

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

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

Usage is implied by the content (per-job profit and margin reporting) and the closing clause 'Owner or office; needs seeing costs and prices' signals the audience and permission prerequisite. There is no explicit when-to-use vs costs_jobs, no exclusions, and no statement of what happens if the job has no costs.

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

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

With no annotations, the description carries the disclosure burden and does well: it states the date range is inclusive and interpreted in the shop's time zone, documents a 500-job ceiling, and explains that a truncation indicator signals more matches existed. It does not explicitly state that the operation is read-only or describe the shape of the returned 'totals', which keeps it short of a 5.

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

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

Three tight sentences, each doing distinct work: scope and date semantics first, then sort options, then volume limits and truncation. No restatement of the name or filler content.

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

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

For a six-parameter report tool with an output schema present, the description covers what the schema cannot: range interpretation, ordering intent, and result-set limits. The remaining gap is the sibling relationship with costs_job and the ambiguity of whether margin sorts ascending or descending.

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 50%, so the description's contribution matters: it adds the inclusive/time-zone semantics for from/to and the 'lowest first' ordering for the profit sort, plus the practical cap that limit cannot exceed 500. It says nothing about shop_id or about how margin and date sorts order, leaving part of the enum behavior underspecified.

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

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

The description gives a specific verb-and-resource pairing: it produces job costing totals across a date range of jobs, which is clearly a report/list operation rather than a mutation. The plural 'across jobs' implicitly distinguishes it from the singular sibling costs_job, but it never names that sibling, 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?

Usage is implied rather than stated: the range semantics and the 'to find the losers' framing convey a profitability-review use case. However, there is no explicit when-to-use guidance, no prerequisites, and no mention of when the agent should prefer the sibling costs_job for a single job's costing instead.

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

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

With no annotations, the description carries the full burden but does add real context: 'null when off' discloses the return behavior and 'Owner or office' signals the required role. It never explicitly says this is a read-only accessor or what happens on missing/unset configurations, leaving a gap for an unannotated 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?

It is a single compact sentence with no filler, which is good. However, the phrasing is clipped to the point of ambiguity — 'Owner or office' is unexplained and the action verb is absent, so brevity costs clarity rather than earning 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?

An output schema exists, so return shape needn't be re-explained, and the description usefully adds null-when-off semantics plus a permission hint. Still, for an unannotated tool the description should confirm the read-only nature and clarify what 'Owner or office' means before an agent can call it confidently.

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 0% and the single parameter (shop_id, uuid) is never mentioned in the description. The description adds no meaning about whose shop is queried or any scoping nuance beyond the schema's type declaration.

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 ('the shop's profit alert: the margin floor in percent') but never states the action (read/get). The sibling costs_setMarginAlert makes a retrieval interpretation plausible, yet the agent must infer the verb from the name rather than the description.

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 call this versus costs_setMarginAlert or costs_job/costs_jobs. The only hint is the value semantics ('null when off'), which does not route the agent between siblings.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the emitted event name (job.margin_low), that it fires only once per downward crossing, that it re-arms only after margin recovers and drops again, the permission requirement, and the null-disables behavior. These are non-obvious semantics an agent could not infer from the schema.

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

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

Three tight sentences, front-loaded with the action and permission scope, then the event contract, then the disable path. Every clause adds information that is not available elsewhere.

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?

Output schema exists, so return values need no explanation, and the description covers permissions, event behavior, re-arm logic, and disabling. Remaining gap is scope: it doesn't say whether the alert is per-shop globally or evaluated per job, which matters given a required shop_id.

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

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

Schema coverage is 0%, so the description must compensate. It explains below_percent fully — threshold semantics plus null to turn the alert off — but never mentions shop_id, leaving it to the self-evident name and uuid format. The 0–100 bounds in the schema are undocumented in prose.

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 a specific verb+resource: 'Set a profit alert'. It goes further than the name by defining the alert as a margin-threshold trigger on invoiced jobs, so an agent knows exactly what this configures and how it differs from the read-side sibling costs_marginAlert.

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?

States the precondition '(owner only)', the follow-up action needed to consume the alert ('subscribe with a webhook'), and how to disable it ('null turns it off'). There is no explicit contrast with the costs_marginAlert sibling, but the use conditions are clear enough to act on.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful side effect: already-booked visits keep their assigned workers. It does not say whether archiving is reversible, what permission level is required, what happens to crew members or future scheduling, or whether the crew disappears from crews_list.

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

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

Two tight sentences with the action front-loaded and the side-effect caveat second — nothing wasted. The parenthetical is the only element that costs clarity without earning its space.

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

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

A simple single-parameter mutation with an output schema, so return values need no explanation; the key non-obvious consequence (booked visits retain workers) is covered. Given the tool's low complexity, the definition is adequate 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?

One parameter (crew_id, uuid) at 0% schema coverage. The description implicitly identifies it as the crew being archived but adds nothing about format, sourcing (e.g., from crews_list), or behavior for an invalid or already-archived id.

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 (archive a crew), which cleanly separates it from crews_list and crews_save. The parenthetical '(owner or office)' is ambiguous — it could denote a permission scope, an account-type variant, or something else — leaving a small residue of doubt about exactly what is archived.

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 statement of when an agent should archive a crew versus using crews_save to modify it, and no mention of an unarchive/restore path or prerequisites. The only usage-relevant signal is the implied 'archive rather than delete', which the agent must infer.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses read authorization ('any worker in the shop can read it') and the default behavior of hiding archived crews, but says nothing about ordering, pagination, or result volume. Solid access/filter disclosure, but incomplete 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?

Three tight, front-loaded sentences with no filler. The core resource statement leads, followed by access and filter details. Slightly terse but every sentence earns its place.

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

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

For a 2-param list tool with an output schema (so return shape is covered elsewhere), the description supplies resource scope, read permission, and the archive filter. Adequate to call it correctly; only ordering/pagination context is absent.

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 0%, so the description must compensate. It explains the non-obvious include_archived flag ('Archived crews only with include_archived') well, and shop_id is inferable from 'the shop's crews'. However, it adds no format or scoping detail for shop_id and leaves include_archived's default unstated.

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: the shop's crews and their current workers. It implicitly distinguishes from siblings crews_save and crews_archive by being the read/list operation. It stops short of an explicit 'list' verb, but the resource is unmistakable.

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?

'Any worker in the shop can read it' and 'Archived crews only with include_archived' imply usage context and the default archive exclusion, but there is no explicit statement of when to use this vs crews_save/crews_archive or any prerequisite. 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?

No annotations are provided, so the description carries the full burden. It does disclose the important upsert behavior (crew_id present = rename/replace) and the 'owner or office' scope, but says nothing about whether replacing person_ids destroys existing assignments, permission requirements, or the 20-person cap that the schema enforces.

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, zero waste, with the core action and the update path front-loaded before the downstream usage hint.

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?

An output schema exists, so return values need not be explained. But for a mutation tool with no annotations, the description leaves gaps: the required shop_id is undiscussed, replacement destructiveness is unstated, and the 'owner or office' phrasing is ambiguous about who may call it.

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

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

Schema description coverage is 0%, so the description must compensate. It gives meaning to name, crew_id and person_ids ('workers'), but shop_id — a required parameter — is never mentioned, and no format or constraint details are added beyond what the schema already conveys.

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 ('Save a named crew of workers to book together') and immediately clarifies the create-vs-update semantics via crew_id. An agent can distinguish it from crews_list and crews_archive without opening the schema.

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

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

Explicitly says to pass crew_id to rename or replace workers, and routes the agent downstream ('Use the crew_id on visits.create, visits.assign or schedule.findTime'), which is genuinely useful cross-tool guidance. It does not, however, contrast with crews_archive or state prerequisites for creating a new crew.

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?

No annotations are provided, so the description carries the full burden. It does usefully disclose that archived customers are hidden from lists but their history is retained, which is non-obvious behavioral context. It does not state permissions required, whether the operation is reversible/idempotent, or what happens to related records (jobs, invoices).

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 short sentence, front-loaded with the primary action and using a parenthetical to convey the two key side effects. Nothing is wasted and nothing important 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 2-parameter mutation with no annotations and no output schema, the description covers the state semantics reasonably but leaves the boolean mapping, default behavior, and return/error information unaddressed. An agent could invoke it, but might guess wrong about which value triggers which operation.

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

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

Schema description coverage is 0%, so the description must compensate. The `archived` boolean is never explicitly mapped (true = archive, false = restore) and its default isn't stated; only the vague 'or bring one back' hints at it. `customer_id` is only documented by its uuid format in the schema, with no mention of where to obtain it.

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 (archive) and resource (customer), and adds what archiving actually means: hidden from lists, history kept. It also covers the inverse operation. It doesn't distinguish itself from nearby siblings like customers_update or customers_merge, which an agent might reasonably confuse with archiving a customer.

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 'or bring one back' implies the dual use is driven by the `archived` flag, giving implied usage. But there is no explicit guidance on when to archive versus update/merge a customer, and no statement of prerequisites or consequences beyond the parenthetical.

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