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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently covers irreversibility, the confirm gate, dry-run behavior, idempotency for already-accepted or invoiced estimates, changed: false, and the re-fetched estimate return. This is exemplary for 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?

Three compact sentences front-load the action and then add only high-value behavioral details. Every clause earns its place, covering mechanism, side effects, confirmation requirement, idempotency, and return value without 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?

Despite having no annotations and no output schema, the description fully covers the critical call-time behaviors an agent needs: irreversible action, confirm requirement, dry-run behavior, idempotent handling, and return value. Nothing essential to calling this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining that confirm must be true to execute and that omitting it yields a preview, and by showing id used in the request path.

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 accepts an estimate and identifies the exact FreshBooks API action, action_accept, sent via PUT. The explicit 'accept' verb and action payload make it distinct from sibling operations like decline, send, 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?

It gives clear operational context: acceptance is irreversible, confirm must be true to execute, and without confirm it is only a dry-run preview with no network call. It does not explicitly name alternatives or exclusion conditions, but the acceptance use case is unambiguous.

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

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

Annotations already mark the tool as readOnlyHint=false and idempotentHint=false. The description adds a crucial behavioral detail beyond those flags: the code is single-use, so a failed exchange cannot be safely retried and requires a new authorization code. This significantly helps an agent avoid a wasted or erroneous retry.

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 filler: sentence one states the purpose, sentence two covers accepted input and the critical single-use constraint. The most important warning is placed at the end but is compact and clear.

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 OAuth exchange tool, the description covers the action, the input flexibility, the failure mode, and the remedy. No output schema exists, but the outcome is explicitly named (a refresh token), so an agent has enough context 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?

Schema description coverage is 100%; the parameter schema already explains that code is 'The ?code= value, or the entire redirect URL you were sent to after approving.' The tool description repeats this almost verbatim ('Accepts the whole redirect URL you landed on, or the bare code'), so it adds no new 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 and resource: 'Exchange a FreshBooks authorization code for a refresh token.' It clearly distinguishes this tool from the sibling freshbooks_auth_url by naming it as the source of a new code when the exchange fails, making the tool's role in the OAuth flow obvious.

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 explicit failure-handling guidance: the authorization code is SINGLE-USE, so do not retry; instead obtain a new code from freshbooks_auth_url. This tells the agent both when to use this tool and when to switch to the alternative.

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

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

The description adds 'Read-only; contacts nothing' beyond the annotations, clarifying that generating the URL has no external side effects. It also explains what happens after the user opens the URL (approval, redirect), which annotates are absent. This is valuable behavioral context that annotations alone do not provide.

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 wasted words. The first sentence front-loads the action and purpose, and the second efficiently directs the user to the next tool. Every phrase earns its place, and the description is not bloated despite including a mini flow explanation.

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 fully covers the tool's role in the auth flow, the next sibling to call, and the safe read-only nature. Since there is no output schema, it could have described the return value (the consent URL) more explicitly, but 'Open it' strongly implies a URL is returned. Overall, the information is sufficient for a human or agent to use this tool correctly.

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

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

With zero parameters, the schema already fully covers the input requirements. The baseline for 0 params is 4, and the description adds no unnecessary param detail; it naturally fits the no-input nature of the tool. No additional param semantics are needed.

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

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

The description uses a specific verb and resource ('Get the FreshBooks consent URL') and clearly states the purpose ('to authorise this connection'). It also distinguishes itself from sibling freshbooks_auth_exchange by specifying that the capture URL is the first step and the exchange is the follow-up, making the tool's role 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 gives clear usage context: open the consent URL, approve, land on redirect, then pass it to freshbooks_auth_exchange. This explicitly names the relevant sibling and explains the flow. It stops short of stating exclusions or alternative conditions, but for a 0-parameter auth-URL generator, the guidance is clear enough.

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?

Discloses a non-obvious behavioral trait: the tool will not execute without confirm: true and returns a dry-run preview with no network call. Since no annotations exist, this is valuable transparency about the execution model, though it could also mention return values or error 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?

Two short sentences that immediately state the purpose and the critical precondition. No filler or redundant content.

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

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

The description explains core behavior and the confirm flag, but with no output schema it does not mention return values or what the dry-run preview contains. The nested fields parameter and error handling are left entirely to the schema, leaving some context gaps.

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

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

The input schema covers all 7 parameters with descriptions, and the tool description adds no additional parameter semantics. Baseline 3 applies because schema coverage is 100%.

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 a client (customer) in FreshBooks, using a specific verb and resource. The parenthetical '(customer)' adds clarity, and it naturally distinguishes from sibling list/get 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 provides the critical usage rule that confirm: true is required to execute and that without it a dry-run preview is returned. However, it does not explicitly compare to alternative tools or state when not to use it, so guidance beyond the confirm flag is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the dry-run preview behavior and that no network call is made without confirm: true, which is valuable context. However, it omits other behavioral traits such as permissions, error handling, and success return format.

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, front-loaded with the purpose, and includes only essential information about the confirm behavior. No unnecessary words 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?

The tool has 9 parameters and a nested amount object, but the description does not explain what a successful execution returns or what the preview contains. Since there is no output schema, the agent is left without guidance on interpreting results, making the description incomplete for this complexity.

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

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

Schema description coverage is 89%, so the schema already provides parameter meanings. The description adds no parameter semantics beyond restating the confirm requirement, which is also 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?

The description clearly states the action ('Record') and the resource ('an expense'), making it distinct from sibling tools like freshbooks_get_expense or freshbooks_list_expenses. The first sentence immediately conveys the core purpose 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 implies usage for recording expenses and explains the confirm requirement, but it does not explicitly contrast with alternatives or provide guidance on when to use this tool vs. siblings. No exclusions or alternative tool recommendations are given.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating that created invoices start as drafts, that confirm:true is required to execute, and that omitting it produces a dry-run preview with no network call. It stops short of describing the preview's content or whether execution is idempotent.

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

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

Three short sentences, each carrying essential information: the action, the lifecycle outcome, and the safety/confirmation behavior. 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?

For an 8-parameter tool with nested objects and no output schema, the description captures the critical safety behavior but omits what the successful response or preview contains. The agent can still operate because confirm:false provides a safe preview, but return-value expectations are left implicit.

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

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

Schema description coverage is 88%, so the parameters are already well documented. The tool description does not add meaning beyond the schema; it restates the confirm behavior that the schema already describes. This meets the baseline but does not exceed it.

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

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

The description clearly states the verb ('Create'), the resource ('an invoice'), and the target ('for a client'). It is unambiguous and distinct from sibling tools like freshbooks_update_invoice or freshbooks_create_client.

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 the tool should be used ('Create an invoice') and explains the confirmation requirement, but it does not explicitly contrast this with alternatives such as freshbooks_update_invoice or mention when not to use it. Usage is mostly inferred from the tool name and first sentence.

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 full responsibility for behavioral disclosure. It discloses the critical two-phase behavior (dry-run vs. actual creation) and explicitly states that a network call is only made when confirm is true. This goes beyond the schema and gives important safety-relevant information. It doesn't mention return format or error handling, but the key behavioral trait is well covered.

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

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

The description is two short sentences, front-loads the core action, and then adds the critical execution caveat. 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?

Given the 9-parameter schema with detailed descriptions, the description only needs to add the non-obvious confirm/dry-run behavior, which it does. It also clearly states the tool's purpose. It doesn't explain return values (no output schema exists), but the absence of an output schema is a minor gap; the essential context for using the tool safely and correctly is present.

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

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

Schema description coverage is 89%, so most parameters are already well documented (rate, project_type, client_id, etc.). The description adds no new parameter-level information; its mention of confirm echoes the schema description. Per the rubric, with high schema coverage, the baseline is 3, and the description does not add value.

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 'Create a project.' which is a specific verb+resource statement. It clearly distinguishes itself from sibling tools that perform other operations (get/list/create for estimates, invoices, clients, etc.). No ambiguity about 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 essential usage context: it explains that confirm must be true to execute, otherwise it returns a dry-run preview and makes no network call. This tells the agent when to set confirm. While it doesn't explicitly name alternatives, siblings are obviously for other resources, so the primary use case is clear.

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

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

With no annotations, the description carries the burden and does well by disclosing the dry-run preview and no network call without confirm. It also highlights the SECONDS unit for duration. It does not cover other behavioral aspects like permissions or result format, but the most critical behavior is disclosed.

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, front-loads the main purpose, and packs the key execution detail (confirm) and unit (seconds) without any waste. 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?

The description covers the essential behavior (dry-run vs. execute) but omits any guidance on the many optional parameters (client, project, service, billable, note). Given the tool's 8 parameters and lack of output schema, more context would help, but the core flow is understandable.

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%, and the description only amplifies that duration is in seconds and confirm is required for execution. It does not add meaning for the other five undocumented parameters (note, billable, client_id, project_id, service_id), so it fails to compensate for the low 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 clearly states the tool's function with a specific verb ('Log') and resource ('a time entry'). This distinguishes it from siblings like freshbooks_list_time_entries, making the purpose immediately 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 provides explicit usage context by explaining the confirm requirement and dry-run behavior. However, it does not mention when to use this tool versus other create tools or list time entries, so it lacks explicit alternatives or exclusions.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool always fails, never sends a request, exists only to return a reason, and explains the underlying API limitations. This is model transparency for a deliberately non-functional 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?

The description is front-loaded with the most critical information—'NOT SUPPORTED' and 'always fails'—and every sentence contributes. The middle sentence is somewhat detailed and lengthy, but it substantiates why the tool cannot work, making the verbosity justified.

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 that always fails and has no output schema, the description is complete: it states behavior, the API reason, the purpose, and the intended action. An agent understands exactly what will happen and what the tool is for. Missing return-format details are irrelevant because the tool never succeeds.

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

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

The single parameter `id` is fully documented in the schema as 'Estimate id' with 100% coverage, so the description does not need to add param details. It does imply the id is ignored because no request is ever sent, but this is behavioral rather than semantic parameter documentation. 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 is explicit that this tool is NOT SUPPORTED, always fails, and never sends a request. It clearly explains the tool's actual purpose—returning the reason and alternatives rather than performing a decline—and distinguishes it from a real operation by citing the missing declined state and action_deny counterpart.

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 makes it clear the tool cannot perform a decline and says to 'call it to get the alternatives,' which implies usage but does not explicitly name the alternative tools or state when to prefer them. It gives context for when it might be invoked but lacks explicit when-to-use vs when-not-to-use 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?

The readOnlyHint annotation already indicates this is a safe read operation, and the description is consistent with it ('Get'). However, the description adds no additional behavioral context such as error handling, rate limits, or authentication requirements. With annotations covering the primary behavior, a score of 3 is appropriate.

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

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

The description is a single, concise sentence that is front-loaded with the action and resource. It contains no unnecessary words 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 get-by-ID tool, the description, combined with the readOnly annotation and schema, is largely complete. It could mention that it returns the client object, but that is commonly understood for a 'get' operation. The absence of an output schema is not a significant gap 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?

The schema already describes the 'id' parameter as 'The client id' with full coverage (100%). The description's mention of 'numeric FreshBooks id' adds no new meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Get') and the resource ('a single client') with a specific qualifier ('by its numeric FreshBooks id'). This distinguishes it from sibling tools like list_clients or create_client, 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?

The description implies usage when you need a single client by ID, but it does not explicitly mention when to use this tool versus alternatives like list_clients or get_estimate. There is no explicit guidance on exclusions or alternative scenarios.

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 is true, and the description aligns with a read-only operation. The description adds no additional behavioral context beyond what the annotation provides (e.g., no mention of errors, auth, or return format). Since annotations already cover the safety profile, the bar is lower, and the description is acceptable but adds no extra transparency.

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 directly states the action and target. There is no filler or redundant phrasing; every word contributes to clarity.

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?

This is a simple getter tool with one parameter, a readOnly annotation, and no output schema. The description sufficiently communicates the operation and expected result (the estimate object). Given the low complexity and full schema coverage, no additional detail is necessary.

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 only parameter 'id' with type integer and a description. The description's phrase 'numeric' merely restates the integer type and adds no new meaning. With 100% schema coverage, the 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 uses a specific verb ('Get') and clearly identifies the resource ('single estimate') and the exact scope ('by its numeric FreshBooks id'). It effectively distinguishes this tool from sibling tools like freshbooks_list_estimates, which would retrieve multiple estimates.

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 context is clear: this tool should be used when a specific estimate is needed by its ID. While it does not explicitly name alternative tools (e.g., list_estimates), the phrase 'single estimate' implies that contrast. There are no explicit exclusions or conditions, but the intended usage is unambiguous.

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

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

The description is consistent with the readOnlyHint annotation, and adds no behavioral context beyond 'get' (e.g., no mention of return format, error handling, or absence of side effects). Since annotations already declare read-only status, the description doesn't need to repeat it, but it also doesn't add extra behavioral nuance.

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 short sentence that is front-loaded with the main action and resource. No wasted words; every element serves a purpose.

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 get-by-id tool with one parameter, the description is adequate. It states the operation and the identifying requirement. Given there is no output schema, a short note about the return value could be useful, but the purpose is sufficiently clear.

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 covers 100% of the parameter semantics with type 'integer' and description 'Expense id'. The description's 'numeric id' adds no new meaning beyond the schema. 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 uses a specific verb ('Get') with a specific resource ('expense') and clearly scopes it to a single entity identified by numeric id. This distinguishes it from sibling tools like list_expenses or 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?

The description implies usage when the caller has a specific expense id and needs that one expense. It doesn't explicitly mention alternatives like list_expenses for multiple records, but the 'single' vs. list distinction is implicitly clear among sibling tools.

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

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

The readOnlyHint annotation already indicates the tool is read-only. The description adds context about the output types (alphanumeric vs integer) and the critical behavior that using the wrong identifier yields a 404 instead of a useful error. This is valuable beyond annotations, though it could also mention pagination or response shape if applicable.

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 fluff. The first sentence states purpose and lists identifiers with their types and usages; the second is a practical warning. 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?

Given no parameters, a read-only annotation, and no output schema, the description fully covers what an agent needs to know: what is returned, the type/usage of each identifier, and a caution about swapping them. No vital context 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 zero parameters, so the description carries no parameter burden. The baseline for 0-parameter tools is 4, and the description correctly focuses on output semantics instead.

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 resolves the authenticated user and lists the exact identifiers returned (accountId, businessId, businessUuid). It distinguishes itself from sibling tools, which all operate on specific FreshBooks resources, making it unique as an identity/metadata endpoint.

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

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

The description provides implicit usage guidance by explaining which identifiers belong to which API areas (accounting/payments vs projects/time tracking). It doesn't explicitly say 'call this first' but strongly implies it, and the 404 warning helps avoid misusing the returned IDs in other endpoints.

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 this is a safe read operation. The description adds minimal behavioral context beyond the tool's purpose (single invoice by numeric id), which is largely already conveyed by the name and schema. No mention of error handling, rate limits, or 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?

The description is a single, concise sentence that front-loads the verb and resource. Every word contributes to clarity, with no redundancy or filler.

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

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

For a simple single-get tool with one fully documented parameter and a readOnlyHint annotation, the description adequately covers all necessary context. The expected return (the invoice) is implied by the tool name and description, and no further details are essential.

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 for the single parameter is 100%, with the schema describing 'id' as 'The invoice id' and integer type. The description's 'numeric FreshBooks id' does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the resource ('a single invoice'), and how it is identified ('by its numeric FreshBooks id'). This distinguishes it from sibling tools like freshbooks_list_invoices or other get_* 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 implies the clear use case: retrieving a specific invoice when you have its numeric id. It does not explicitly mention when not to use it or alternatives like listing invoices, but the context is unambiguous.

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

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

The readOnlyHint annotation already declares this as a safe read operation. The description adds the detail of 'numeric FreshBooks id' but does not disclose other behavioral aspects like errors, permissions, or response format. It does not contradict annotations, and 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?

The description is a single, concise sentence that is front-loaded with the key purpose. It contains no extraneous words.

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 getter with one parameter and no output schema, the description adequately conveys the tool's effect. It could mention what fields are returned, but the purpose is clear enough given the sibling context and the general behavior of 'get' operations.

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% with the 'id' parameter described as 'The item id'. The description adds 'numeric FreshBooks id', which reinforces the integer type but does not provide additional meaning beyond what the schema already states.

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 (Get), the resource (a single item), and the identifier type (numeric FreshBooks id). It distinguishes itself from siblings like freshbooks_list_items, which retrieves multiple items.

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 a specific item is needed by id, but it does not explicitly state when to prefer this over freshbooks_list_items or other getters. No alternatives or exclusions are mentioned, leaving the agent to infer 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 signals a safe read operation. The description adds the 'single' and 'numeric id' qualifier, which is mild additional context but not a rich behavioral disclosure like error conditions or response format.

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, concise sentence that front-loads the verb and object. Every word earns its place; no filler or unnecessary detail.

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

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

For a simple get-by-id tool with one parameter and a readOnly annotation, the description fully covers the essential context. No output schema is needed for such a straightforward operation.

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

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

The schema covers the single parameter fully ('The payment id' with integer type). The description's 'numeric FreshBooks id' reinforces but does not add meaningful new semantics 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 clearly states the action ('Get'), the resource ('a single payment'), and the identifier ('by its numeric FreshBooks id'). This precisely differentiates from siblings like freshbooks_list_payments (list vs. single) and freshbooks_record_payment (get vs. create).

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 payment' clearly implies the use case of retrieving one specific payment when its id is known. While it doesn't explicitly name alternatives, the context is unambiguous and contrasts with list operations.

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 nature is covered. The description adds the 'single' and 'numeric id' context but does not disclose additional behavioral traits such as error handling or response format. This is acceptable given the annotation coverage.

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

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

One sentence with no wasted words; the essential information is front-loaded and immediately accessible.

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 get-by-id tool with full schema coverage and readOnlyHint annotation, the description is sufficient. No missing context would hinder invocation or selection.

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 describes the only parameter ('id' as Project id with integer type), so the description adds no new parameter semantics beyond reinforcing that the ID is numeric. With 100% schema coverage, the baseline of 3 applies.

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

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

The description uses a specific verb ('Get'), resource ('project'), and scope ('single by numeric id'), clearly distinguishing it from list and create operations. The purpose is immediately obvious.

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 have a project's numeric ID and need a single record, providing clear context. However, it does not explicitly mention alternatives like list_projects or create_project, so it falls short of explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context about id handling: numeric ids are the norm and string ids are accepted as text. This goes beyond the schema by explaining why strings are allowed, which helps agents avoid conversion errors. No contradiction with 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 exactly two sentences, front-loaded with the main action. Every clause contributes meaning: the scope (any resource), the identification method (name and id), and the id type nuance. No filler or 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 simple read tool, the description is mostly adequate, but it misses the relationship to the numerous sibling getter tools. Without usage guidance, an agent might not know whether to pick this generic tool or a dedicated one. The output schema is absent, but the description is not expected to detail returns. The gap in usage context lowers completeness.

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

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

Schema description coverage is 100%, with both parameters described. The description's note about numeric ids and string acceptance largely restates the schema's anyOf definition, adding only a brief rationale. It does not explain the resource enum values or the 'alphanumeric accountId' remark, so it contributes little 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 clearly states the tool's function: 'Get a single record from any FreshBooks accounting resource by name and id.' The verb and resource are specific, and the 'any resource' scope distinguishes it from the sibling-specific getters, though it does not explicitly say it's a fallback for resources without a dedicated getter.

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 offers no guidance on when to use this generic getter versus the many resource-specific getter tools listed as siblings (e.g., freshbooks_get_invoice, freshbooks_get_client). There is no mention of preferred alternatives or conditions like 'use only for resources without a dedicated getter.'

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?

Even though annotations already mark readOnlyHint, idempotentHint, and openWorldHint, the description adds valuable behavioral details: it reports the credential source, acceptance status, round-trip time, and a plain-English failure-mode hint. It also explicitly promises 'never returns the credential itself,' which is important safety context beyond the annotations.

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

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

The description is moderately long but every sentence earns its place: mechanism, outputs, usage trigger, and safety guarantee. It is front-loaded with the core behavior and avoids filler, though the final sentence could be viewed as slightly repetitive with 'Read-only'.

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 no output schema, the description is complete: it explains what the tool does, what it returns (source, acceptance, RTT, hint), when to use it, and a key safety property. An agent has all the information needed to invoke and interpret the call.

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

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

The input schema has zero parameters, so there is nothing to document. The description explains that the tool resolves credentials internally, which is sufficient. The 0-parameter baseline of 4 applies here.

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 ('Resolves the credential... makes one authenticated request to api.freshbooks.com') and a clear diagnostic resource. It is unmistakably distinct from sibling CRUD/auth tools because it focuses on credential validation and upstream reachability, not on Fetching or mutating data.

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 explicitly states when to use the tool: 'Call this when a real tool fails and you want to know which hop broke.' This provides clear contextual guidance, though it does not explicitly list exclusions or sibling alternatives. The trigger condition is precise enough for an agent to select it over other tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavior: pagination support, raw FreshBooks filter params passed through, and a return summary of items plus page/pages/total. This goes beyond the annotation without contradicting it.

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

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

Two sentences with no filler. The core action and resource are front-loaded, followed by terse but useful feature statements about pagination, filters, and return shape.

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 no required parameters and full schema coverage, the description plus readOnly annotation provide a solid picture. It names the return fields, but does not cover default pagination values or error behavior, so a 5 is not warranted.

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

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

Schema description coverage is 100%, and each parameter already has detailed documentation, especially 'search' with an example and 'per_page' with a max. The description only briefly mentions pagination and raw filters, adding little 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 uses a specific verb ('List') and resource ('clients') scoped to the authenticated FreshBooks account. It is clearly distinguishable from siblings like freshbooks_get_client for fetching a single client and freshbooks_create_client for creating one.

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 a list operation and mentions pagination and filters, but it does not explicitly state when to use this tool versus freshbooks_get_client or freshbooks_create_client. Usage context is present but no alternatives or exclusions are given.

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

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

Annotations declare readOnlyHint=true, and the description adds useful behavioral context: it supports pagination, passes raw FreshBooks filter params verbatim, and returns page/pages/total alongside items. This goes beyond the annotation without contradicting it.

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

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

Two sentences contain all essential information with no filler. The core purpose is front-loaded, followed by the two key capabilities (pagination and raw filters) and the return shape.

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 a read-only annotation and fully described parameters, the description covers scope, pagination, filtering behavior, and the top-level return shape. With no output schema, 'items' could be slightly more explicit as an array of estimate objects, but overall an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents page, search, and per_page. The description adds a high-level mention of pagination and raw filter params but no parameter-level detail beyond what the schema provides. 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 verb 'List' and resource 'estimates' are specific, and 'for the authenticated FreshBooks account' defines scope. It is immediately distinguishable from the sibling freshbooks_get_estimate (single-item fetch) and the other list_* tools by resource type.

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

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

The description implies when to use it: to list estimates, optionally paginating or filtering. However, it does not explicitly contrast with freshbooks_get_estimate or mention cases where a different tool would be more appropriate, leaving the routing to inference.

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

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

The readOnlyHint annotation already signals this is a safe read operation. The description adds the useful detail that it supplies categoryid for expense creation, but does not disclose other behavioral aspects such as pagination behavior, return format, or any limitations. With annotations covering safety, this meets the minimum but lacks rich context.

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

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

The description is a single, efficient sentence that front-loads the primary purpose and adds a key contextual note. Every word earns its place, and there is 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 simple read-only list tool with optional pagination, the description covers the essential purpose and the relationship to expense creation. However, with no output schema, it would benefit from noting what fields are returned or pagination defaults. It is minimally adequate but leaves room for improvement.

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

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

Schema description coverage is 0% for the two parameters (page and per_page), and the description does not mention them at all. Since the schema provides only names and types, the description fails to compensate by clarifying parameter usage or defaults, leaving the agent with no additional semantic guidance.

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

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

The description clearly states the tool's specific action ('List expense categories') and identifies the resource. It also differentiates this from sibling tools like freshbooks_list_expenses by noting these categories supply the categoryid for expense creation, making its role 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 clear contextual guidance: it is used to obtain categoryid values for creating expenses. It does not explicitly mention exclusions or alternatives (e.g., when to use list_expenses instead), but the context is strong enough for an agent to infer the appropriate scenario.

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 adds meaningful behavioral details: default ordering, pagination support, raw filter syntax, and a subtle edge case where a total may include records the identity cannot read, surfaced via the note field. This is valuable transparency.

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 focused sentences. The first states the core purpose and ordering; the second covers pagination, filters, and an important caveat. 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 read-only list operation with three optional parameters and no output schema, the description covers the key behaviors: ordering, filters, pagination, and the unreadable-count caveat. It is slightly incomplete in not detailing page/per_page semantics or naming alternatives, but it is largely sufficient.

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

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

The schema has 0% description coverage, so the description must compensate. It mentions 'pagination' and gives an example of a raw filter, but it does not explain the individual page or per_page properties, their defaults, or how they interact. This is only partial compensation.

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 expenses for the account') and adds ordering ('newest-first by default'). It clearly distinguishes this from sibling tools like get_expense or create_expense by framing it as a list 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 provides context but gives no explicit guidance on when to choose this tool over alternatives such as get_expense or create_expense. There is no mention of when not to use it or what conditions favor a sibling tool, leaving the agent to infer 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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds valuable behavioral detail beyond the annotation: pagination is supported, raw FreshBooks filter params are passed through verbatim, and the response contains items plus page/pages/total. This helps the agent understand the return envelope and filter behavior without an output schema.

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

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

Three concise sentences, each earning its place: what the tool lists, how pagination/filtering behaves, and what the return envelope contains. No fluff or repetition of schema details.

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 paginated list operation with no required parameters and no output schema, the description covers scope, pagination, filtering, and the top-level response shape. It is complete enough for an agent to call correctly, though it could further detail default pagination behavior or the structure of each invoice item.

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 explains page, search, and per_page well. The description only reinforces that pagination and raw filter params exist without adding meaningful semantic details beyond the schema.

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

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

States a specific action ('List') and resource ('invoices') for the authenticated FreshBooks account, clearly distinguishing it from single-invoice retrieval (freshbooks_get_invoice) and mutation tools like freshbooks_create_invoice or freshbooks_update_invoice. The scope is unambiguous.

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

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

The description implies this is the tool for retrieving multiple invoices rather than a single one, and it mentions pagination/filter support, which signals common list-operation usage. However, it does not explicitly state when to prefer this over freshbooks_get_invoice or any other sibling, nor does it mention exclusions like 'use get_invoice for a specific invoice ID.'

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

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

Annotations already declare readOnlyHint=true and the description agrees by using 'List.' The description adds useful behavioral context beyond annotations by disclosing pagination support and the high-level response shape ('items plus page/pages/total'). No safety-relevant behavior is hidden.

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

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

Three short sentences, front-loaded with the core purpose and no filler. Each sentence contributes either the action, the capabilities, or the return shape.

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 fully documented parameters, the description covers authentication scope, pagination, filter capability, and the top-level return shape in the absence of an output schema. It could go further by describing the item object shape, but the essentials are present.

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

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

Schema description coverage is 100%, and the description does not add meaning beyond it: pagination and raw FreshBooks filter params are already spelled out for page, per_page, and search. It correctly signals the three parameters exist but adds no new semantic detail.

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

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

The description opens with a specific verb and resource—'List items for the authenticated FreshBooks account'—so an agent knows exactly what operation this exposes. It does not explicitly differentiate from siblings like freshbooks_get_item, though the list-vs-get distinction is reasonably inferable from tool names.

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 is the list-all/query endpoint with pagination and raw filter passthrough, so its use case is implied. However, it never names alternatives or exclusion criteria, such as using freshbooks_get_item when a single item is needed.

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 indicate readOnlyHint=true, so the safe-read profile is covered. The description adds useful behavioral context: it supports pagination, passes raw FreshBooks filters verbatim, and returns items plus page/pages/total—details not encoded in the annotations.

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

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

Two sentences with no filler. The core action is front-loaded, and the second sentence efficiently covers pagination, filter passthrough, and the return shape.

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 correctly provides a minimal return contract ('items plus page/pages/total'). The parameters are fully documented in the schema, and the read-only nature is covered by annotations. It lacks error-case or default-pagination detail, but for a list tool this is not a major gap.

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

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

Schema description coverage is 100%, so the schema already documents page, per_page, and search well. The description's mention of pagination and raw filter params mirrors the schema without adding new meaning; it stays at the baseline because no additional parameter nuance is provided.

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 ('List') and resource ('payments') and scopes it to the authenticated FreshBooks account. It distinguishes well from siblings like freshbooks_get_payment (single item) and freshbooks_record_payment (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 implies listing usage with pagination and raw filter params, but it does not explicitly state when to choose this over freshbooks_get_payment or mention any exclusions. The verb and context make the primary use clear, but no direct alternative guidance is given.

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

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

The readOnlyHint annotation already indicates a safe read operation. The description adds valuable context about businessId vs accountId and the tool's behavior without an accounting account. However, it does not disclose pagination behavior, response format, or other non-obvious traits, so it partially extends beyond annotations but leaves gaps.

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, front-loaded with the core action ('List projects for the business'), and adds a useful caveat without any fluff. Every phrase earns its place, making it concise and well-structured.

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

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

For a simple list tool with pagination parameters and no output schema, the description covers the essential purpose and a key behavioral nuance. However, it omits any mention of what a successful response contains (list of projects) and does not clarify pagination defaults or limits, leaving some context incomplete given no 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?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It fails to mention 'page' or 'per_page' entirely; the only parameter-like reference is businessId, which is not in the schema. The description provides no semantic value for the actual parameters, leaving pagination details undocumented.

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's function: 'List projects for the business.' This is a specific verb+resource pair that distinguishes it from sibling tools like freshbooks_get_project (retrieve a single project) and freshbooks_create_project (create a project). The additional note about businessId reinforces the 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 provides some usage context: 'Uses businessId (not accountId)' and 'works even when the business has no accounting account.' This implies a scenario where the tool is especially useful, but it does not explicitly compare with alternatives or state when not to use it. No exclusion or alternative tool names are mentioned, so guidance is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=true, so the description carries additional useful context: it discloses the return shape ('items plus page/pages/total') and notes that some resources are gated by plan or role and 'will report that rather than returning rows.' This is meaningful behavioral information beyond the structured 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 only two sentences and gets the core purpose, scope, return shape, and access-gating caveat out quickly. The first sentence is long with a parenthetical enumeration, but every phrase carries useful information and there is no repetition of schema content.

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

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

With no output schema, the description reasonably summarizes the return as 'items plus page/pages/total' and calls out plan/role gating. However, it does not cover how pagination parameters interact with the response, how search filters should be represented, or how to know when a resource is not available through this endpoint. Useful, but not fully complete for a generic reader with four parameters.

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 exactly 50%, with resource and search documented in the schema but page and per_page left without descriptions. The tool description adds resource examples but does not explain pagination parameters, search-object usage, or the fact that resource must match an enum. It provides only marginal value beyond what the schema already states.

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

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

States a clear verb+resource: 'List any FreshBooks accounting resource by name.' It positions itself as the generic reader and enumerates long-tail resources, which helps distinguish it from dedicated list tools. However, it also lists 'expense categories' which already has a dedicated sibling tool (freshbooks_list_expense_categories), slightly blurring the boundary.

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 'alongside the ones with dedicated tools' implies the generic tool is for resources without dedicated list tools, but it never explicitly states when to prefer this tool over a sibling. The inclusion of 'expense categories' despite a dedicated sibling makes the intended usage less crisp. Minimal guidance for resource access is present but no explicit exclusions are given.

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

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

The readOnlyHint annotation already discloses that this is a safe read-only operation. The description adds no further behavioral details such as pagination behavior or return format, but it does not contradict the annotation either. Minimal viable transparency given 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 a single concise sentence with an effective parenthetical clarification. It is front-loaded, contains no filler, and 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 simple list tool with no output schema and only optional pagination parameters, the description sufficiently defines the resource and its domain. A minor gap is the absence of pagination defaults or response format, but the simplicity and read-only annotation keep this from being a major deficiency.

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?

With 0% schema description coverage, the description should compensate for parameter understanding, but it says nothing about page or per_page. Although these parameter names are self-explanatory, the description adds no meaning beyond the schema's basic type/range constraints.

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

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

The description uses the specific verb 'List' with the resource 'services' and adds clarifying context that services are 'billable work types available to projects and time entries.' This clearly distinguishes it from sibling tools like freshbooks_list_projects or freshbooks_list_items.

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 useful context about what services are and where they are used, helping an agent infer when to use this tool. However, it does not explicitly mention alternative tools or exclusionary conditions, so it stops short of a full when/when-not guide.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context about the response envelope containing total_logged and total_unbilled. This enriches the agent's understanding of the tool's output without contradicting 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?

Two concise sentences, front-loaded with the main purpose and a second sentence for the response envelope detail. 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 simple read-only list tool with two optional pagination parameters, the description covers the core behavior and response envelope. The schema documents the parameter constraints, and the readOnlyHint covers safety. It could be more complete by explicitly stating pagination behavior, but the current coverage is adequate.

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 has no descriptions for the page and per_page parameters, and the description does not explain them. While the names are self-explanatory for pagination, the description adds no meaning beyond the schema's type and constraints.

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

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

The description clearly states the tool lists tracked time entries for the business, using the specific verb 'List' and resource 'time entries.' This distinguishes it from sibling tools that list other entities (invoices, clients, projects).

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

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

The description implies the tool is for retrieving time entries, but provides no explicit guidance on when to use it over alternatives, such as create_time_entry or other list tools. Sibling names distinguish the resource, but the description itself doesn't state any exclusions or alternative contexts.

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 reveals a critical safety feature: confirm must be true to execute, and without it, the tool returns a dry-run preview and makes no network call. This adds value beyond the schema's confirmation parameter description by explicitly stating the network call behavior. However, it does not mention side effects of actual execution, permissions, or error conditions, which are also important for a mutation 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?

The description is extremely concise: one sentence states the purpose, and the second explains the critical confirm behavior. Both are front-loaded and contain no fluff. 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 mutable operation with 6 parameters, a nested object, and no output schema, the description is minimal. It captures the core purpose and confirm gate, but omits return value, prerequisites (e.g., invoice exists), and potential failure modes. While the schema enriches parameter understanding, the overall behavioral context is incomplete for safer execution.

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 provides descriptions for 83% of parameters, including the nested amount object and confirm's behavior. The description does not add any parameter-specific information beyond what the schema provides, so it does not need to compensate. Baseline score of 3 is appropriate given the 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 clearly states the tool's purpose with a specific verb 'Record' and resource 'payment against an invoice.' This distinguishes it from sibling tools like list_payments/get_payment, which are read-only, and from create_invoice/update_invoice which deal with invoices rather than payments.

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 that this tool is for recording payments on invoices. While it does not explicitly name alternative tools or state when not to use it, the sibling list contains mostly read/list operations and other create/update tools, so the intended use is unambiguous. The phrase 'against an invoice' helps differentiate from other payment-related tools.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that this sends email to a client's inbox, requires explicit confirmation, performs no network call without confirm, falls back to the client's stored address if recipients are omitted, and returns the re-fetched estimate. This is exemplary behavioral 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?

Four sentences, each earning its place: the core action, the execution requirement, the recipient fallback, and the return value. It is dense but not bloated, and the most important behavior is front-loaded.

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

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

For a side-effectful email-sending tool with no output schema and no annotations, the description covers the key operational concerns: network side effect, confirmation gate, dry-run safety, recipient resolution, and return value. 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 already documents all five parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema for confirm (dry-run vs. actual execution) and email_recipients (omitting means use client's on-file address), which justifies a higher score.

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 precise verb and resource: emailing an estimate to the client via the action_email endpoint, with the exact API path and payload. This clearly differentiates it from sibling tools like accept_estimate, decline_estimate, and 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 gives clear context on the action's effect, the requirement for confirm: true, and the dry-run behavior when confirm is absent. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to understand the intended 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?

With no annotations provided, the description carries the full burden and does so well. It discloses the dry-run behavior with no network call, the confirm gate, the whole-line-set replacement semantics, and the fact that it returns a re-fetched estimate. This is exactly the kind of behavioral nuance an agent needs before calling a mutation 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?

Four tight sentences with no filler. The core action is front-loaded, followed by the most decision-critical behavioral details in logical order: patch semantics, confirm gate, line replacement warning, and return value. 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?

Despite 14 parameters, nested objects, and no output schema, the description tells an agent everything essential: how partial updates behave, how to actually execute (confirm:true), how to safely update lines, and what the response will be. No critical invocation detail is left to guesswork.

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

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

Schema coverage is 93%, so the schema already documents individual parameters well. The description adds cross-cutting meaning beyond the schema: partial-update semantics, the confirm requirement, and the lineid requirement to preserve existing lines. This elevates it above 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 opens with a specific verb and resource: 'Update an existing estimate.' This clearly identifies the operation and distinguishes it from list/get/send/accept/decline siblings, even without naming them. The phrase 'existing estimate' also separates it from create-style 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 gives strong operational guidance: only supplied fields are sent, omitted fields are untouched, and confirm:true is required to execute. It stops short of explicitly naming alternatives or conditions when NOT to use this tool, so it misses clear exclusions, but the context is otherwise 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 fully discloses key behaviors: only supplied fields are sent (partial update), confirm:true is required for execution, without it returns a dry-run preview and makes no network call, and changing out of draft can email the client. This is excellent behavioral transparency.

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

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

Three sentences, front-loaded with the core purpose. Each sentence adds distinct value: purpose, partial-update and confirm mechanics, and email side-effect warning. No redundant or verbose content.

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

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

The description thoroughly covers operational behavior (partial update, dry-run, email side effect) and usage requirements. It doesn't describe the success return value, but with no output schema and a relatively simple tool, this is a minor gap. Overall, it provides enough context 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 already covers 100% of parameters, but the description adds meaning by stating 'Only the supplied fields are sent,' clarifying the partial-update semantics of the 'fields' parameter. It also reinforces the confirm parameter's dry-run behavior, providing 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 'Update an existing invoice' with a specific verb and resource, clearly distinguishing it from siblings like freshbooks_create_invoice and freshbooks_get_invoice. The 'existing' qualifier unambiguously scopes the tool's purpose.

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

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

It implies usage for existing invoices and provides critical guidance on the confirm parameter (must be true to execute; otherwise dry-run preview). It also warns about the email side effect when leaving draft. However, it doesn't explicitly name alternatives or state when not to use, so a small deduction.

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