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: it discloses the OAuth browser flow, local token storage, that it is a one-time operation, the exact scopes required, and the fallback behavior when credentials are absent. This is unusually rich behavioral disclosure for an auth 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?

Front-loads the purpose, then the prerequisite, then the invocation contract, then the no-credentials fallback. Length is justified by the multi-step setup the agent must relay; no sentence is filler.

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

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

Covers the full setup and invocation path including the degraded no-credential case, and with no output schema or annotations it is nearly complete. It stops short of describing token lifetime, refresh, or what happens if stored tokens expire, which an agent may need for follow-up calls.

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 client_id and client_secret are already documented, giving a baseline of 3. The description adds real meaning by tying the values to the user's Jobber developer app and explaining that calling without them is valid (consistent with required=0), which the schema alone does not convey.

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

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

States a specific verb (connect/authenticate) and resource (the user's Jobber account) via OAuth, and explicitly frames it as a one-time setup action. This clearly separates it from every sibling, all of which are read/query tools for jobs, invoices, quotes, etc.

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 prerequisite (create a developer app with read-only scopes, leave Callback URL blank) and an explicit no-credential path: calling without credentials returns setup instructions to relay to the user. The agent knows both when and how to 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?

With no annotations, the description carries the full burden and does the important part well: 'Nothing is ever sent or written to Jobber - the draft is returned for human review,' which rules out the main side-effect risk. It also discloses that facts are pulled live rather than from cached/stale data. It stops short of covering failure behavior (invalid client_id/invoice_id, missing facts) 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 sentences, front-loaded with the core action and the no-side-effects guarantee, then the message-vs-template conditional. No filler, no restating of the title, and every clause carries information an agent needs before invoking.

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

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

For an 8-parameter tool with no annotations, the description covers purpose, mode selection, and side-effect safety, which is the bulk of what's needed. The remaining gap is the return shape: there is no output schema, and the description only says 'the draft is returned' without indicating whether verified facts or a rendered template come back alongside 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 100%, so the baseline is 3 and the schema already documents all 8 parameters. The description adds real meaning on top: `message` is 'used verbatim' and suppresses template generation, while `purpose` drives template selection, and `invoice_id` facts matter mainly for payment reminders. That interaction between parameters is not in the schema.

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

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

States a specific verb and resource ('Compose a DRAFT message (email or SMS) to a client') and immediately scopes it as draft-only, distinguishing it from any send action. It also names the concrete enrichment source (Jobber invoice number, balance owing, due date, days overdue, client name), so an agent knows exactly what this tool produces.

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 branch: 'Provide `message` if you already wrote the body ... omit it to get a template based on `purpose`.' That tells the agent when to use which mode. It doesn't name alternatives among the siblings (e.g. fetch facts with get_unpaid_invoices first), but no sibling actually overlaps this compose capability.

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 the returned data shape, which is genuinely useful, but says nothing about permissions/auth needs, rate limits, or how 'recent' is bounded for jobs and 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?

Two tight sentences, front-loaded with the purpose and return contents followed by the prerequisite. No filler, 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?

With no output schema, the description correctly enumerates the return fields, so an agent knows what it gets back. The only gap is the vague 'recent jobs and recent invoices', which leaves the time window or count unspecified.

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% for the single parameter, so the baseline is 3; the description goes beyond the schema by explaining how to obtain the client_id via search_jobs, which is practical guidance the schema field itself does not provide.

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 ('Full profile for one client') and enumerates exactly what the profile contains: name, contact info, balance, member-since, recent jobs and invoices. This is clearly distinguishable from siblings like search_jobs or get_unpaid_invoices.

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

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

Gives an explicit prerequisite and workflow: find the client_id via search_jobs when you only know the name. It names the right alternative for name-based lookup, though it stops short of stating when NOT to use this tool (e.g., bulk 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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses that results are grouped by status and that filters are optional and server-side, but it does not mention authentication requirements, read-only safety, pagination behavior, or result ordering. The core behavior is implied but 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?

The description is three tight sentences: it front-loads the return shape and grouping, then gives the usage scenario, then lists filters. Every sentence earns its place with no redundant 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?

With no output schema and no annotations, the description does a good job explaining the return fields and the grouping behavior. It omits details about pagination (cursor/limit) and safety/permissions, but those are either covered by the schema or adequately implied for a read-only retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description restates the status enum options and client_id filter but adds no syntax, format, or behavioral details beyond what is already in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states the specific resource (quote pipeline) and the grouping behavior (grouped by status) along with the fields returned (quote number, client, total, job). It does not explicitly differentiate this tool from siblings like get_unpaid_invoices or search_jobs, but the resource is clear enough to distinguish it in practice.

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

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

It gives a concrete usage scenario: 'Use for pipeline questions like "which quotes are awaiting a response?"'. This provides clear context for when to use the tool, though it does not state when to prefer alternatives or any 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 full burden and does disclose meaningful behavior: the default range, sort order, embedded job/client data, and critically that filtering happens server-side on visit start time. It omits auth requirements and pagination mechanics despite limit/cursor parameters, 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 with no filler, and the most important scoping facts (resource, default range) are front-loaded. The date-format sentence partly duplicates the schema, but it is brief and harmless.

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 stand on its own, and it does describe what comes back (visits with job and client) and how filtering works. It stops short of documenting pagination behavior or access requirements, which an agent paging through results would benefit from.

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 all four parameters (from, to, limit, cursor) are already documented in the schema, making 3 the baseline. The description adds the server-side filtering semantics and restates defaults and the YYYY-MM-DD format, but does not explain cursor paging flow or how limit interacts with the cursor.

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 (visits/appointments) along with the scope (date range), ordering (sorted by start time), and the included relations (job and client). It is clearly a schedule/visit-listing tool, but it never states an explicit verb and doesn't differentiate itself from sibling retrieval tools like search_jobs or get_client_details.

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 call it to see visits/appointments over a date range, and the default window (today through +7 days) is given. There is no statement of when to prefer this over search_jobs, no exclusions, and no prerequisites, so the agent must infer the selection rationale.

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

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

With no annotations, the description carries the full burden and does disclose the crucial caveat that it scans only the most recent invoices (default 50) and filters on balance, so older unpaid invoices can be missed. It also names the sort order and derived fields. It stops short of stating read-only status explicitly, auth requirements, or whether results are paginated beyond the scan cap.

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 earning its place: the first defines the result set and ordering, the second gives the trigger scenario, the third exposes the scan-limit behavior. The most decision-relevant information 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?

With no output schema and no annotations, the description usefully compensates by naming the derived return values (days overdue, total outstanding) and the scan-window behavior. What remains thin is the read-only assumption and any pagination beyond the limit cap, but for a single-parameter list tool this is close to 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents that limit controls how many recent invoices are scanned. The description repeats that same 'scans the most recent invoices (default 50)' semantics rather than adding new 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 and resource (list invoices) plus the exact filter (status past_due / awaiting_payment, balance owing), the sort order (oldest-due first), and the returned fields (days overdue, total outstanding). Nothing about the tool's scope is left ambiguous, and it is clearly distinct from the sibling tools (jobs, clients, schedule, quotes).

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 use case with an example question: 'Use for accounts-receivable questions like

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 carries most of the behavioral burden by explaining server-side vs local filtering, default/max page size, and cursor pagination. It does not explicitly state read-only or authentication requirements, though 'Search' strongly implies a read operation.

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

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

Front-loaded with purpose and filters, then pagination details. The status value list duplicates the schema, but the overall paragraph is bounded and no framing 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?

No output schema exists, so the description carries the return explanation: up to limit results plus a cursor, and which fields are searched. It is adequate for a 7-parameter read search, though it omits auth or rate-limit 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 description coverage is 100%, so the baseline is 3. The description reinforces status enum values, date formats, default/max limit, and that client_id is a local filter, but adds little meaning beyond what the schema already 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 'Search' and resource 'Jobber jobs (work orders)', and enumerates searchable fields plus filter dimensions. No sibling tool provides job search, so it is readily distinguishable from get_quotes, get_schedule, and get_client_details.

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?

Explains that status, created date, and free-text filters are applied server-side and that client_id is a local filter, giving clear operational context. It does not name an alternative tool or state when not to use it, keeping it below a 5.

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