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

Goes far beyond the annotations: it discloses irreversibility (no un-accept action), the two-phase preview/confirmToken behavior and MCP_CONFIRM_MODE dependency, and idempotent short-circuit semantics (already-accepted estimates return changed: false with no write). This is exactly the kind of context an agent needs before a destructive mutation.

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 but front-loaded: the core action and its irreversibility come first, followed by the confirmation mechanics and idempotency. The parenthetical PUT payload is slightly redundant but still earns its place as precision.

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, non-reversible mutation with no output schema, the description covers irreversibility, confirmation flow, idempotency behavior and the return value (re-fetched estimate). Nothing an agent needs to call it safely 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 the confirmToken schema description is itself detailed, so the description need not compensate. It reinforces the token's role in the flow but adds no new syntax or constraints beyond the schema.

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

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

States a specific verb+resource ('Accept an estimate') and even names the underlying API action, so it is immediately distinguishable from siblings like freshbooks_decline_estimate, freshbooks_send_estimate and freshbooks_update_estimate.

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 the confirmation workflow and the fallback path clearly, and points to freshbooks_list_estimates for obtaining the id. It does not explicitly state when to prefer a sibling instead (e.g., decline/send), but the acceptance scope is unambiguous.

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

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

Annotations already declare the mutation/side-effect profile (readOnly=false, idempotent=false, destructive=true), and the description adds substantial context beyond them: local vs hosted session behavior, what each returns (status vs refresh token), the single-use nature of the code, and the state-validation requirement. No contradictions with the annotations.

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

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

Three front-loaded sentences with no filler; purpose comes first, then session/return behavior, then the parameter constraint and the single-use warning. The first sentence packs multiple clauses (local vs hosted), which is dense but each 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 still tells the agent what is returned (status or refresh token, depending on session mode) and how failure must be handled. For a single-param auth-exchange tool this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents the 'code' parameter and that a bare ?code= value is refused. The description goes slightly further by explaining the state-matching rationale, adding meaning beyond the schema, though it partly repeats the schema's bare-code warning.

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 ('Complete FreshBooks authorization') and clearly positions itself as the exchange step relative to the sibling freshbooks_auth_url, which it explicitly names as the source of the state. An agent can distinguish this from freshbooks_auth_url 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?

Gives explicit when-to-use (after approving, with the whole redirect URL), a prerequisite (state must match a consent URL freshbooks_auth_url issued), and a when-not-to-do-something alternative ('if this fails, authorize again rather than retrying it'). Nothing about selection or sequencing 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 already declare readOnlyHint=true and openWorldHint=false, but the description adds non-obvious behavioral facts beyond them: the state parameter binds approval to this server, the URL is valid 15 minutes, and it is single-use. It also clarifies 'contacts nothing', which corroborates the openWorldHint=false annotation rather than contradicting 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?

Two sentences, front-loaded with the purpose and then the exact follow-up action, with no filler. Every clause (validity window, single-use, state binding, read-only) carries actionable information.

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

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

With no output schema, the description still tells the agent what it receives (a consent URL) and precisely what to do with it, closing the OAuth loop to the sibling tool. Nothing needed to invoke or continue the flow 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?

The tool takes zero parameters, so the schema baseline is 4 and there is no parameter syntax the description needs to carry. The description correctly spends no words on inputs.

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 ('Get the FreshBooks consent URL') plus the intent ('to authorize this connection'), and explicitly names the sibling it hands off to (freshbooks_auth_exchange). An agent can distinguish this from the exchange step 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?

Provides an explicit procedure (open, approve, land on redirect URL) and an exact handoff rule ('pass that whole URL to freshbooks_auth_exchange'), naming the alternative tool and the sequencing. This is a textbook when-to-use and what-next instruction.

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 annotations already declaring destructiveHint=true, idempotentHint=false and openWorldHint=true, the description still adds substantial behavior beyond them: the elicitation-or-fallback confirmation model, that the first call makes no network call and returns a preview plus confirmToken, and that only a repeat call with the token proceeds.

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?

Purpose is front-loaded in the first clause, followed by the confirmation mechanics; it is dense but every sentence carries necessary information about the two-step flow, with only mild reliance on the external MCP_CONFIRM_MODE reference.

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 seven-parameter mutation tool with a nested 'fields' object and no output schema, the description covers purpose, safety-relevant confirmation behavior, and the phase-1 response shape adequately; minor gaps remain around error/retry conditions, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the detailed confirmToken contract; the description adds no field-level syntax or format meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource — 'Create a client (customer) in FreshBooks' — which an agent can immediately distinguish from siblings like freshbooks_get_client, freshbooks_list_clients, or the create_invoice/create_project 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?

The description explains the two-phase confirmation flow and when confirmToken applies, which is real invocation guidance, but it never names or contrasts alternatives (e.g., when to create a client vs. reuse an existing one), so routing context is only implied.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description goes further and discloses non-obvious behavior: a confirmation prompt where supported, otherwise a no-network-call phase-1 preview plus confirmToken, and that only a repeat call proceeds. It still omits what the tool does on success/validation failure, so not a 5.

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

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

Purpose is front-loaded in the first sentence, with the confirmation flow following. The second sentence is dense and packs several clauses, but every clause carries operational meaning and there is 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 9-parameter destructive mutation with nested objects, no output schema and strong annotation coverage, the description covers the highest-risk aspect an agent must get right: the two-phase confirmation path that prevents an unintended write. Remaining gaps (return shape, error behavior) are minor given annotations and schema.

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

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

Schema description coverage is 89%, so the schema already documents amount, date, vendor, billable, clientid, categoryid and confirmToken thoroughly. The description adds no parameter-level detail beyond restating the confirmToken protocol, which itself is already fully described in 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 clear verb+resource ("Record an expense") that is easy to distinguish from siblings like freshbooks_get_expense or freshbooks_list_expenses. It does not explicitly name an alternative or scope its difference from update/list variants, but the purpose itself 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?

The description supplies important usage mechanics for the confirmation protocol, which is genuinely useful context. However, it gives no when-to-use vs when-not guidance against sibling write tools (e.g. when to reach for this versus a related expense or client tool), leaving that 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?

Adds significant context beyond annotations: drafts by default, the two-step confirmation fallback, no network call on the first call. Annotations already mark it non-idempotent and destructive, and the description's confirmation flow explains why, which is genuinely useful.

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 core action and initial state, then explains the confirmation flow. Slightly dense with parentheticals and a reference to MCP_CONFIRM_MODE, but 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?

Covers the create action, draft state, and the non-obvious confirmation mechanism that an agent must follow. Missing details on return value (no output schema) but the confirmation-form behavior is the key complexity and is well addressed.

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 89%, so parameters are largely self-documented. The description adds an implicit note about confirmToken handling but does not detail other params like lines, currency_code, or 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 (create) and resource (invoice) plus the initial state (drafts start as drafts). Distinguishable from siblings like freshbooks_update_invoice and freshbooks_list_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?

Explains the two-path confirmation flow clearly: uses a prompt where supported, otherwise a preview/confirmToken round trip. Lacks guidance on when to choose this vs. siblings like update_invoice or when a client must exist first.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the two-phase confirmation, that phase 1 issues no network call, and that only a repeat call with the token proceeds. It still omits what the preview contains 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?

The purpose is front-loaded in two words, then the confirmation contract follows compactly. The only friction is the trailing "see MCP_CONFIRM_MODE" reference, which points at something the agent cannot resolve and slightly pads the sentence.

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

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

For a destructive create tool with no output schema, the description covers the confirmation path and the confirmToken round-trip, which is the non-obvious part of invoking it correctly. It does not describe the post-creation result or the preview contents, and the MCP_CONFIRM_MODE pointer is dangling, keeping it short of full completeness.

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

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

Schema description coverage is 89%, so the schema already documents title, rate, fixed_price, project_type and confirmToken in more detail than the description. The description adds no parameter-level meaning beyond what is in the schema, so the baseline of 3 applies.

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

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

"Create a project" states a specific verb and resource, and no sibling tool also creates projects, so the operation is unambiguous. It does not explicitly differentiate itself from list_projects or get_project, but the verb alone separates it cleanly.

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 strong procedural guidance on the confirmation flow (what happens on the first call vs. a repeat call with the token), but says nothing about when to create a project versus another path, nor any prerequisites. Usage is implied through the mechanics rather than stated as when/when-not.

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 description discloses behavior the annotations cannot: that the tool pauses for user confirmation, that on non-elicitation clients the first call performs no network write and returns a preview plus confirmToken, and that only a repeated call with that token commits. This is exactly the kind of non-obvious side-effect and side-effect-avoidance behavior an agent needs, and it is consistent with destructiveHint=true rather than contradicting 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 sentences, front-loaded with the action and the unit constraint, with the confirmation mechanics packed into one dense clause. It is efficient, though the parenthetical MCP_CONFIRM_MODE reference assumes the reader has that context.

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 confirmation flow, the hardest part to get right, is covered well. But with eight parameters at 38% schema coverage and no output schema, the description leaves the agent without guidance on which ID combinations are valid, whether billable/note are optional, or what a successful commit 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 only 38%, so the description carries some burden, and it does reinforce the critical duration unit and explains the confirmToken lifecycle. However, six of eight parameters (note, billable, client_id, project_id, service_id, started_at) get no explanation of their relationships, optionality, or defaults, so it only partially compensates for the coverage gap.

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

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

The description opens with a specific verb+resource ("Log a time entry") and immediately pins the unit of the primary field (seconds). It does not name or contrast with a sibling such as freshbooks_list_time_entries, but the create action is unambiguous and there is no competing create-time-entry tool.

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

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

Usage is implied by the description and the required fields, but the text gives no explicit when-to-use/when-not-to-use guidance and never mentions the list_time_entries alternative for reading existing entries. The one piece of procedural guidance it does give (confirm first) is about flow, not tool selection.

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 declare readOnlyHint=true and openWorldHint=false, and the description substantially enriches that: it guarantees no request is ever sent, that the call always fails, and gives the underlying domain reason (no declined state, no decline webhook, only draft/sent/viewed/replied/accepted/invoiced). This is exactly the kind of context annotations cannot convey.

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 critical fact — the tool always fails and never sends a request — is front-loaded, and each following clause adds a distinct piece of evidence (status set, missing action, missing webhook, rationale). It is longer than most definitions but 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?

There is no output schema, and the description compensates by describing what the call yields (the reason plus alternatives). For a deliberately non-functional stub, an agent has everything it needs: it knows the call is safe, always fails, and why to use 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% for the single required 'id' parameter, so the schema already carries parameter meaning. The description adds nothing about the id (e.g., that it is accepted but unused), 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?

The opening sentence states exactly what the tool does: it always fails, never sends a request, and is not supported by the FreshBooks API. It also contrasts itself with the accept path ('there is no action_deny or action_decline counterpart to action_accept') and with update_estimate-style writes, so an agent can distinguish it from the real estimate 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?

It explicitly says when to call it ('Call it to get the alternatives') and explains the intent ('so this answers with the reason instead of a plausible-looking write that changes nothing'). It doesn't name the specific substitute tool (e.g., update_estimate for status changes), so routing is implied rather than fully spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing further: no auth requirements, no error behavior for an unknown or unauthorized id, and no return-format context. 'Numeric' mildly clarifies the id, but that is already in 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?

One short, front-loaded sentence that states verb, resource, lookup key, and id type with zero filler.

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

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

For a trivial single-parameter getter this is minimally viable, but there is no output schema, so the description could have said what a successful lookup returns or how a missing/unauthorized id is handled. Those gaps leave an agent to discover the response shape at call time.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as 'The client id' with type and exclusivity constraints. The description only echoes that it is a numeric FreshBooks id, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get a single client') and constrains the identifier ('by its numeric FreshBooks id'). It implicitly separates itself from freshbooks_list_clients by saying 'a single client', but never names or contrasts with that sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of freshbooks_list_clients as the alternative for browsing clients. The usage is only inferable from the verb 'Get' plus the required id, which is minimal.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the id is the numeric FreshBooks id, a useful additional detail, but says nothing about error behavior when an id is missing or not found.

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 that front-loads the action and object with zero waste. Slightly under-informative rather than padded, but appropriately sized.

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-param read tool with annotations covering safety and full schema coverage, the description is adequate but minimal. With no output schema, it does not hint at what an estimate record contains, which would help an agent use the result.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, so the description need not add more. It does clarify the id is numeric FreshBooks-specific, marginal added value over the schema.

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

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

States a specific verb (Get) and resource (single estimate) with the id key, which distinguishes it from freshbooks_list_estimates and freshbooks_get_invoice. It does not explicitly name a sibling, but the singular/numeric-id framing makes the retrieval-by-id scope 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 indication of when to use this versus freshbooks_list_estimates or freshbooks_get_invoice, nor any prerequisites. The only inferable guidance is that you need an id, which the schema already enforces.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds only the numeric-id requirement; it says nothing about error behavior for missing ids or return 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?

One short, front-loaded sentence with no filler; the verb and identifier are stated immediately. Nothing is wasted.

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

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

For a single-parameter read tool with no output schema, the description plus annotations and full schema coverage give an agent everything needed to call it correctly. Return-format details are the only omission, and they are minor here.

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

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

Schema description coverage is 100% with a single well-documented integer 'id' parameter, so the baseline is 3. The description's 'numeric id' adds no syntax or format detail beyond the schema's integer type and exclusiveMinimum constraint.

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

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

States a specific verb (Get) and resource (single expense) with the identifier type, which clearly separates it from list_expenses and create_expense. It does not, however, name a sibling or scope restriction explicitly, so differentiation relies on 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?

The phrase 'by its numeric id' implies this is the lookup path when an id is known, but there is no explicit when-to-use versus freshbooks_list_expenses or when-not guidance. Usage 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 cover readOnlyHint and openWorldHint; the description adds substantive behavior beyond them: the three identifiers are not interchangeable and the wrong one yields a 404 instead of a useful error, multi-business accounts populate a `businesses` list, and writes are blocked without an explicit business selection. That is real error-mode and side-effect disclosure.

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 then packed with the identifier distinctions and the write-refusal caveat. Every clause carries decision-relevant information; there is 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?

With no output schema, the description must describe what comes back, and it does: the three identifier fields plus the `businesses` list for multi-business accounts. Combined with the 404 and write-refusal warnings, an agent has everything needed to call and use this tool correctly.

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

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

The tool takes zero parameters, so per the baseline this dimension is at 4. The description adds useful meaning about the identifiers it resolves, though that is return-value information rather than parameter 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?

States a specific verb and resource: 'Resolve the authenticated FreshBooks user and their identifiers', then enumerates exactly what is returned (accountId, businessId, businessUuid). No sibling tool in the list performs identity resolution, so an agent can route here unambiguously.

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 downstream context: accountId is for accounting/payments endpoints and businessId for projects/time tracking, which tells the agent when each value is needed. It also states that writes are refused unless FRESHBOOKS_BUSINESS_ID selects a business. It stops short of an explicit 'call this first / call this before X' instruction, so it is strong context rather than a full when-to-use rule.

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 and openWorldHint, so the safety profile is covered elsewhere. The description adds only the 'numeric' qualifier and provides no additional behavioral context such as error behavior on a missing id or what happens for a non-existent invoice.

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 with no filler. Every word earns its place and the resource and key are 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 trivial one-parameter read tool with full schema coverage and a clear readOnly annotation, this is nearly complete. It only omits any hint about the returned invoice object, which is minor since the schema fully specifies the input.

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

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

Schema coverage is 100% and the single parameter is fully described, so the schema does the heavy lifting. The description repeats that the id is numeric, which the schema's integer type already conveys, and adds no new syntax or constraint detail.

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

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

States a specific verb ('Get') and resource ('a single invoice') and identifies the lookup key as the numeric FreshBooks id. This cleanly separates it from freshbooks_list_invoices (plural listing) and from get_client/get_payment by resource.

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 by-id lookup pattern implies when to use it, but there is no explicit guidance on when to prefer this over freshbooks_list_invoices or what to do if the id is unknown. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that — nothing about not-found/error handling, id validation, or response characteristics.

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 with the resource and selector front-loaded and no wasted words. It is efficient but so sparse that it borders on under-specification.

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

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

For a simple one-parameter read tool with full schema coverage, annotations, and no output schema, the description covers the essentials. Minor gaps remain around id-not-found behavior and prerequisite auth.

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

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

Schema description coverage is 100% and the single id parameter is fully documented as an integer id. The description's 'numeric FreshBooks id' merely restates the schema type, 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 (Get) and resource (a single item) plus the key selector (numeric FreshBooks id). It is clearly distinguishable from the sibling freshbooks_list_items, though it does not name alternatives explicitly.

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

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

Only hints that a numeric id is required, implying you must already have the id. It never says when to use this versus freshbooks_list_items or what to do if you lack the id.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds nothing beyond that — no behavior for an unknown/nonexistent id, no error semantics, and no note that the id must belong to the authenticated account. For a read tool with full annotation coverage, this leaves the description contributing almost no behavioral 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?

One sentence, front-loaded with the action and resource, with zero filler. Nothing could be removed without losing information.

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

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

For a single-parameter read operation whose read-only/open-world nature is already declared by annotations and which has no output schema to explain, the description says enough: it names the returned entity and the required identifier. Only minor details such as error behavior on a missing id are 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 description coverage is 100% and the single parameter 'id' is documented in the schema as 'The payment id' with type integer and a positive minimum. The description only restates this as 'numeric ... id', adding no syntax, format, or sourcing guidance (e.g., where to obtain the id) beyond the schema.

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

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

States a specific verb (Get) and resource (payment), plus the scope qualifier 'a single' which implicitly contrasts with the sibling freshbooks_list_payments. It stops short of naming the sibling or any differentiating condition explicitly, so it is clear but not maximally distinguishing.

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: an agent infers it should call this when it already has a numeric payment id and wants one record rather than a list. There is no explicit when-to-use statement, no mention of freshbooks_list_payments as the alternative, and no prerequisites (e.g., auth or account context).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds essentially nothing behavioral beyond restating the identifier type: no note on failure when the id is unknown, no auth/credential requirement, no indication of what a project payload contains.

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

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

One short, front-loaded sentence with the action and the identifier constraint stated up front. Zero filler.

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

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

For a trivial single-parameter read tool with annotations covering safety and no output schema, the description is minimally sufficient. It nonetheless omits any note on not-found behavior or what the returned project looks like, leaving small gaps an agent might need.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Project id', so the schema carries the load. The description's phrase 'numeric id' mildly reinforces the integer type but adds no format or constraint detail beyond 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 ('Get a single project by its numeric id'), which cleanly distinguishes a single-item fetch from the sibling freshbooks_list_projects. It does not, however, explicitly name or contrast any sibling, so it falls short of the top band.

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

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

There is no when-to-use guidance, no precondition (e.g. project must already exist), and no routing to alternatives such as freshbooks_list_projects for discovery or freshbooks_create_project for creation. Usage is only implied by the verb.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and not contradicted. The description adds only a minor behavioral note that string ids are coerced, and says nothing about missing-record behavior or error shape, so it clears the lowered bar without adding much.

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 front-loaded and no filler. The second sentence is somewhat redundant with the schema's id description, which keeps it just short of a 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?

No output schema exists, but a read-only single-record fetch whose parameters are fully specified needs little return documentation. The remaining gap is sibling disambiguation against the typed getters and list_records, which the description never addresses.

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 both parameters are already documented in full, including the enum of resource names and the integer-or-digit-string id rule. The description's id explanation largely restates the schema's own wording ('numeric for all currently mapped resources'), 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 concrete verb (get) and resource (a single record from any FreshBooks accounting resource) scoped by name and id. It is unambiguous what the tool returns, but it never distinguishes itself from the many typed siblings (get_invoice, get_client, get_expense) or from list_records, which an agent must reconcile 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?

No when-to-use guidance is given. With 17 resource-specific get_* siblings plus list_records, the description should say when the generic lookup is preferable (e.g. unmapped or dynamic resource names) versus the typed getter, but it offers neither conditions nor alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it resolves the credential the way real tools do, makes exactly one authenticated request, reports the credential source, and never returns the credential itself. It also explains the plain-English hint categories. This is strong added context, though it doesn't detail error formats or timeouts.

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

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

The description is compact and front-loaded: it opens with the core action, then details the outputs, then gives the usage trigger. Every sentence adds information; no filler or 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 zero-parameter diagnostic tool with rich annotations and a clear output description, the description is complete. It tells the agent what the tool does, what it reports, what it never does, and when to call it. No output schema exists, but the description enumerates the reported items sufficiently.

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 has zero parameters, so there is no parameter schema to document. The description fully explains what the tool does with its implicit inputs (credential resolution, upstream request). Baseline 4 is appropriate for a zero-parameter tool.

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 ('Resolves', 'makes one authenticated request') and resource (api.freshbooks.com), and clearly distinguishes this healthcheck tool from the data-access siblings. It explains what it reports (credential source, acceptance, round-trip time, hint) and explicitly says it is read-only.

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 an explicit when-to-use instruction: 'Call this when a real tool fails and you want to know which hop broke.' It also implies when not to use it (not for normal data operations) and distinguishes it from siblings by focusing on credential/upstream diagnostics rather than resource access.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that pagination is supported and that the response is an envelope of items plus page/pages/total, which is useful non-annotation context, but it omits anything about rate limits, auth failures, or empty-result behavior.

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

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

Three short sentences, zero filler, and the core action is front-loaded with supporting details (pagination, filters, return shape) following in order of importance.

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

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

With no output schema, the description usefully discloses the return envelope (items plus page/pages/total), and the nested search object is fully documented in the schema. An agent has enough to call it correctly, though auth/permission expectations remain unstated.

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

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

Schema description coverage is 100%, so page, per_page and search are already fully documented in the schema. The description only restates that pagination and raw filter params exist, adding no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('List clients for the authenticated FreshBooks account'), which clearly separates it from freshbooks_get_client and freshbooks_create_client. It does not explicitly name or differentiate against siblings, but the scope 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?

The description implies when to use it (bulk retrieval with pagination/filters) but never states when to prefer freshbooks_get_client or how it relates to freshbooks_list_records. Usage is inferable from the verb, not spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context on top: it discloses that raw FreshBooks filter params are passed through and that the response carries items plus page/pages/total — the latter is important because no output schema exists.

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 with zero filler, and the core purpose is front-loaded before the capability and return-shape notes. Every sentence carries distinct information.

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

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

With no output schema, the description usefully states the return shape ('items plus page/pages/total'), and it covers pagination and filtering. What is missing is any note on pagination limits, empty-result behavior, or auth failure handling, but for a low-complexity read-only list tool this is close to sufficient.

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 three parameters (page, per_page, search) are already documented in the schema with constraints like max 100 and 1-based numbering. The description only gestures at 'pagination' and 'raw FreshBooks filter params' without adding syntax or format detail, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List estimates') scoped to the authenticated FreshBooks account, which cleanly separates it from freshbooks_get_estimate and freshbooks_list_invoices. It does not explicitly name a sibling alternative, but the resource noun makes the distinction obvious enough 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?

The description says what is supported (pagination, raw filter params) but never says when to reach for this tool versus freshbooks_get_estimate for a single record or freshbooks_list_invoices/invoices-related siblings. There are no exclusions or prerequisites, leaving usage to inference from the name 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral on top of that: no mention of pagination, result limits, ordering, or what the response contains. With annotations carrying the burden, a low-but-not-floor score is appropriate.

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 states the action and the reason to call it, with zero filler. Nothing could be trimmed without losing information.

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

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

For a simple read-only list tool with annotations covering safety, the essentials are present, but there is no output schema and no description of the returned structure or pagination semantics. An agent can call it, but cannot anticipate the response shape.

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 both parameters (page, per_page) and the description never mentions them. Names are fairly self-explanatory, but for a paginated list endpoint the description should explain paging behavior; it does not compensate for the coverage gap.

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

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

States a specific verb and resource (list expense categories) and even explains the resource's downstream role in expense creation, which separates it from freshbooks_list_expenses and freshbooks_create_expense. It stops short of explicitly naming a sibling it is not, so 4 rather than 5.

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

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

The clause 'supply the categoryid used when creating an expense' gives clear implied context for when to call it (before freshbooks_create_expense). No exclusions or explicit when-not guidance are provided, so it does not reach 5.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), yet the description adds genuinely non-obvious behavior: newest-first ordering by default and the caveat that a reported total may include records the identity cannot read, surfaced in a `note` field instead of a silent empty result. That preempts a real misdiagnosis, though pagination mechanics themselves are only asserted, not described.

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, all load-bearing: the core operation leads, the filter capability follows, and the counter-intuitive count caveat closes. No restatement of the tool name or 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?

With no output schema, the description must gesture at the return shape; it covers ordering and the anomalous total-vs-rows case via the `note` field, which is the highest-risk return behavior. Remaining gaps (record shape, pagination response envelope) are minor 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?

Schema description coverage is 0%, so the description carries the burden. It compensates for the trickiest parameter by documenting the open-ended `search` object and its filter syntax with an example, but says nothing about `page` or `per_page` semantics (defaults, page size behavior) beyond the bare word "pagination".

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 expenses for the account") plus the default ordering, which immediately distinguishes it from freshbooks_get_expense, freshbooks_create_expense and freshbooks_list_expense_categories in the sibling set. An agent can route to 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?

It explains that raw FreshBooks filters are supported and gives a concrete filter example, which implies the filtering use case, but it never states when to prefer this over a single-record fetch or when filtering is unnecessary. No explicit when-not guidance or named alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: pagination support, verbatim pass-through of raw FreshBooks filters, and the response envelope (items plus page/pages/total), which is valuable given there is no output schema.

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

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

Three short sentences, front-loaded with the core action, then capability, then return shape. Every sentence carries distinct information with no repetition or filler.

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

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

For a read-only list tool with no output schema, the description compensates by describing the return envelope (items plus page/pages/total) and the pagination/filter model. It stops short of noting default page size or total-vs-page relationship, but an agent has enough 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 100%, so the schema already documents page, per_page and the passthrough search object in detail. The description restates the same capabilities (pagination, raw filters) without adding syntax or format 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+resource ('List invoices') and scopes it to the authenticated account, which distinguishes it from the singular freshbooks_get_invoice. It does not explicitly name that sibling or any other alternative, so an agent must infer the list-vs-single distinction.

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

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

Usage is implied by the name and the mention of pagination/filtering, but the description never states when to reach for this tool over freshbooks_get_invoice or freshbooks_list_clients, nor any exclusions or prerequisites. Adequate but with clear gaps.

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 and openWorldHint, and the description usefully adds that pagination is supported, that raw FreshBooks filter params are passed through verbatim, and that the response carries items plus page/pages/total. It stops short of disclosing rate limits, auth prerequisites, or error behavior, but it clears the (lower) bar set by the annotations.

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

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

Three short sentences, front-loaded with the primary action, then pagination/filtering, then return shape. No filler and nothing 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 helpfully states the return envelope (items plus page/pages/total) and the nested search object's pass-through nature is covered by the schema. What is missing is any indication of what 'items' contain or failure modes, but for a simple read/list tool this is close to sufficient.

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 page, per_page, and search are already fully documented, including the unvalidated filter-key pass-through. The description only restates that pagination and raw filters exist, adding no format or semantics beyond the schema — the baseline 3 for a fully covered 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 ('List items') scoped to the authenticated FreshBooks account, and notes pagination plus raw filter pass-through. It is clear what the tool does, though it never explicitly differentiates 'items' from lookalike siblings such as freshbooks_list_services or freshbooks_list_records.

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 resource and the mention of pagination/filter params, but there is no explicit when-to-use, when-not-to-use, or routing to an alternative (e.g. freshbooks_get_item for a single item, or freshbooks_list_services). An agent can infer intent but gets no guidance on selection.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true). The description adds real value on top by disclosing pagination support and the return envelope (items plus page/pages/total), which is meaningful since no output schema exists. It does not mention rate limits or default page size, 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 short sentences, each carrying distinct information: scope, capability, and return shape. Purpose is front-loaded and nothing is redundant or 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?

With no output schema, the description usefully summarizes the return envelope and confirms pagination and verbatim filter pass-through, which is enough for an agent to call a read-only list tool correctly. Minor gaps remain around defaults (e.g., default per_page) and error behavior, but the essentials are present.

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

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

Schema description coverage is 100%, so page, per_page and the raw search pass-through are already fully documented in the schema, including the concrete filter examples. The description only echoes this at a high level ('supports pagination and raw FreshBooks filter params'), adding no syntax or validation detail beyond the schema. Baseline 3.

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

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

States a specific verb (List) and resource (payments) scoped to the authenticated FreshBooks account, which cleanly separates it from the singular freshbooks_get_payment and the write tool freshbooks_record_payment. It does not explicitly name those siblings, so an agent must infer the list-vs-single distinction from the plural naming.

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

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

Usage is only implied by 'List payments'; there is no explicit statement of when to reach for this over freshbooks_get_payment or freshbooks_list_invoices, nor any prerequisite or exclusion guidance. Adequate but the agent gets no routing help.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the identifier convention and that the call succeeds even when the business has no accounting account. It omits any mention of pagination behavior despite exposing page/per_page.

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 filler, and the identifier caveat is stated directly. Efficient and front-loaded, though the second clause is somewhat implementation-detail heavy for the space available.

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

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

For a read-only list tool with no output schema the safety bar is low and the identifier note is helpful, but an agent still lacks pagination semantics and any hint about the returned project shape. Adequate but with clear 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% and neither page nor per_page is explained anywhere in the description. It does introduce businessId, which is not even present in the input schema, so the description partially compensates but leaves the two documented parameters unexplained.

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

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

States a specific verb+resource ('List projects for the business'), which is unambiguous against siblings like get_project and create_project. It does not, however, explicitly differentiate itself from other list tools (e.g., list_time_entries), so it falls short of a 5.

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

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

The description notes the required identifier type ('Uses businessId, not accountId'), which is a useful precondition, but it gives no when-to-use guidance versus alternatives such as get_project or the other list_* tools. No exclusions or routing conditions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: the return shape ('items plus page/pages/total') and the fact that plan- or role-gated resources report an error rather than returning rows. It does not mention rate limits or how the gating error surfaces, so it is not exhaustive.

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 purpose, then two short supporting sentences on return shape and gating. The long parenthetical resource list is dense but justified since it enumerates the tool's actual scope, though it partly repeats the enum.

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

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

With no output schema, the description usefully describes the return envelope (items plus page/pages/total) and warns about plan/role gating. The main remaining gap is pagination/filter parameter behavior, which neither the schema nor the description covers.

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% — 'page' and 'per_page' carry no schema descriptions, and the description says nothing about pagination or the pass-through 'search' object. The resource list in the description duplicates the enum already present in the schema, adding no new semantic value. With half the parameters undocumented in both places, the description fails 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 states a specific verb+resource ('List any FreshBooks accounting resource by name') and explicitly positions itself as 'the generic reader covering the long tail', naming concrete examples (taxes, credit notes, invoice profiles, tasks, staff, gateways, bills, etc.). It also distinguishes itself from siblings that have dedicated tools, so an agent can route correctly without opening a schema.

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

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

It clearly signals when this tool is the right choice — for the long-tail resources that lack dedicated tools — which is real routing guidance. It stops short of an explicit exclusion ('use freshbooks_list_invoices for invoices'), so an agent must infer that dedicated tools take precedence for the overlapping resources.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds domain context about services being billable work types, but says nothing about pagination behavior, result ordering, or volume despite taking page/per_page — modest added value over the annotations.

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

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

A single front-loaded sentence with a parenthetical clarification — nothing wasted, and the key concept ('services') leads.

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

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

For a simple read-only list tool this is close to sufficient, but with no output schema and no mention of pagination semantics or response shape, an agent lacks the information needed to page through results 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 neither 'page' nor 'per_page' is documented anywhere; the description contributes no syntax, defaults, or limits. With two parameters wholly undocumented in both schema and description, the parameter burden is largely unmet.

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 ('services') and usefully glosses the domain term as 'the billable work types available to projects and time entries,' which disambiguates it from items or projects. It does not explicitly name a sibling or contrast against freshbooks_list_items, so it falls short of a 5.

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

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

The description gives no when-to-use context, no prerequisites, and no guidance about alternatives such as freshbooks_list_items or freshbooks_list_projects. An agent knows what it returns but not when to reach for 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?

The annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful return-shape context (the envelope carries total_logged and total_unbilled), which matters given there is no output schema, but it says nothing about pagination behavior for a paginated 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 short sentences with no filler, and the core purpose is front-loaded before the return-envelope detail.

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

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

For a simple two-optional-parameter list tool the coverage is roughly adequate, and the return-envelope note compensates for the missing output schema. However, the pagination contract and any filtering scope are absent, which leaves the description 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 description coverage is 0%, so both parameters (page, per_page) are undocumented anywhere. The description does not mention pagination at all, leaving the agent to guess that these are page controls and what the default or page size limits are.

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 tracked time entries for the business'), which is unambiguous and clearly distinct from write siblings like freshbooks_create_time_entry. It does not, however, name or contrast any sibling tool, so differentiation is left to the reader.

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

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

There is no guidance on when to use this versus alternatives such as freshbooks_create_time_entry or freshbooks_list_projects, and no mention of scoping (project, client, date range). 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?

Annotations already declare destructiveHint=true, not idempotent, and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior beyond that: that the first call may make no network call and instead return a preview plus confirmToken, and that only a token-bearing repeat call proceeds. This is exactly the kind of extra context the annotations cannot carry.

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 action, followed by the confirmation flow; there is little waste. The trailing '(see MCP_CONFIRM_MODE)' is a compact pointer, and while the second sentence is dense, every clause conveys necessary two-phase 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?

For a destructive mutation with no output schema, the critical piece an agent needs — that a confirmation/preview gate exists and how to satisfy it — is fully disclosed. The absence of output schema is not a gap since the description explains the preview response; only auth/prerequisite details are omitted.

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 83%, so the schema already documents most params including confirmToken and the nested amount object. The description reinforces confirmToken's semantics but adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The first sentence states a specific verb and resource — 'Record a payment against an invoice' — which is unambiguous and clearly distinct from list/get payment siblings. It does not, however, explicitly name or contrast against a sibling, so it lands at 4 rather than 5.

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

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

The bulk of the description is dedicated to the confirmation workflow rather than when-to-use-this-vs-alternatives guidance; usage is implied by the purpose but no alternative or exclusion is named. The confirmation protocol is context-rich but is about how to invoke, not when to choose the 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?

The description discloses the side effect of putting mail in the client's inbox, the confirmation flow, and the two-step fallback with confirmToken. This goes well beyond the annotations (destructiveHint=true) and provides crucial operational context for the agent.

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

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

The description is front-loaded with the core purpose, then covers confirmation, recipients, and return value in a logical order. Every sentence adds unique information; it is long but justified by the complexity of the tool.

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

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

For a tool with a confirmation flow, recipient restrictions, and a two-step fallback, the description covers all essential aspects: side effects, confirmation mechanics, parameter nuances, and the return value. Nothing critical is missing for correct invocation.

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

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

Even though schema coverage is 100%, the description adds significant meaning: it explains that omitting email_recipients uses the client's address, clarifies when allow_non_client_recipients is appropriate, and details the confirmToken's exact usage and restrictions. This is valuable beyond the schema.

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

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

The description states a specific verb ('email') and resource ('an estimate'), and explains the underlying API call. It clearly distinguishes this from sibling tools like accept_estimate or decline_estimate by focusing on the email action.

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

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

It clearly states when to use the tool (to email an estimate) and provides guidance on recipient selection (omit to use client's address, or require allow_non_client_recipients for non-client addresses). However, it does not explicitly contrast with alternative actions like accept or decline, leaving that 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 declare destructive/not-idempotent/write, and the description goes well beyond them: it discloses the confirmation requirement, the two-step preview+confirmToken fallback that makes no network call, the destructive whole-set replacement of lines, and the re-fetched return. This is exactly the extra behavioral context annotations cannot carry.

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 layers in update semantics, confirmation behavior, the lines warning, and the return value in a tight sequence. Dense but every sentence carries actionable 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?

With no output schema, the description supplies the return behavior ('Returns the re-fetched estimate') and fully covers the confirmation workflow and destructive lines replacement. Nothing an agent needs to invoke this 14-param mutation 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 93%, so the baseline is 3, but the description adds real meaning: it explains that omitted fields are untouched (patch semantics across all 14 optional params) and reinforces the lineid-based replacement rule for lines. The confirmToken usage note is also restated usefully, though much of it duplicates schema text.

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

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

States a specific verb and resource ('Update an existing estimate') and immediately scopes it as a partial update ('Only the supplied fields are sent; anything omitted is left alone'). The estimate resource distinguishes it cleanly from the invoice/expense/project siblings.

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

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

Gives clear operational context: the confirmation flow that gates the call, and the critical rule that supplying lines replaces the whole set so existing lineids must be included. It stops short of naming an alternative tool or stating when-not-to-use, so it's strong context without explicit routing.

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

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

Beyond the annotations (destructiveHint true), the description reveals critical behaviors: potential emailing of invoices when changed out of draft, the two-step confirmation fallback with a non-network first call, and recipient validation rules. This significantly exceeds what annotations alone convey.

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 purposeful: core purpose first, then confirmation flow, then side effects, then recipient rules. Each sentence earns its place, though the length could be slightly trimmed 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 mutation tool with no output schema, the description covers everything needed: the action, the confirmation protocol, the fallback mechanism, the side-effect of emailing, and field-level recipient constraints. An agent can invoke this correctly without further external knowledge.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful nuance: 'Only the supplied fields are sent' explains partial updates, and the confirmToken/allow_non_client_recipients usage constraints go beyond the schema text. Slight redundancy with schema descriptions prevents a 5.

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 first sentence, 'Update an existing invoice,' uses a specific verb and resource, immediately distinguishing this from create_invoice and update_estimate. The remainder clarifies scope without obscuring the core purpose.

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 clear context: it is used to update existing invoices, with confirmation requirements and side-effect warnings clearly spelled out. It doesn't explicitly name alternatives like create_invoice, but the resource and verb make the intended use unambiguous.

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