Workiz MCP by usefulapi

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

Annotations already carry destructiveHint=true, so the write/safety signal is partly covered. The description adds useful semantic context — the exact state transition (lost to active) and an explicit 'WRITE' label — but is silent on error behavior if the lead isn't lost, side effects, and reversibility, so the gain beyond annotations is modest.

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 label and the effect. The trailing 'Workiz: POST /lead/activate/{UUID}/' is somewhat redundant internal API detail but cheap and doesn't bury the key information.

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

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

For a single-parameter state-changing tool with an existing destructiveHint annotation and no output schema, the description covers purpose, effect, and mutated resource adequately. It lacks prerequisite/error conditions, but nothing essential for invoking 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?

There is a single parameter with 100% schema description coverage ('The lead's UUID (e.g. XYZ56X)'), so the schema already documents it fully. The description repeats the UUID placeholder in the endpoint but adds no format or constraint detail beyond what the schema provides, which is the baseline-3 case.

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

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

States a specific verb and resource with the state transition spelled out: change a lost lead back to active. This clearly distinguishes it from the sibling mark_lead_lost (its inverse) and from generic update_lead, so an agent can select it without opening the schema.

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

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

The precondition is implied (the lead must currently be lost) by the phrase 'a lost lead back to active.' However, it never names an alternative or states when-not to use it (e.g. versus update_lead or create_lead), so routing is left to inference.

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

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

Annotations only give destructiveHint=true; the description adds that this is a WRITE operation and that it is reversible via workiz_unassign_job, plus the underlying endpoint. That is genuinely useful risk context beyond the structured fields, though it says nothing about required permissions or failure modes.

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

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

Three terse fragments with zero filler; the WRITE classification is front-loaded so an agent scanning for mutating tools sees it 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 two-parameter mutation with a fully documented schema and no output schema, the description covers purpose, mutation class, and the undo path. Only the lack of any prerequisite or auth note keeps it short of complete.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the NAME-exactly-as-shown convention and the workiz_list_team pointer. The description's 'by name' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (assign), resource (a team member), and target (a job), with an explicit WRITE marker. It also names the inverse sibling workiz_unassign_job, so the agent can distinguish it from the other job/lead tools at a glance.

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

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

Names the reversal path (workiz_unassign_job), which hints at when this tool is the right call, but gives no explicit when-to-use vs alternatives or prerequisites (e.g. whether the job must already exist or the user must be active).

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

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

The 'WRITE' tag and 'Reversible with workiz_unassign_lead' statement add real behavioral context beyond annotations: the agent learns the mutation can be undone and what undoes it, plus the underlying endpoint (POST /lead/assign/). It omits failure modes (e.g. does it overwrite an existing assignee, or error on unknown names), but the annotations set a low bar and this clears 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?

Three short fragments, front-loaded with the operation type, then the action, then reversibility and endpoint. No filler; every clause carries information an invoking agent needs.

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

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

For a two-parameter write with no output schema and no nested objects, the description covers what it does, how to reverse it, and the parameter identity convention. Minor gaps remain around resolving the lead UUID and overwrite/error behavior, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100% and both parameters are fully documented there, including the 'name exactly as Workiz shows it' nuance. The description's 'by name' phrasing aligns with but does not extend the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (assign), a specific resource (team member to a lead), and the identifying key used for the member (by name). It also names the exact inverse operation, workiz_unassign_lead, which separates it cleanly from siblings like workiz_assign_job.

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

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

Gives clear context: this is a write operation, and workiz_unassign_lead is the way to undo it, which tells the agent when to pick the counterpart. It does not explicitly state preconditions (e.g. whether the lead must be active/open, or that the name must be resolved via workiz_list_team first), so it stops short of full when/when-not guidance.

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

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

Annotations only provide destructiveHint=true; the description goes further by spelling out that the API cannot undo the conversion and that the response contains a UUID and link. It stops short of noting what happens to the lead record afterward or 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 tight sentences with the WRITE/no-undo warning front-loaded, followed by the effect and return payload, then the endpoint. No filler and no repetition of the title.

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

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

For a one-parameter mutation with no output schema, the description supplies the essential context: irreversibility, the created resource, and the returned identifiers. The remaining gap is whether the originating lead is removed or archived.

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

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

Schema description coverage is 100%, so the single UUID parameter is already fully documented in the schema. The description adds no format, example, or constraint information beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('convert a lead into a job') and clarifies the side effect ('creates a new job from the lead'). This clearly distinguishes it from siblings like workiz_create_job (which makes a job without an existing lead) and workiz_activate_lead.

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 establishes the precondition (a lead must exist) and the consequence (irreversible conversion), but never says when to choose this over workiz_create_job or workiz_activate_lead, nor what state a lead must be in to be convertible. Usage is implied rather than stated.

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

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

Annotations only supply destructiveHint=true, so the description usefully adds that this is a WRITE, discloses the return payload (job UUID, ClientId, app link) despite there being no output schema, and names the backing endpoint. It stops short of stating permission requirements, validation/dedupe behavior for client fields, or reversibility.

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 statements, mutation flag front-loaded, no filler. Every clause carries information (what it creates, what it returns, the endpoint).

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

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

For a 25-param, all-optional create tool with no output schema, the description covers purpose and returns but omits what constitutes a minimally valid call and how duplicate clients are handled. Adequate as a starting point, but an agent still has open questions before invoking 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 coverage is 100%, so 3 is the baseline, but with 25 parameters the description's grouping into schedule, client contact/address, type, source, and notes meaningfully helps an agent navigate the flat field list. It still gives no guidance on which fields matter most or how they interact (e.g. ClientId vs inline client name 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 ('WRITE: create a new job') and enumerates what the job contains (schedule, client contact and address, type, source, notes). It does not differentiate from close siblings like workiz_convert_lead_to_job or workiz_create_lead, so an agent must infer the boundary itself.

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 'WRITE:' prefix signals a mutation, but there is no guidance on when to use this versus workiz_convert_lead_to_job (already have a lead) or workiz_create_lead (no job yet). No prerequisites are stated, e.g. whether a new client block or an existing ClientId is preferred.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral load; it usefully discloses the return payload (new lead's UUID, ClientId, app link) despite there being no output schema, plus the underlying POST /lead/create/ endpoint. It does not say whether any of the 25 fields are practically required to succeed, nor anything about permissions or duplicate 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?

Three compact sentences with the WRITE marker front-loaded, the captured data summarized in one parenthetical, and the return values stated last. Every sentence earns its place and nothing is repeated verbatim from the schema.

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

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

For a 25-parameter creation tool with 100% schema coverage and no output schema, the description covers purpose, payload categories and return values, which is nearly everything an agent needs. The remaining gap is that zero parameters are marked required, yet the description gives no hint about which fields matter in practice.

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

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

Schema description coverage is 100%, so every field including LeadDateTime, JobSource and ClientId is already documented in the schema; baseline is 3. The description's field grouping adds narrative framing but no format, default or constraint detail beyond what the schema provides.

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

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

States a specific verb and resource ("create a new lead") and then enumerates the payload's semantic scope (client contact and address, requested time, job type, source, notes), which is far more informative than the bare name. The naming alone separates it from the update_lead, convert_lead_to_job and create_job siblings, and the WRITE prefix signals state change.

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 and no mention of alternatives such as create_job, convert_lead_to_job or update_lead, even though those siblings overlap heavily at the 'Capture a job/lead' decision point. The reader must infer that this creates a fresh lead record rather than converting or updating one.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description goes further by enumerating the returned payload (schedule, status, contact/address, totals, amount due, notes, tags, team) and citing the backing endpoint, which is real added value given there is no output schema. It omits error/not-found behavior for an invalid UUID.

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

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

A single front-loaded sentence that names the lookup key first and then the payload, followed by a compact endpoint citation. No filler and nothing is buried.

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

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

With no output schema, the description correctly compensates by listing the returned fields, so an agent knows what it gets back. It stops short of covering failure modes (unknown UUID, missing permissions) or any response envelope 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 coverage is 100% and the schema already gives the UUID format with an example, so the description's 'by UUID' adds no syntax or format detail. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Fetch one job by UUID') and then enumerates what the job record contains, which cleanly separates it from workiz_list_jobs and workiz_get_lead. An agent can identify the tool without reading 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 'by UUID' implies the tool is used when the caller already holds an identifier, which contrasts implicitly with the list tools. However, no explicit when-to-use or when-not-to-use guidance and no sibling is named, so the routing must be inferred.

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

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

The readOnlyHint annotation already establishes the safe-read profile, and the description adds useful context beyond it by enumerating what comes back (schedule, status, client contact/address, source, notes, assigned team) and citing the underlying endpoint GET /lead/get/{UUID}/. It omits auth requirements, error behavior for an unknown UUID, and pagination/formatting details.

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

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

Two compact sentences with the identifier and return payload front-loaded; no filler or restated boilerplate.

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

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

With no output schema, the description correctly compensates by listing the returned fields, and the required UUID input is unambiguous. Slightly short of complete because it says nothing about failure cases or the shape/format of the returned data.

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

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

Schema description coverage is 100% and the single uuid parameter is already documented with an example, so the description's 'by UUID' adds nothing beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Fetch) and resource (one lead) scoped by UUID, which implicitly distinguishes it from workiz_list_leads. It does not explicitly name a sibling or contrast against the other lead tools, so it stops short of a 5.

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

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

Usage is implied: call this when you have a lead UUID and need a single lead. There is no explicit when-to-use/when-not guidance and no mention of the alternative (workiz_list_leads) for retrieving multiple leads.

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?

readOnlyHint=true already tells the agent this is a safe read, and the 'GET /team/get/{USER_ID}' endpoint reference reinforces that. Beyond that the description adds nothing about not-found behavior, permissions, or rate limits, so it clears the lower annotation-backed bar but no more.

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

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

A single front-loaded sentence naming the lookup key and returned fields, plus a compact endpoint reference. Nothing is padded or repeated, and the key information comes first.

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

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

With no output schema, the description is the only place listing what comes back (name, role, field-tech flag, email, service areas, skills, active status), which is a genuine contribution. It is nearly complete for a one-param read tool, with only usage guidance thin.

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 required parameter with 100% schema description coverage, which already explains the id and its source. The description only restates 'by user id' and adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one team member by user id') and enumerates the returned attributes, so the agent knows exactly what this returns. It is implicitly distinct from workiz_list_team, but it never names that sibling, 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?

'by user id' implies this is the single-record lookup to use once you already have an id, and the schema's 'from workiz_list_team' reinforces the chain. There is no explicit when-to-use, when-not-to-use, or alternative named in the description itself.

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?

readOnlyHint=true already covers the safety profile, so the description's real contribution is the emphasized 'FUTURE' filter, which tells the agent historical/past entries will not be returned. It adds nothing about pagination, result shape, or auth needs, keeping this at a solid-but-limited 3.

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

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

A single tight sentence, front-loaded with the action and scope, with the endpoint path appended as a compact routing aid. Nothing is padded or repeated.

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 tool with readOnly annotations, the description supplies the essential scope constraint (one named member, future records only). Return format and pagination remain undisclosed and there is no output schema, but the gap is minor 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?

Only one parameter and schema description coverage is 100%, so the schema already documents the name format and example ('Joe Acme'). 'By their name' merely restates the schema; 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 ('List ... time off') plus the narrowing scope ('one team member's', 'FUTURE'), which implicitly separates it from the sibling workiz_list_time_off. The sibling is not named outright, so it falls just short of a 5.

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

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

Requires a user_name, so usage is implied: call this when you want a single person's time off rather than the full list. No explicit when-to-use, when-not-to-use, or named alternative (workiz_list_time_off) is given.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing sort order, the 14-day implicit window, and the 100-record page cap — genuinely useful traits beyond the annotations, though nothing about rate limits or result 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?

Front-loads purpose and sort order, then filters, then defaults in a tight two-sentence block with no filler. The trailing 'Workiz: GET /job/all/.' is mild noise but does map the call to the underlying endpoint.

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 annotations covering safety, the description supplies sorting, default date window, paging limits, and filter semantics. Since there is no output schema, a brief note on returned record shape would have been ideal, leaving a small gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the 14-day default for start_date. The description's parameter notes (max 100, offset/records paging, status/open filters) largely restate the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List jobs') plus a distinguishing behavioral trait: results are sorted by JobDateTime descending. It is readily separable from get_job or list_leads, but it never names an alternative sibling for contrast, so it stops short of the 5 bar.

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

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

Gives concrete usage context: filter by start date, open-only and status, page with offset/records, and the crucial fallback that omitting start_date yields the last 14 days. No when-not-to-use or explicit alternate-tool routing is provided, which keeps it at 4.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one genuine behavioral trait beyond the schema: the implicit sort order (LeadDateTime descending) and the API endpoint. It does not discuss pagination termination, total counts, or what happens when filters match nothing, so the added context is modest.

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 zero filler: sort order and scoping constraints are front-loaded, then filters, then paging, then the endpoint reference. Every clause earns its place.

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

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

For a read-only list tool with no output schema and full schema coverage, the description covers filtering, paging, and ordering well. It stops short of describing the returned record shape or how to detect the end of a result set, which is the only meaningful gap for a paged list endpoint.

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

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

Schema description coverage is 100% and each of the five parameters (offset, status, records, only_open, start_date) is fully documented in the schema, including defaults and the 1-100 range. The description only restates 'filter by start date, open-only, and status; page with offset/records (max 100)' without adding format or edge-case meaning, so baseline 3 applies.

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

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

States a specific verb (list) and resource (leads), and adds the ordering semantics 'most recent first (sorted by LeadDateTime, descending)'. It is trivially distinguishable from get_lead, create_lead, and update_lead in the sibling set, and it even names the underlying Workiz endpoint.

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 enumerates what can be done (filter by start date/open-only/status, page with offset/records) which implies the retrieval use case, but it never states when to prefer this tool over workiz_get_lead for a specific record or how filters map to intent. Usage is implied, not 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful scoping detail that only 'active' members are returned, but says nothing about pagination, result limits, or auth requirements for the GET /team/all/ endpoint it cites.

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

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

Two tight sentences: the return contents come first, then the practical use, then the endpoint hint. Every clause carries information and nothing is repeated from the title or annotations.

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

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

With no output schema, the enumeration of returned fields is genuinely valuable and largely compensates. Only the absence of pagination/limit behavior keeps it from being fully complete for a list endpoint.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; schema coverage is trivially 100%. Baseline for a parameterless tool 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 ('List the account's active team members') and even enumerates the returned attributes (id, name, role, field-tech flag, email, service areas, skills). The plural 'list' plus 'active' scope cleanly separates it from the sibling get_team_member, though that 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?

Gives concrete downstream guidance: 'Use the name to assign people to jobs or leads,' which tells the agent why to call this before assign_job/assign_lead. It offers no when-not guidance or explicit alternative (e.g., use get_team_member for a single record).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds value beyond that by naming the returned fields (start, end, userName), explaining the 'Entire Business' sentinel for company closures, and citing the backing endpoint. It does not discuss sorting, pagination, or date-window bounds, which a 'future' query would benefit from.

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 verb and scope; the returned-field hint and the all=true rule both earn their space. The trailing endpoint citation ('Workiz: GET /TimeOff/get/') is marginally useful metadata rather than instruction.

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 only one optional parameter and no output schema, the description does the work of explaining what comes back (start, end, userName, company-wide marker) plus the scope toggle. That is sufficient for an agent to call it correctly; only pagination/date-range behavior is unaddressed.

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

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

Schema description coverage is 100% and the single parameter's behavior (include all users' and company time off, default false) is already documented in the schema. The description largely restates that semantics rather than adding new meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List FUTURE time off') and narrows scope with FUTURE and the userName/'Entire Business' distinction, which separates it from the single-user sibling workiz_get_user_time_off. It stops short of naming that sibling explicitly, so it is clear but not fully differentiated by routing language.

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?

'Useful before scheduling' gives an implied context for use, and the all=true sentence gives a clear selection rule. There is no explicit when-not guidance and no named alternative (e.g., workiz_get_user_time_off for a single user), so usage is only partially covered.

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

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

Annotations only supply destructiveHint=true, so the description adds real value: it labels the operation as a WRITE and discloses that it is reversible via workiz_activate_lead, which is the key behavioral fact an agent needs before mutating state. It omits auth/permission requirements and any response behavior, 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?

Three terse fragments, front-loaded with the action verb and safety warning, with zero filler. Every clause (operation, reversibility, endpoint) 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 single-parameter mutation with destructiveHint already declared and no output schema, the description covers what it does and how to undo it, which is sufficient to call it correctly. It could add permission or idempotency notes but nothing essential is missing.

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

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

Schema description coverage is 100% and the single uuid parameter is already documented with an example in the schema, so the description adds no parameter meaning. Baseline 3 applies when the schema carries the full burden.

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 ("mark a lead as lost") and explicitly names the inverse sibling workiz_activate_lead, so an agent can distinguish undo/redoing without opening a schema. The WRITE prefix further disambiguates it from the read-oriented list/get siblings.

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

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

The reversibility note ("Reversible with workiz_activate_lead") hints at the paired undo action, but the description never states when a lead should be marked lost versus updated or reassigned via workiz_update_lead or workiz_unassign_lead. Usage is implied rather than 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?

Annotations only supply destructiveHint=true, so the description meaningfully adds that this is a write/mutation and that the change is reversible by workiz_assign_job. It also discloses the underlying endpoint. It stops short of noting permission requirements or side effects on other assignments.

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 WRITE marker front-loaded and the reversibility path immediately following. 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 two-parameter tool with full schema coverage and no output schema, the definition covers mutation nature, reversibility, and the sibling used to resolve the user name. Missing only edge-case behavior such as what happens if the member is not assigned.

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

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

Schema coverage is 100%: UUID and User are both fully documented in the schema, including the 'exact name' constraint and the pointer to workiz_list_team. The description's 'by name' phrasing only restates what the schema already says, so baseline 3 applies.

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

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

States a specific verb and resource ('remove a team member ... from a job') with a leading 'WRITE:' marker, and names the inverse sibling workiz_assign_job, so an agent can distinguish it from workiz_assign_job without opening either schema.

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

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

Gives clear operating context: the operation is reversible via workiz_assign_job, and the job/member pairing is scoped. It does not explicitly state when to prefer this over e.g. workiz_update_job, but the routing to the inverse tool is 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?

Annotations only declare destructiveHint=true; the description goes beyond that by scoping exactly what is mutated (only the team-member assignment, not the lead) and disclosing a reversal path via workiz_assign_lead. It does not cover idempotency or error behavior, so it is not fully transparent.

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 terse fragments, mutation type front-loaded first, followed by reversibility and the raw endpoint. Nothing is wasted, though the 'POST /lead/unassign/' fragment is orientation rather than selection guidance.

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

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

For a two-parameter mutation with fully documented schema and no output schema, the description covers purpose, scope of change, and reversal. Adequate, with only minor gaps around failure modes and idempotency.

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

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

Schema description coverage is 100%, so both UUID and User are already documented with examples. The description's 'by name' merely corroborates the schema's User format note and adds no syntax detail beyond it; baseline 3 applies.

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

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

States a specific verb (remove/unassign) plus both resources (team member, lead) and the key selector ('by name'). An agent can distinguish it from workiz_unassign_job or workiz_assign_lead without opening a schema.

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

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

Explicitly names the counterpart operation (workiz_assign_lead) and frames this as its reversible inverse, which is real routing guidance. It stops short of stating when-not or prerequisites (e.g. must the member currently be assigned?), so it is not a full when/when-not treatment.

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

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

Annotations only supply destructiveHint=true; the description adds the materially useful behavioral fact that this is a partial update which leaves unpassed fields untouched, and labels the operation as a WRITE. It still doesn't disclose permission/authorization requirements, whether changes are reversible or notification-triggering, or what happens when ClientId reattaches a job to a different client.

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 terse fragments, front-loaded with the WRITE marker and the action, then the field groups, then the backing endpoint. Every clause carries information and 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 27-parameter mutation with no output schema and only a destructiveHint annotation, the description covers the essential call-correctness facts (required UUID via schema, partial-update semantics, writable field families). Remaining gaps are side-effect and failure behavior, which the annotations do not carry either.

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

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

Schema description coverage is 100%, so the schema already documents all 27 parameters with examples. The description's field-group summary (status/sub-status, reschedule, contact, address, type, source, notes, tags) organizes but does not add meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource (update fields on an existing job) and enumerates the updatable field groups, so an agent can immediately tell this is a partial-update mutation on an existing record rather than a create. It stops short of naming a sibling alternative (e.g. workiz_assign_job for assignment-only changes), so differentiation is inferred from 'existing job' 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 'Only the fields you pass are sent' clause implies the correct usage pattern for a PATCH-style update, but there is no explicit when-to-use guidance or any statement of when to prefer workiz_assign_job / workiz_unassign_job / workiz_update_lead over this tool. Usage is implied rather than directed.

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

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

Annotations only supply destructiveHint=true, so the description's "WRITE" marker and the explicit partial-update semantics (only passed fields are sent, untouched fields are preserved) add real behavioral value beyond the annotation. It still omits side effects such as whether changing Status triggers automation, permission requirements, or error behavior for an unknown UUID.

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 WRITE semantics and the most decision-relevant fact (partial update), with no filler. The field list is dense but earns its place by scoping what can be changed.

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 26-parameter mutation tool with a single required UUID and no output schema, the description covers the operation, mutation semantics, and endpoint. It is nearly complete, missing only return/confirmation behavior and whether the call fails or partially applies on an invalid field.

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

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

Schema description coverage is 100% across all 26 parameters, so the schema already documents every field's meaning and format. The description's field-group list (status, schedule, contact, address, type, source, notes, tags) largely restates what the schema provides and adds no syntax or constraint detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource ("update fields on an existing lead") and enumerates the field groups affected, making it immediately distinguishable from workiz_create_lead, workiz_get_lead, and the status-mutating siblings like workiz_activate_lead or workiz_mark_lead_lost. The Workiz endpoint (POST /lead/update/) pins down the underlying 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?

The description implies the partial-update contract ("Only the fields you pass are sent"), which is useful context for choosing this over a create call. However it gives no explicit when-to-use/when-not guidance and does not point to alternatives such as workiz_mark_lead_lost or workiz_convert_lead_to_job for status changes with dedicated tools.

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