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

With no annotations provided, the description carries the full burden and does so excellently. It discloses irreversibility, the dry-run preview behavior without confirmation, idempotency for already-accepted/invoiced estimates, that no write is sent in that case, and that the result is a re-fetched estimate.

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 purposeful sentences, front-loaded with the action and resource. Every sentence adds essential operational detail without redundancy.

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

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

Despite lacking annotations and an output schema, the description covers action, safety, state changes, idempotency, and return value. An agent has enough to invoke the tool correctly and understand the consequences.

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 input schema already fully documents both parameters (100% coverage), so the baseline is 3. The description adds meaningful value by explaining that confirm must be true to execute and that omitting it produces a dry-run preview with no network call, going beyond the schema's one-line description.

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

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

The description names a specific action ('Accept an estimate'), the resource ('estimates/{id}'), and the exact API operation ('action_accept'). This immediately distinguishes it from related siblings such as freshbooks_decline_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?

The description provides clear context: acceptance is irreversible, requires confirm:true, and behaves idempotently. It doesn't explicitly name alternative tools for rejection or modification, but the accept-vs-decline distinction is strongly implied by the sibling set and the tool's own semantics.

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=false and idempotentHint=false, but the description adds the critical single-use constraint, which is not conveyed by annotations. This is essential behavioral context that prevents harmful retry loops.

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 core action and immediately followed by the critical single-use warning. Every sentence earns its place with no redundancy.

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

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

For a single-parameter, no-output-schema tool, the description covers purpose, input flexibility, failure handling, and the correct sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and already explains that the parameter accepts either the ?code= value or the entire redirect URL. The description repeats this without adding new parameter-specific meaning beyond what the schema provides, 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?

Description clearly states 'Exchange a FreshBooks authorization code for a refresh token' – specific verb and resource. It distinguishes itself from sibling freshbooks_auth_url by explicitly pointing to it as the source for a new code when exchange fails.

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 clear input format guidance (whole redirect URL or bare code) and explicitly states when NOT to retry: 'The authorization code is SINGLE-USE — if this fails, get a new one from freshbooks_auth_url rather than retrying.' This routes the agent to the correct sibling.

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 the description reinforces this with 'Read-only; contacts nothing.' It also discloses the behavioral flow: open the URL, approve, land on redirect URL, then pass the code to the exchange tool. This adds meaningful context beyond the annotation.

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

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

The description is three compact sentences with no redundant information. It front-loads the core purpose and immediately explains the necessary follow-up action, making every sentence valuable.

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 tool with no output schema, the description fully covers what an agent needs: what the tool does, what the user must do, and how to proceed with the result. No critical information 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 has zero parameters, so there is nothing for the description to add beyond the empty schema. The baseline of 4 applies; the description correctly avoids inventing parameter details.

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

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

The description clearly identifies the tool's purpose: obtaining the FreshBooks consent URL for authorizing the connection. It distinguishes this from the sibling auth_exchange tool by explicitly naming it as the next step rather than this tool's function.

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 for when to use this tool: at the start of the authorization flow, before freshbooks_auth_exchange. It doesn't explicitly state when not to use it or list alternatives, but the flow guidance is strong and unambiguous.

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

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

With no annotations, the description carries the behavioral burden. It discloses that confirm=false results in no network call and a dry-run preview, which is useful, but this largely restates the confirm parameter description and adds only 'no network call.' It does not address auth requirements, return behavior, or duplicate handling.

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

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

The description is one compact, front-loaded sentence with no filler. The core purpose appears first, followed immediately by the critical execution requirement and dry-run 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?

The description covers the essential confirm-gating behavior, but with no output schema or annotations, it leaves unclear what a successful create returns and what auth state is required. This is acceptable but not fully complete for a 7-parameter creation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema already provides; the confirm behavior is mentioned in both places, but no new semantics are offered for email, fname, lname, fields, organization, or currency_code.

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 exactly what the tool does: 'Create a client (customer) in FreshBooks.' This names the action and resource, and it distinguishes the tool from sibling list/get tools and other create_* tools by specifying the client entity.

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 operational guidance about the confirm flag, explaining that confirm=true executes while confirm=false yields a dry-run preview. However, it does not explicitly state when to use this tool versus list/get clients or mention any exclusions or preconditions.

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

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

No annotations are provided, so the description must disclose behavior on its own. It clearly states that without confirm: true, the tool performs a dry-run preview and makes no network call, which is critical behavioral context. This exceeds the minimum and helps the agent understand side effects and idempotency. It could mention auth requirements or what happens with invalid data, but the confirm behavior is a strong 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?

The description is a single, front-loaded sentence that states the core action and then highlights the critical confirm behavior. It has no filler or redundant phrasing, earning efficiency. It is slightly sparse but effective, warranting a 4 rather than 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?

For a create tool with 9 parameters and no output schema, the description covers the most important operational nuance (confirm flag and dry-run behavior). The schema handles parameter details, and the description adds the execution model. It lacks guidance on error handling or required permissions, but given the simple action and high schema coverage, it is reasonably 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 high (89%), so the schema already documents most parameters, including the shape of 'amount' and the meaning of 'confirm'. The description adds little beyond what the schema provides, but it reinforces the confirm semantics and the two-phase nature. The 'fields' parameter is only minimally described in the schema ('Additional raw FreshBooks fields, merged'), and the description does not elaborate, which is a minor gap given the high coverage.

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

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

The description states a clear verb ('Record an expense') and resource, distinguishing it from other expense-related tools like freshbooks_get_expense or freshbooks_list_expenses. It also mentions the confirm flag, setting it apart from similar create tools. Although it could be more specific about the expense fields, it is sufficiently clear.

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

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

The description implies usage for creating an expense when the user wants to record one, and it highlights the two-step confirmation process. However, it does not explicitly contrast with alternatives like freshbooks_create_invoice or freshbooks_record_payment, nor does it state when not to use it. The confirmation requirement is useful guidance, but the 'when to use' context is only implicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that created invoices start as drafts, that confirm: true is required to execute, and that without it the tool returns a dry-run preview and makes no network call. This is essential safety and side-effect information. It could additionally mention what happens on success, but the core mutation behavior is transparent.

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

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

Two sentences, no filler, and the most critical behavioral constraint (confirm required, dry-run default) is front-loaded. Every word adds value, and the structure is scannable.

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 9 parameters, nested objects, and no output schema, the description is reasonably complete. It addresses the most important gotcha (confirm flow) and clarifies the draft status. It does not describe the return payload or error handling, but given the complexity, the missing return details are a minor gap that the schema's high coverage partially offsets.

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 high (89%), so the description's value-add is limited but meaningful. It adds semantics to the 'confirm' parameter by explaining the dry-run vs execution behavior, which the schema only labels as a boolean. This is exactly the kind of context an agent needs beyond the raw schema. Other parameters are adequately described in the schema, so no further description is necessary.

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

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

The description clearly states the tool creates an invoice for a client, which is a specific verb and resource. It distinguishes from siblings like freshbooks_update_invoice and freshbooks_get_invoice by noting created invoices start as drafts, implying new creation. No ambiguity.

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 confirmation requirement and the dry-run preview behavior, which gives clear context on how to execute. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use update_invoice instead), nor does it mention any exclusions. The usage context 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?

With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond 'Create a project' by revealing that without confirm: true the tool only returns a dry-run preview and makes no network call. This is a meaningful safety-related behavioral disclosure, though it does not cover authentication or response behavior after a confirmed create.

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 two sentences long, front-loads the primary purpose, and immediately follows with the most important execution nuance. Every sentence earns its place, and there is no padding or repetition.

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

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

Given a 9-parameter input schema with nested objects and no output schema, the description provides the key preview-vs-execute behavior but leaves other context to the schema. It does not describe what happens after a confirmed create (e.g., returned project object), nor clarify how fields, rate, fixed_price, and project_type relate beyond their schema descriptions.

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 nearly every parameter. The description adds the confirm: true behavior, but that is also reiterated in the confirm parameter's schema description. There is no additional semantic weight for parameters like project_type or the interplay between rate and fixed_price.

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

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

The description states the exact operation with a specific verb and resource: 'Create a project.' It is unambiguous and naturally distinguishes this tool from the sibling create_* tools by naming the target resource. The confirm-gating detail adds useful context without obscuring what the tool does.

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 a clear execution prerequisite ('Requires confirm: true to execute') and explains the dry-run fallback, which is useful operational guidance. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention read-only siblings like freshbooks_get_project or freshbooks_list_projects.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently reveals the dry-run preview behavior, the requirement for confirm=true to execute, and explicitly states that without confirm no network call is made. This is critical behavioral context that is not fully covered by the schema. However, it does not describe success responses or error handling, which slightly reduces the score.

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 extremely concise at two sentences, with the primary purpose front-loaded and the critical behavioral caveat (confirm/dry-run) immediately after. Every word earns its place, and there is no redundancy or fluff.

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

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description covers the most essential aspects: purpose, duration units, and the confirm dry-run behavior. However, it omits details about return values, the meaning of the ID fields, and any prerequisites or side effects beyond the dry-run. An agent could make a basic correct call but might lack context for optional parameters or expected outcomes, so it is not fully 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 only 38%, so the description must compensate for undocumented parameters. It clarifies duration (seconds) and confirm (must be true to execute), which are essential. However, it does not explain note, billable, client_id, project_id, service_id, or started_at beyond what the schema already provides (started_at has a schema description). The description adds value for two key parameters but leaves the rest unaddressed, so it only partially compensates for the low coverage.

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

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

The description states a clear verb and resource ('Log a time entry'), which conveys the tool's purpose unambiguously. It does not explicitly differentiate from the sibling freshbooks_list_time_entries, but the verb 'log' implies creation, so the distinction is apparent. The description is specific enough for an agent to understand what the tool does.

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 provides no guidance on when to use this tool versus alternatives, such as listing or updating time entries. It does mention the confirm requirement, which is a how-to-use detail, but not a when-to-use condition. No exclusions or alternatives are named, leaving the agent to infer usage 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?

The description fully discloses the tool's behavior: it always fails, never sends a request, and exists only to return the reason. It explains the underlying API limitations (no declined state, no action_deny/decline counterpart, no webhook event). With no annotations provided, the description carries the full burden and does so comprehensively. No contradiction with annotations (none exist).

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

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

The description is front-loaded with the key fact ('NOT SUPPORTED... always fails') and then explains the rationale and provides a call-to-action. It is slightly verbose with the detailed API explanation, but every sentence serves a purpose: it prevents the agent from expecting a plausible write and gives the reason. It is well-structured and not redundant.

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

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

For a tool with one parameter, no output schema, and no annotations, the description is complete. It explains the tool's failure mode, the exact reason, and what the agent should do instead. An agent has everything needed to understand that calling this will return an error with the reason, and that alternatives should be sought. Nothing essential is missing.

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

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

The input schema has 100% coverage with a clear description for the `id` parameter ('Estimate id'), so the schema already documents it. The description adds no additional parameter-specific meaning, but since the tool always fails regardless of the id, parameter semantics are moot. Baseline 3 is appropriate given high schema coverage.

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

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

The description states exactly what the tool does: it always fails and never sends a request, and it explicitly names the resource (estimates) and the unsupported operation (decline). It clearly distinguishes itself from siblings like freshbooks_accept_estimate by explaining that no declined state exists in the API. The purpose is unambiguous and not a tautology.

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 direct usage guidance: 'Call it to get the alternatives.' It tells the agent when to invoke it (when a decline is needed) and what to expect (the reason for failure instead of a fake write). It also implicitly warns against expecting a successful operation, which is crucial for agent behavior.

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

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

The readOnlyHint annotation already communicates that this is a read-only operation. The description adds only that the id is numeric and the fetch is for a single client, but does not disclose behavior around missing clients, authentication, or return shape. Given the annotation covers the main safety trait, this is acceptable but not rich.

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

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

The description is a single, direct sentence with no filler. It front-loads the operation, resource, and key identifying detail, making it easy for an agent to parse quickly.

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-only get-by-id tool, the description plus the input schema and readOnlyHint are largely sufficient. It lacks explicit notes about not-found behavior or response format, but the operation is conventional and simple enough that this is a minor gap.

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

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

Schema description coverage is 100%, and the schema already documents the 'id' parameter with type, bounds, and description. The tool description only repeats that the id is numeric, adding little beyond what the structured schema already provides.

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

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

The description states a specific verb ('Get'), a specific resource ('a single client'), and the exact identifier ('numeric FreshBooks id'). This clearly distinguishes it from list_clients (bulk retrieval) and create_client (mutation), so the agent can tell it apart from siblings.

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

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

The description implies when to use the tool: when you need one client by its known id rather than listing or searching clients. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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

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

The readOnlyHint annotation already establishes this as a safe read operation, and the description's 'Get' aligns with that without contradiction. The description adds little beyond that, such as error behavior or response format, but for a simple get-by-id tool the annotation coverage is sufficient.

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 compact sentence with no filler, placing the verb and resource first and the key selection criterion ('numeric FreshBooks id') last. Every word 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 one well-documented required parameter, a readOnly annotation, and no output schema needed for a straightforward fetch, the description is sufficient for an agent to invoke the tool correctly. Nothing essential is missing.

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

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

The schema fully documents the single required id parameter with type, bounds, and a description. The description's 'numeric FreshBooks id' reinforces the parameter type but does not add material semantic value beyond what the schema already provides.

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

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

The description states a specific action ('Get a single estimate') on a specific resource, qualified by 'numeric FreshBooks id'. This clearly distinguishes it from list_estimates and from state-changing siblings such as accept_estimate or 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?

The phrasing 'single estimate by numeric id' establishes a clear use case: retrieve one known estimate by its id. It does not explicitly name alternatives like list_estimates for searching, so it stops short of full alternative 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?

The description aligns with the readOnlyHint annotation, confirming this is a read operation. It adds little beyond the annotation, though it does clarify that exactly one expense is returned rather than a collection.

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

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

The description is a single, front-loaded sentence with no filler or redundant explanation. It earns its place by stating the core operation and key parameter characteristic.

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

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

For a one-parameter read-only getter with the readOnlyHint annotation, the description is mostly sufficient. It lacks an explicit mention of the return payload, but the tool name and wording make the returned resource obvious.

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 input schema fully documents the single 'id' parameter with description, type, and constraints, so schema coverage is 100%. The description's mention of 'numeric id' adds no meaningful 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?

The description states a specific verb ('Get'), a resource ('a single expense'), and the lookup key ('numeric id'). This clearly distinguishes it from sibling tools like freshbooks_list_expenses and freshbooks_create_expense.

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

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

No guidance is given about when to use this tool versus alternatives such as freshbooks_list_expenses or freshbooks_get_expense related flows. There is no mention of prerequisites, exclusions, or how an agent might obtain 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 only provide readOnlyHint=true; the description adds substantial behavioral context beyond that: the specific error behavior (404 on wrong ID), the multi-business listing, and the write-refusal rule. It also clarifies that the tool resolves identity without side effects, consistent with the read-only hint.

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

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

The description is three sentences, each earning its place. The first sentence states the purpose and lists the identifiers; the second warns about interchangeability and error behavior; the third explains the multi-business scenario and the write-refusal condition. It is front-loaded with the core action and scoped efficiently.

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

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

Given no output schema, the description fully explains the return values (accountId, businessId, businessUuid, and businesses list) and their meaning. It also covers edge cases (multiple businesses, write refusal) and error behavior. An agent can call this tool without any further guidance.

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 the schema is trivially 100% covered. The baseline for 0 params is 4, and the description adds value by explaining the semantic meaning of the identifiers returned, even though that is output-oriented rather than parameter-oriented. There is nothing missing regarding parameters.

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 clear, specific verb+resource: 'Resolve the authenticated FreshBooks user and their identifiers.' It explicitly names the three identifier fields (accountId, businessId, businessUuid) and distinguishes them by their usage. This is distinct from all sibling tools, none of which are identity-resolution 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 when this tool is needed (to obtain the user's identity) and provides critical usage guidance: the identifiers are not interchangeable, and using the wrong one yields a 404. It also warns that writes are refused when the identity belongs to multiple businesses unless FRESHBOOKS_BUSINESS_ID selects one, giving the agent an explicit precondition for subsequent mutations.

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

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

The readOnlyHint annotation already establishes this as a safe read operation, and the description's 'Get' is consistent with that. The description adds no behavioral context beyond the annotation, such as not-found behavior or return shape, but for a simple getter the annotation covers the main safety trait.

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

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

One short, front-loaded sentence with no filler. It places the operation first, then the resource and the lookup key, making every word meaningful.

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

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

For a one-parameter read-only getter, the description supplies the essential selection and invocation information. It does not explicitly describe the return value or error behavior, but the simplicity of the operation and the readOnlyHint annotation make this a minor gap.

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

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

Schema description coverage is 100%, with the id property described as 'The invoice id', so the baseline applies. The description only adds 'numeric', which duplicates the integer type already present in the schema.

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

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

States a specific verb ('Get'), a specific resource ('single invoice'), and the lookup key ('numeric FreshBooks id'). This clearly distinguishes it from siblings like freshbooks_list_invoices and freshbooks_update_invoice.

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 'a single invoice by its numeric FreshBooks id' implies the intended use case: retrieving one record by ID. However, it does not explicitly say when to prefer list_invoices or mention alternatives/exclusions, leaving some inference to the agent.

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

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

The readOnlyHint annotation already establishes that this operation has no side effects, and the word 'Get' is consistent with that. The description adds no extra behavioral context such as error behavior or authentication requirements, though for a trivial single-item read this is only a minor gap.

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

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

The entire description is one compact sentence with no filler. Every phrase ('single', 'numeric', 'FreshBooks id') earns its place by carrying identifying 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 one-parameter read-only get operation, the description is complete: it identifies the resource, the required input, and the result. No output schema exists, but 'Get a single item' sufficiently conveys the return value, and nothing needed to call it correctly is 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 coverage is 100%, so the schema already documents the only parameter ('id') as a positive integer. The description's 'numeric FreshBooks id' merely restates the schema's type and purpose rather than adding new meaning, which matches the baseline for high schema coverage.

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

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

The description names a specific verb ('Get'), a specific resource ('a single item'), and the identifying key ('numeric FreshBooks id'), which is enough to distinguish it from sibling freshbooks_list_items. It is unambiguous and action-oriented.

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 usage is implied rather than stated: an agent can infer to use this when it has an item id and needs one item, but the description gives no explicit when-to-use guidance or alternatives such as freshbooks_list_items for retrieving multiple items. There is no exclusionary 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?

The readOnlyHint annotation already covers the non-destructive safety profile, and the description confirms a single-record fetch by id. It does not disclose error/not-found behavior, auth requirements, or response shape, but for such a simple read-only tool this is a minor gap rather than a serious omission.

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. Every word contributes to identifying the operation, the resource, and the required id selector.

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

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

For a one-parameter, read-only getter, this is nearly complete: the operation and required argument are clear, and readOnlyHint covers side effects. The absence of an output schema means return shape is not described, but the tool's simplicity makes that a tolerable gap.

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

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

Schema coverage is 100% and the id parameter is already documented as an integer payment id. The description's 'numeric FreshBooks id' adds slight domain context, but it mostly restates what the schema already provides, so it stays at the baseline.

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

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

The description uses a specific verb ('Get'), names the resource ('a single payment'), and specifies the selection mechanism ('by its numeric FreshBooks id'). This clearly distinguishes it from freshbooks_list_payments and freshbooks_record_payment without needing to inspect schemas.

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 'single... by id' phrasing implies the tool is for retrieving one known payment, but it never explicitly tells the agent when to prefer it over freshbooks_list_payments or what conditions make it the right choice. No alternatives are named and no exclusions 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 provide readOnlyHint=true, covering the read-only safety profile. The description adds no further behavioral detail such as error behavior, authentication requirements, or response shape, though the 'single project' wording does clarify cardinality.

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 conveys the operation, resource, and cardinality with no filler or redundancy. Every word earns its place.

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

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

For a one-parameter, read-only get-by-id tool with no nested objects or output schema, the description plus schema and annotations is sufficient for an agent to select and invoke it correctly. No additional context like pagination or filtering is relevant 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%, so the schema already documents id as a positive integer with the description 'Project id'. Saying 'numeric id' reinforces the type but contributes no new semantic meaning 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 an action 'Get', a single resource 'project', and the key condition 'by its numeric id'. This clearly separates it from freshbooks_list_projects (plural/list) and other get_* tools for different resources.

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' signals that this is for retrieving one specific project when the ID is known, and the sibling tool freshbooks_list_projects provides the obvious alternative when listing is needed. It does not explicitly state exclusions, so it stops short of a 5.

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

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

Annotations already mark the tool readOnlyHint=true, and the description consistently describes a read operation ('Get a single record'). It adds a useful nuance about numeric ids also accepting strings, but it does not go beyond that to disclose auth requirements, error behavior, or response shape. With annotations covering the safety profile, this is adequate but not rich.

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 concise sentences with no filler. The action and scope are front-loaded, and the id-type clarification is the only supporting detail. Every sentence earns its place.

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

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

For a two-parameter read-only tool with a comprehensive enum and 100% schema coverage, the description is almost sufficient. It clearly tells the agent what to pass (resource name and id). The only gap is that no output schema exists and the description does not describe the returned record shape, but for a simple getter this is a minor omission.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description's id flexibility note is already reflected in the schema's anyOf for integer/string and the 'numeric for all currently mapped resources' text. The description adds little semantic value beyond what the structured schema provides.

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

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

The description clearly states the tool gets a single record from any mapped FreshBooks accounting resource by name and id. The word 'any' plus the resource-and-id framing distinguishes it from the many specific sibling getters like get_invoice or get_client. This is a specific verb + resource with clear scope.

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

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

The description implies usage when you know the resource name and record id, and the generic 'any resource' phrasing suggests it is the fallback across the enum of resources. However, it does not explicitly say when to prefer this over the dedicated get_* siblings or list_records, nor does it mention any exclusions.

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

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

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?

Beyond the readOnlyHint annotation, the description discloses the response shape ('items plus page/pages/total') and mentions support for pagination and raw FreshBooks filter params. This adds useful behavioral context about return format and parameter behavior without contradicting the annotation.

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, well-structured sentence that front-loads the primary purpose, then adds key behavioral details. No filler or redundancy; every word contributes value.

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 list tool with annotations covering the read-only safety profile and schema fully documenting parameters, the description adequately covers return structure and core behavior. It doesn't address error handling or edge cases, but these are not essential for a straightforward list operation. The lack of explicit sibling differentiation is a minor gap but not critical.

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 all three parameters already well-documented (page, per_page, search). The description only summarizes that pagination and raw filters are supported, adding no new meaning beyond what the schema provides. Baseline of 3 is appropriate given high coverage.

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

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

The description clearly states the action 'List clients' with a specific resource and scope ('for the authenticated FreshBooks account'). It unambiguously distinguishes this from get_client (singular) and other list tools by naming 'clients'. The verb and resource are explicit and non-tautological.

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

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

The description implies usage (listing clients) but provides no explicit guidance on when to prefer this over alternatives like get_client for a single client, or when to avoid it. The agent can infer from the name, but there's no direct statement of exclusions or alternative 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?

The readOnlyHint annotation already signals a safe read operation, lowering the bar. The description adds valuable behavioral details: it supports pagination and raw filter params, and specifies the return shape (items plus page/pages/total). This goes beyond the annotation and informs the agent of expected output structure and flexibility, though it does not disclose potential rate limits or error conditions.

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

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

The description is a single, front-loaded sentence that immediately states the core function. It includes key details (pagination, filters, return format) without any fluff. Every clause contributes value, making it highly efficient for an agent to parse.

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

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

For a list operation with optional parameters, the description is sufficiently complete. It mentions the return format (items plus page/pages/total), which is essential since there is no output schema. It does not mention authentication, but 'authenticated FreshBooks account' implies that. Minor gaps like pagination defaults or error behavior are not critical for a read-only list tool, so this is a solid 4.

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 three parameters (page, per_page, search) with their descriptions. The description's mention of 'pagination and raw FreshBooks filter params' slightly reinforces the purpose of the search parameter but does not add significant meaning beyond the schema. With full coverage, 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?

The description states a specific verb and resource: 'List estimates for the authenticated FreshBooks account.' It clearly distinguishes from the sibling tool freshbooks_get_estimate (singular) and other list tools like freshbooks_list_invoices. The purpose is unambiguous and directly indicates the operation.

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

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

The description gives clear context that this tool lists estimates, implying it should be used when retrieving multiple estimates or with filters. However, it does not explicitly mention when not to use it (e.g., when a single estimate is needed, use get_estimate) or reference any alternatives. It provides clear context but lacks explicit exclusions.

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

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

Annotations already provide readOnlyHint=true, so the description doesn't need to state that. The description adds useful context about the categoryid relationship, but it doesn't disclose pagination behavior, sorting, or response format. With annotations covering the safety profile, the description adds some value but not rich behavioral detail.

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 sentence that conveys the core purpose and a key dependency. Every word earns its place, and the most critical information (that it supplies categoryid) is front-loaded. There is no verbosity 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?

The description is minimal. It explains the main purpose but omits details about pagination parameters, the response shape (no output schema exists), and any sort/filter options. For a list operation with two undocumented parameters, this is incomplete. An agent would have to guess the meaning of page and per_page or rely on 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 description coverage is 0%, and the description does not mention the page or per_page parameters at all. The schema has no descriptions for these fields either, so the agent has no guidance on their semantics or limits. The description fails to compensate for the lack of schema descriptions, leaving parameters entirely 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?

The description states a specific verb and resource: 'List expense categories'. It also adds the key purpose of supplying categoryid for creating expenses, which is a specific, actionable detail that distinguishes it from other list tools like freshbooks_list_clients or freshbooks_list_invoices. The purpose 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 usage for fetching category IDs before creating an expense, but it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or alternatives. The context is implied rather than stated clearly, so it lacks explicit routing guidance.

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

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

Annotations only provide readOnlyHint=true, but the description adds critical behavioral context: newest-first default ordering, pagination support, raw filter syntax with an example, and the subtle edge case where a total count may include unreadable records reported in the note field. This goes far beyond the annotations and fully discloses the tool's behavior.

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

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

Two sentences with zero redundancy. The purpose is front-loaded, the pagination and filter capabilities are stated efficiently, and the edge-case explanation is concise and directly relevant. Every word earns its place.

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

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

For a list operation with three optional parameters and no output schema, the description covers the essential behaviors: default sorting, pagination, filter mechanism, and the note-field behavior for unreadable records. It is complete enough for an agent to call this tool correctly without further inference.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'search' accepts raw FreshBooks filters with an example, and mentions pagination which maps to page and per_page. While it does not spell out the exact parameter names or value constraints, it provides enough semantic grounding for an agent to use the schema correctly.

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

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

The description clearly states the verb 'List' and the resource 'expenses for the account', with an explicit default ordering. It distinguishes itself from sibling list tools by naming the resource and the additional raw-filter capability, leaving no ambiguity about which list operation this is.

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

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

The description implies usage for listing expenses, and the sibling names (list_services, list_invoices) make the resource-specific purpose clear. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for an agent to route correctly. A stronger definition would note that get_expense handles a single expense.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by stating that pagination and raw FreshBooks filter parameters are supported and that the response contains items plus page/pages/total. It does not cover errors or rate limits, but for a read-only list tool this is not a significant gap.

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

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

The description is three short sentences, each contributing a necessary point: what it lists, its capabilities, and the return shape. It is front-loaded and contains 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 helpfully provides the high-level response shape (items plus page/pages/total) and notes the raw filter pass-through. Combined with the exhaustive parameter descriptions and readOnly annotation, it is complete enough for an agent to call the tool safely and interpret results.

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 input schema already thoroughly documents page, search, and per_page. The description's mention of pagination and raw filter params reinforces the intent but does not add meaning beyond what the schema already provides.

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

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

The description uses a specific verb and resource ('List invoices') and scopes it to the authenticated FreshBooks account, making the tool's function unmistakable. It is easily distinguishable from sibling tools like freshbooks_get_invoice (single record) and freshbooks_create_invoice (write operation).

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

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

The description gives clear functional context (listing, pagination, raw filters) but does not explicitly say when to prefer it over alternatives such as freshbooks_get_invoice or freshbooks_list_estimates. Usage is implied by the action/resource pair rather than stated as direct guidance.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety is covered. The description adds behavioral value by noting pagination support, raw pass-through of FreshBooks filter params, and the returned pagination fields (page/pages/total), which goes beyond the annotation alone.

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, front-loaded with the core purpose, and each sentence contributes either capability or return information. It is slightly less tight than ideal, but it avoids waste and remains easy to scan.

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 well-documented parameters and no output schema, the description covers the essential behavior, filtering, pagination, and return summary. It could be more complete by stating default pagination values or clarifying the item shape, but the current information is sufficient for an agent to invoke 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 input schema already fully documents page, search, and per_page. The description briefly mentions pagination and raw filter params but does not add meaningful parameter-level meaning beyond what the schema provides, hence the baseline score of 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?

The description uses a specific verb and resource: 'List items for the authenticated FreshBooks account.' This clearly distinguishes it from sibling tools such as freshbooks_list_services and freshbooks_get_item, since 'items' is a distinct resource and the action is a collection listing rather than a single-item retrieval.

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 provides no guidance about when to use this tool versus alternatives like freshbooks_list_services or freshbooks_get_item. It states only what the tool does, not when it is preferred or when a sibling should be used instead.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. It adds behavioral context by noting pagination support, raw filter passthrough, and the return shape ('items plus page/pages/total'). This goes beyond the annotation and helps the agent understand pagination behavior and response structure.

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 with no extraneous words. The core purpose is front-loaded, followed by key behavioral notes. Every sentence earns its place, and the description is appropriately sized for a list operation.

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 list tool with 3 optional parameters and no output schema, the description covers the essential aspects: pagination, raw filter usage, and return shape. It does not cover error cases or authentication, but those are common across the tool set and annotations cover safety. Minor gaps, but sufficient for correct invocation.

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

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

Schema description coverage is 100%, with each parameter (page, search, per_page) already documented in the schema. The description adds no additional parameter-level meaning beyond the schema, merely summarizing that pagination and raw filters are supported. With high coverage, 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 clearly states the verb 'List' and resource 'payments', specifying the scope as 'for the authenticated FreshBooks account'. It distinguishes from sibling tools like freshbooks_get_payment (single payment) and other list tools by resource type. The phrase 'List payments' is unambiguous and specific.

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 does not explicitly contrast with alternatives such as freshbooks_get_payment or other list tools. Usage is implied (e.g., listing multiple payments) but no when/when-not guidance or explicit alternative references are given. It is clear enough for an agent to infer use, but lacks 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?

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds a valuable behavioral detail—'works even when the business has no accounting account'—which is not captured in annotations and gives insight into the tool's edge-case behavior.

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

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

Two sentences with no extraneous wording, and the core purpose is front-loaded. The businessId note is a bit awkwardly placed but the overall structure is efficient and readable.

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 list tool, the description covers the key differentiator (businessId) but leaves pagination behavior undocumented and does not mention the return format. The businessId reference is ambiguous without a schema parameter, creating a gap in understanding how to invoke the 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?

Schema coverage is 0%, yet the description does not explain the two actual parameters (page, per_page) at all. Instead, it introduces 'businessId', which is not present in the schema, potentially confusing an agent into looking for a nonexistent parameter. The description fails to compensate for the schema's lack of parameter documentation.

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

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

The description clearly states the verb 'List' and the resource 'projects for the business', distinguishing it from sibling tools like freshbooks_get_project. The explicit mention of 'Uses businessId (not accountId)' further differentiates it from other list tools that might rely on accountId, making the purpose 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?

It provides a clear guideline on which identifier to use (businessId not accountId) and notes the tool works even without an accounting account, giving context for when it's appropriate. However, it does not explicitly contrast with alternatives like list_services, though the ID distinction is a key usage clue.

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

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

Annotations only declare readOnlyHint=true; the description adds real value by stating the return shape ('items plus page/pages/total') and the plan/account-role gating behavior that can suppress rows. This goes beyond the structured annotation and gives an agent useful expectations about what a successful or constrained response looks like.

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

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

Two dense, information-carrying sentences with no filler. The first establishes scope and positioning against siblings; the second covers output shape and access gating. Every clause earns its place.

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

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

For a generic read tool with no output schema, this description covers the resource scope, return fields, pagination presence, and plan/role limitations. The enum and sibling names fill in the remaining context, so an agent has enough to select and invoke the 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 resource parameter is already well covered by the enum and schema description, and the search parameter is described in the schema. The description adds little for page and per_page, though the return-note about page/pages/total hints at pagination semantics. With 50% schema coverage, the description is adequate but does not substantially compensate for the undocumented pagination parameters.

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 ('List'), a clear resource domain ('FreshBooks accounting resource by name'), and positions the tool as the generic reader for the long tail. It also names concrete resources and explicitly contrasts itself with dedicated sibling tools, so an agent can distinguish it without opening the schema.

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

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

The description clarifies that this is the generic reader covering long-tail resources while dedicated tools also exist, which strongly implies when to reach for it. It stops short of explicitly saying 'use the dedicated list tool for invoices/clients/etc.' or naming freshbooks_get_record as the singular alternative, so it gives clear context but not a full when/when-not 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=true, so the agent knows this is a safe read operation. The description adds the domain context that services are billable work types, which is useful. However, it doesn't disclose pagination behavior, default page size, or whether the list is ordered, but the read-only safety is covered by 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?

The description is a single, compact sentence that front-loads the verb and resource, then adds a clarifying parenthetical. Every word earns its place; there is no fluff or repetition.

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

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

For a simple read-only list tool with two optional pagination parameters and no output schema, the description is mostly adequate. The main gap is that it doesn't mention pagination behavior or defaults, but the parameter names and annotations cover the essential safety and scope. An agent can likely call this tool correctly with the current information.

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 for parameter meaning. The description does not explain 'page' or 'per_page' beyond what the schema types imply. However, the parameter names are self-explanatory for pagination, and the schema provides constraints (exclusiveMinimum, maximum for per_page). The description adds no semantic value 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 ('List') and resource ('services'), and clarifies what services are ('billable work types available to projects and time entries'). This distinguishes it from sibling list tools like freshbooks_list_invoices or freshbooks_list_clients, though it doesn't explicitly name a sibling alternative.

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

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

The description implies usage context by defining services as billable work types for projects and time entries, which helps an agent know when this tool is relevant. However, it provides no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of pagination usage.

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 annotation readOnlyHint=true already covers the non-destructive nature. The description adds value by disclosing that the response envelope includes total_logged and total_unbilled, which is useful behavioral context about the return shape. This is comparable to the get_calls example where the description added scoping context beyond 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?

The description is two concise sentences with no filler. The primary action is front-loaded, and the extra response envelope detail is added without bloat. It is well-structured and efficient.

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

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

There is no output schema, so the description must explain return values. It mentions total_logged and total_unbilled but does not describe the row structure, pagination behavior, or any edge cases. For a simple list tool this is adequate but leaves gaps, so a 3 is appropriate.

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

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

Schema description coverage is 0%, and the description does not mention the page or per_page parameters at all. Since the schema provides only basic integer constraints and no descriptions, the tool description completely fails to compensate for this gap, leaving agents without any explanation of how pagination works.

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

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

The description clearly states the verb 'List' and the resource 'tracked time entries', which is specific enough to distinguish it from other list tools like freshbooks_list_expenses. However, it does not explicitly differentiate itself from sibling list tools by name or contrast, 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?

No guidance is provided on when to use this tool versus alternatives such as freshbooks_list_records or freshbooks_list_expenses. There is no mention of typical use cases, filtering, or exclusions, so an agent gets no help in choosing this tool over others.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explicitly states that confirm: true is required to execute and that without it, the tool returns a dry-run preview and makes no network call. This is a significant and useful disclosure about the tool's safety and execution model. However, it does not describe the post-confirmation behavior (e.g., irreversible changes, return format), so it's not fully transparent.

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

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

The description is two sentences with zero fluff. It front-loads the purpose and then immediately covers the critical confirm mechanism. Every word earns its place, making it highly efficient for an agent to parse.

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

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

Given that this is a mutation tool with no output schema and no annotations, the description is adequate but incomplete. It does not mention what the tool returns upon successful confirmation, nor any constraints (e.g., invoice status, permissions). The confirm/dry-run behavior is well explained, but the absence of return-value details and prerequisite conditions leaves some gaps for the agent.

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 schema already provides high coverage (83%) of parameter meanings, including descriptions for confirm, invoiceid, and amount fields. The description adds no additional parameter semantics beyond what the schema offers—it merely repeats the confirm behavior. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Record') and a specific resource ('a payment against an invoice'), which clearly distinguishes this from sibling read-only tools like list_payments or get_payment. It unambiguously conveys the tool's core function without ambiguity.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It only notes the confirm flag requirement, which is more of a behavioral detail than usage guidance. The agent is left to infer when this tool is appropriate.

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, it discloses the confirm gate, the no-network-call dry-run behavior, the client-address default, and the guardrail that allow_non_client_recipients is only for user-named addresses. This is substantial additional transparency about side effects and execution 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?

Four dense sentences front-load the core action and confirmation requirement, then cover recipient behavior and return value. The inline JSON snippet adds technical precision but is slightly verbose; still, every sentence earns its place without fluff.

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

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

For a 6-parameter mutation with no output schema, the description covers all critical decisions: how to execute, dry-run behavior, recipient eligibility, special-case guardrails, and the return value. Nothing an agent needs to call it correctly is missing, and it compensates well for the lack of an output 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?

Although the schema already has 100% coverage, the description adds decisive meaning to the most important parameters: confirm controls execution vs preview, email_recipients omission selects the client address, and allow_non_client_recipients is restricted to explicit user intent. This clarifies parameter interactions 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 the specific action (email an estimate to the client) and the underlying API operation (action_email), clearly distinguishing it from siblings like accept_estimate, decline_estimate, or update_estimate. The verb+resource combination makes the tool's purpose unmistakable.

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

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

Provides rich operational guidance: requires confirm:true to actually send, explains dry-run behavior without it, and details recipient defaulting and validation rules. It does not explicitly name alternative tools, but the context is strong enough to infer when this tool is appropriate.

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

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

No annotations are provided, so the description carries full responsibility. It discloses the partial-update behavior (only supplied fields sent), the confirm/dry-run mechanism, the lines replacement rule, and the return of the re-fetched estimate. This is thorough and leaves no major behavioral surprises.

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 concise sentences, each serving a distinct purpose: purpose + partial update, confirm/dry-run, and lines replacement + return value. No filler, front-loaded with the most important constraints. Excellent structure.

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

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

Given the tool's complexity (14 parameters, nested objects, no output schema), the description covers the essential behaviors: partial update, confirm requirement, lines replacement, and return value. It does not enumerate every parameter, but the schema covers those. It omits error handling or permission requirements, but these are not standard for tool descriptions. Overall, adequate for correct invocation.

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

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

Schema description coverage is 93%, so the schema already documents most parameters. The description adds critical semantic value for the 'lines' parameter (full replacement, include lineid to update) and the 'confirm' parameter (dry-run vs execute), which are not fully clear from the schema alone. This goes beyond the baseline.

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

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

The description states a clear verb ('update') and resource ('existing estimate'), and distinguishes itself from sibling tools like create, accept, decline, and send by focusing on updating an already-existing estimate. It also adds the partial-update behavior, which is a specific differentiator.

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 clearly explains when to use the tool (updating an existing estimate) and provides critical usage conditions: the confirm flag is required for execution, without it only a dry-run preview occurs, and lines replacement semantics. It doesn't explicitly name alternatives or exclusions, but the purpose is unambiguous given the sibling set.

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, the description discloses critical behavioral details: dry-run mode with no network call, the side effect that changing an invoice out of draft can email the client, and the email_recipients validation rule. These are exactly the kinds of non-obvious behaviors an agent needs to know before invoking a mutating tool.

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

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

Every sentence earns its place: purpose first, then partial-update behavior, then confirm/dry-run mechanics, then the email side effect, then the recipient constraint. There is no wasted wording, and the most important operational facts are front-loaded.

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

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

The description covers the invocation essentials and side effects comprehensively for a tool with no output schema. It does not describe what a successful update returns, but the dry-run preview, confirm requirement, and recipient rules give enough to call it correctly. A brief mention of the success return shape would make it fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that fields is a partial update set, explains the behavior of confirm, and adds nuance to allow_non_client_recipients ('only for addresses the user named themselves'). This elevates the parameter understanding beyond bare property descriptions.

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 'Update an existing invoice', a specific verb plus resource that makes the core purpose immediately clear. It does not explicitly differentiate from sibling tools like freshbooks_update_estimate, but the tool name and invoice reference make the target 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 provides strong context: it explains the partial-update behavior ('Only the supplied fields are sent'), the confirm flag requirement ('Requires confirm: true to execute'), and the dry-run alternative ('without it returns a dry-run preview and makes no network call'). It does not explicitly mention alternatives or when-not-to-use cases, but the guidance given is clear and actionable.

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