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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it filters to unpaid supplier bills and organizes them into overdue buckets, which explains the report's structure. It does not contradict 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 that are front-loaded with the key term 'Aged creditors' and immediately explain what the report does. No filler or redundant information.

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

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

For a simple, read-only report with one optional parameter and no output schema, the description provides sufficient context about what the tool does and what it shows. It doesn't detail the exact response structure but the mention of 'bucketed' hints at the output. Slightly more detail about the asAt parameter could improve it, but it's not 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?

Schema description coverage is 100% and the only parameter (asAt) is fully described with format and default value. The tool description does not add any extra parameter information, which is acceptable since the schema carries the burden. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it shows unpaid supplier bills bucketed by how overdue they are. This distinguishes it from the sibling tool freeagent_aged_debtors (which presumably covers customer invoices) by explicitly mentioning 'supplier bills' and 'what the company owes.'

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

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

Usage context is implied rather than explicit. The description indicates this is for viewing supplier-related aged balances, which implies using it when you need creditor aging info, but it does not directly reference alternatives or state when not to use it. No exclusions or alternative tool names are mentioned.

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 destructiveHint=false, so the safety profile is covered. The description adds clarity by defining the aging buckets and output focus, but it doesn't disclose additional behavioral context such as how the aging is calculated or whether all customers are included. The description does not contradict 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 a single concise sentence that front-loads the key concept ('Aged debtors') and efficiently elaborates with bucket details. Every word contributes meaning; 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 report with one optional parameter, the description adequately conveys the report's content and purpose. It clearly explains the output (aging buckets and who owes what) even without an output schema. Slight gap: it doesn't mention the optional 'asAt' parameter in the description, but the schema covers that.

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 provides 100% coverage for the only parameter (asAt) with a clear date format and default. The description adds no extra parameter-specific detail, but the baseline of 3 applies because the schema fully documents the parameter.

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: it lists unpaid customer invoices bucketed by aging periods. It explicitly defines the resource ('aged debtors') and the action ('shows who owes what and for how long'), and the name + description naturally distinguish it from the sibling 'freeagent_aged_creditors'.

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

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

The description implies when to use the tool (when analyzing overdue receivables) but does not explicitly state when-not-to or mention alternatives like freeagent_aged_creditors. It gives a clear context but lacks exclusions or comparative 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 and destructiveHint=false, so the safety profile is known. The description adds value by specifying the exact set of returned fields, which is useful because there is no output schema. It does not contradict annotations.

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

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

The description is a single, front-loaded sentence with an em dash to list contents. Every word earns its place, and there is 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 zero-parameter, read-only tool with no output schema, the description fully communicates what the tool returns. The listed fields are sufficient for an agent to know what to expect. No additional context is required.

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?

This tool has zero parameters, and the schema is complete with no properties. The description correctly avoids inventing parameters. With 0 parameters, the baseline is 4, and no further parameter explanation is 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 clearly identifies the resource (FreeAgent company details) and enumerates the specific fields returned (name, type, registration number, VAT status, year end, currency). This distinguishes it from sibling tools that deal with contacts, invoices, bills, and other specific entities.

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

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

No explicit usage guidelines or alternative tools are mentioned. The purpose is clear enough that an agent can infer when to use it (when company-level details are needed), but it does not state exclusions or compare to siblings.

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 says 'Record', which appropriately signals a state-changing operation and matches the annotations. However, it does not disclose side effects beyond creation, such as whether duplicate calls create duplicate bills, or whether special permissions are required. Annotations cover read-only/destructive/idempotent hints, but the description adds little independent behavioral context.

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

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

The description is short, front-loaded with the core purpose, and every sentence contributes either to tool selection or to an efficient workflow. The RECEIPTS note is prominent without being verbose.

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 table with 12 parameters, the description plus fully covered schema is enough for an agent to construct a valid call. It does not explain return values, but there is no output schema and create-tool output is not usually self-serve. A small gap is not explicitly stating what to do if no email match is found, though it is reasonably implied.

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 value by emphasizing that every line requires a category and a value including tax, and it explains how fileBase64 and fileName should be supplied when a matching invoice is found in email tools. This is actionable semantics beyond the raw schema descriptions.

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

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

The description opens with a specific action and resource: 'Record a supplier bill', with the parenthetical 'an invoice the company has received and owes' removing ambiguity. This clearly separates the tool from invoice creation for customers and from expense recording without needing to inspect the schema.

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

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

It gives clear context for when to use the tool: recording supplier bills. The RECEIPTS section adds a concrete workflow instruction by telling the agent to search Gmail/Outlook for the supplier invoice before asking the user for a PDF. It does not explicitly name alternative tools or exclusion cases, but the contextual cue is strong enough to guide selection.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which adequately signals that this persists a new record and is not idempotent. The description adds the practical constraint about naming, but doesn't disclose duplicate behavior, permissions, or response shape. With the annotations in place, this is acceptable but not rich.

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

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

Two concise sentences with no filler. The subject and resource are front-loaded, and the sentence sentence explains both the use cases and the most important optional-field constraint. Every clause earns its place.

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

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

For a straightforward create operation with 13 optional params, the description covers the only non-obvious constraint (the naming rule) and leaves the rest to the full parameter schemas. The lack of an output schema and response details means the agent can't predict the exact returned object, but the description is still sufficient for selecting and invoking the tool correctly in most cases.

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?

All 13 parameters already have descriptions in the schema, so the baseline is 3. The description improves on that by clarifying the business grouping: either organisationName or firstName / lastName must be supplied (or both), and the contact is a client or supplier. This is semantic context not present in the parameter schemas.

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 the exact verb and resource ('Create a contact in FreeAgent') and explains why the contact is being created — a client to invoice or a supplier to record bills against. This distinguishes it cleanly from sibling tools like freeagent_create_invoice or freeagent_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?

By identifying the two business contexts that call for this tool — invoicing a client or recording bills against a supplier — the description gives an agent a clear trigger. It doesn't explicitly list alternatives or exclusions, but there is no dedicated contact-creation sibling, so the context is sufficient.

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?

Since annotations only mark readOnly/idempotent/destructive hints, the description carries the burden here. It discloses auto-selection of category from vendor, optional bank-transaction matching via bankAccountId, and the required receipt-search workflow. It stops short of explaining the full side-effect of linking/explaining the bank transaction, which prevents a 5.

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

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

Two structured paragraphs with no filler. The core purpose is frontloaded, the optional bank-account matching is clearly explained, and the RECEIPTS section is practical workflow guidance rather than redundant paraphrasing of the schema.

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

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

With 12 parameters and no output schema, the description covers the main invocation intent, optional behaviors, and the required receipt-presearch step. It lacks an explicit note on what the tool returns after success, but that is not critical 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 covers 100% of parameters, giving a baseline of 3. The description enriches beyond the schema by tying parameters to real scenarios: personal card purchases, company-card overlap, and the vendor-and-date matching for bankAccountId. These additions help the agent select which parameters matter in context.

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 precisely 'Create an expense in FreeAgent' and narrows the use case to 'purchases on a personal card or cash that need claiming back'. This clearly distinguishes it from the mileage-expense sibling and tells the agent exactly what resource is being created.

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

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

Gives a concrete scenario for when this tool applies and even instructs the agent about receipt-related workflow before invocation. It does not explicitly mention alternatives such as freeagent_create_mileage_expense, so the agent is left to infer which sibling handles mileage claims.

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

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

Annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, which give minimal context. The description adds critical behavioral information: the invoice is created as a DRAFT and is not sent to the client. This is a key side effect not inferable from annotations or schema. It could go further by noting response shape, but the draft disclosure is substantial.

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 paragraphs: the first states the tool's purpose and key behavioral note, the second gives the lookup workflow. Every sentence contributes useful information; 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?

Given 10 parameters and no output schema, the description covers the essential workflow (draft creation, next step to send, prerequisite lookups). The schema handles parameter details. A more complete description might mention the response format or error handling, but for a create operation with a rich schema, this 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 already provides 100% coverage for all 10 parameters, so the baseline is 3. The description adds practical guidance for two key parameters (contact and categoryUrl) by telling users to look them up with dedicated list tools and giving an example category URL ('001 Sales'). This goes beyond the schema's formal descriptions.

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

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

The description opens with 'Raise an invoice in FreeAgent' — a specific verb with a clear resource. It immediately distinguishes itself from sibling tools like freeagent_update_invoice_status and freeagent_delete_invoice by clarifying it creates a draft, not a sent invoice.

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

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

Explicitly states when to use this tool (raise a draft invoice) and directs users to freeagent_update_invoice_status for marking as sent. Also provides lookup guidance for contacts and income categories via freeagent_list_contacts and freeagent_list_categories, naming the exact 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?

With annotations providing no supportive hints (all false), the description carries the burden and excels. It discloses that the claim value is computed by FreeAgent, that ratePence/cumulativeMilesYTD are advisory only, and that distance lookup requires API keys. This goes well beyond the structured data.

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

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

The description is compact, front-loaded with the core action, and every sentence contributes critical information. It avoids fluff and redundancy while conveying complex behavioral nuances in two paragraphs.

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 11 parameters and no output schema, the description covers all essential usage aspects: input modes, distance computation, rounding behavior, and the distinction between advisory and filed values. No critical gap is apparent for an AI agent to select and invoke 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?

Despite 100% schema coverage, the description adds significant semantic value by explaining the exclusive-or relationship between origin/destination and manualMiles, the effect of roundTrip, and the advisory nature of ratePence/cumulativeMilesYTD. This synthesis is not obvious from the schema alone.

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-resource pair ('Create a mileage expense in FreeAgent') that clearly identifies the tool's function. It implicitly distinguishes itself from the sibling 'create_expense' by focusing specifically on mileage, and the name reinforces this. No ambiguity exists.

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

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

The description clearly instructs when to use origin+destination versus manualMiles, and explains the roundTrip flag. It does not explicitly mention when to prefer this over freeagent_create_expense, but the context is clear enough for mileage-specific scenarios. A slight exclusion note would elevate it to 5.

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

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

Annotations already indicate a non-read-only, non-idempotent mutation. The description aligns with readOnlyHint=false and adds useful domain behavior (tasks set billing rates for logged time). It does not disclose idempotency implications, error behavior, or prerequisites, but annotations lower the burden.

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 fluff. The first sentence is front-loaded and directly states the operation; the second provides essential context about billing rate. 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 core function and domain relevance are covered. Given the 100% schema coverage and absence of an output schema, the description doesn't need to explain return values. It could mention that the project must exist or contrast with timeslip creation, but these are minor gaps.

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

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

Schema coverage is 100% with clear individual parameter descriptions. The description adds meaning by explaining that billingRate and billingPeriod define how logged time is charged, linking the billing parameters to the timeslip use case. This goes beyond the schema's isolated field descriptions.

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

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

The description clearly states the action and resource: 'Create a task on a FreeAgent project.' It distinguishes from sibling create tools (e.g., create_contact, create_expense) by specifically naming 'task' and adds domain context about billing rates, which ties it to timeslips.

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 by explaining that tasks carry the billing rate for logged time, suggesting a prerequisite before creating timeslips. However, it does not explicitly state when to use this tool versus alternatives like create_timeslip or list_tasks, nor does it mention exclusions.

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

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

Annotations already indicate a non-read-only, non-destructive write operation. The description adds valuable behavioral context by noting that the user defaults to the authenticated user, which is not obvious from annotations alone. It also references a necessary lookup step, which helps set expectations.

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, immediately states the core purpose, and contains no filler or redundant information. 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 create tool with 6 parameters and no output schema, the description covers the essential context: what it does, the default user behavior, and how to find the required task. It could mention the return value or potential errors, but the schema and annotations cover parameter details, so this is reasonably complete.

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

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

Schema coverage is 100% with each of the 6 parameters having a description, so the baseline is 3. The description adds little beyond the schema (e.g., 'defaults to the authenticated user' duplicates the user parameter description). No additional parameter meaning 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 clearly states the action ('Log time') and the resource ('against a FreeAgent project task'), which distinguishes it from sibling tools like freeagent_list_timeslips or freeagent_delete_timeslip. It also mentions the default user behavior, adding specificity.

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

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

The description gives clear context for when to use the tool (recording time against a task) and even points to the prerequisite tool 'freeagent_list_tasks' for finding the task. It does not explicitly name alternatives or exclusions, but for a create operation the usage context is sufficiently 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?

Annotations already declare destructiveHint true and idempotentHint true, so the safety profile is known. The word 'Permanently' reinforces irreversibility but adds no new behavioral context beyond annotations, and no details on side effects or error conditions are provided.

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 no filler. It front-loads the action verb and resource, making it immediately clear what the tool does.

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 simple one-parameter schema and annotations covering safety, the description is adequate but lacks information about return values or behavior for non-existent bills. Without an output schema, this leaves some ambiguity for the agent.

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

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

The input schema fully documents the only parameter, billId, including a pattern and description. The tool description adds no parameter-specific semantics, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description states 'Permanently delete a FreeAgent bill' with a specific verb and resource, making the tool's function unambiguous. It also distinguishes from sibling delete tools for invoices and timeslips by naming the 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?

There is no guidance on when to use this tool versus alternatives such as delete_invoice or delete_timeslip, nor any prerequisites or contextual conditions. The usage is only implied by the tool's name and action.

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 destructive and idempotent behavior; the description adds the restriction that only draft invoices can normally be deleted and that deletion is permanent, which is valuable context beyond the schema.

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

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

Two sentences, both information-dense: the first states the core purpose, the second covers constraints and alternatives. No wasted 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?

With one simple parameter, no output schema, and annotations covering destructive/idempotent hints, the description sufficiently covers the operation, including the critical draft-only limitation and the alternative for non-draft invoices.

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

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

The input schema already fully describes the single parameter (invoiceId with description and pattern). The description does not add additional parameter-specific details beyond that, so baseline 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 ('Permanently delete') and the resource ('FreeAgent invoice'), and it distinguishes itself from sibling freeagent_update_invoice_status by mentioning the alternative for issued invoices.

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

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

It explicitly states when deletion is allowed (draft invoices only) and directs users to freeagent_update_invoice_status for canceling issued invoices, providing clear when/alternative 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 description merely repeats the destructive nature already indicated by annotations (destructiveHint=true, readOnlyHint=false). It adds no extra context such as irreversibility, permission requirements, or behavior for non-existent timeslips. With annotations present, the description provides minimal added value beyond them.

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 clear sentence with no unnecessary words. It is concise and front-loaded, stating exactly what the tool does. 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 delete tool with one parameter and annotations covering the safety profile, the description is minimally complete. However, it lacks any context about side effects or when deletion is allowed, which is a gap for a destructive operation. The presence of annotations partially compensates, but the description alone would not fully prepare an agent for nuanced situations.

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 timeslipId is fully documented in the schema with type, pattern, and description. The tool description does not mention the parameter at all, so it adds no additional meaning. Given 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action 'Delete' and the resource 'a logged timeslip from FreeAgent', which is specific and distinguishes it from other delete tools targeting different resources (e.g., delete_bill, delete_invoice). It is not a tautology and adds the context 'logged' to clarify the subject.

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

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

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or consequences. The usage is only implied by the tool's purpose; it says nothing about conditions under which deletion is appropriate or what to do if the timeslip is referenced elsewhere.

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 key behavioral traits beyond the annotations: re-attaching replaces an existing attachment, the server reads/encodes filePath or fileUrl, large fileBase64 payloads are unreliable, and markExplained should be set only with confirmation. These details match the idempotentHint and readOnlyHint=false annotations, with no contradictions.

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 uses clear sections (main actions, RECEIPTS, SAFETY) and bullet, front-loading the primary purpose before digging into attachment workflow. Every sentence serves a distinct purpose—no filler—and the structure lets the agent rapidly locate the relevant guidance.

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

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

For a 9-parameter mutation tool with no output schema, the description covers everything an agent needs: how to resolve the required explanationId, how to handle file options, how to source receipts, and when it is safe to approve. It also directs to relevant sibling tools where appropriate. The lack of explicit return-value documentation is acceptable because no output schema exists and the primary responsibility is to perform the mutation.

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 every parameter already has meaning. The description enriches that meaning with prioritizing filePath/fileUrl over fileBase64, explaining how fileName defaults when using filePath, and clarifying the safety condition on markExplained. This is above baseline but some repetition of schema text exists.

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

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

The description opens with a specific verb-resource pair: 'Approve or update a FreeAgent bank transaction explanation' and immediately lists the three core actions it supports. It clearly distinguishes this tool from siblings like freeagent_list_transactions by directing the agent to obtain explanationId from that list tool.

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

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

Provides explicit when-to-use workflows: approving marked-for-review transactions, changing categories/descriptions, and attaching receipts. It also gives conditional guidance ('Only set markExplained=true when you have a confirmed receipt attached or the user has approved it') and cross-tool references, such as using freeagent_list_categories for the category path.

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 destructiveHint=false, so the description builds on that by specifying what 'full' means (including line items). It adds useful behavioral context beyond the annotations without contradicting them.

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

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

A single, succinct sentence that front-loads the verb and resource, with zero wasted words. It is immediately scannable 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 simple, single-parameter read-only tool with strong annotations, the description covers the essential purpose and return scope. No output schema exists, so the mention of line items helps set expectations. The tool's simplicity means nothing critical is missing.

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

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

The single parameter invoiceId is fully described in the schema (100% coverage), including its pattern. The description does not need to add parameter-level detail, and it doesn't, but it reinforces that the tool fetches by ID. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Fetch') targeting a single resource ('a single FreeAgent invoice') and adds a key differentiator ('in full, including its line items'). This distinguishes it from sibling tools like freeagent_list_invoices.

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

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

The description implies usage when a specific invoice ID is known and full detail (including line items) is needed. It does not explicitly name alternatives or exclusions, but the clear scope ('single') and sibling context provide adequate 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 indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields but does not mention behavior like pagination or limits. It is consistent but not highly informative beyond annotations.

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

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

The description is two sentences, front-loaded with purpose and output, with no wasted words. Every sentence adds value.

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

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

For a simple list tool with no parameters and good annotations, the description covers purpose, return fields, and a usage hint. It is complete enough for effective tool 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 input schema has no parameters, so description coverage is 100%. The description implies the tool returns all accounts without filters, which is sufficient. Baseline of 4 for zero parameters.

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

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

The description explicitly states it lists all bank accounts and details the returned fields (name, currency, balance, status). It clearly distinguishes from sibling tools which deal with expenses, categories, or transactions.

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 advises using this tool to find the bank account ID before listing transactions, providing explicit usage guidance. No when-not-to-use statements, but the context 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?

Annotations already provide readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds behavioral context by explaining that open_or_overdue views show unpaid bills, which is a useful nuance beyond the schema's enum.

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

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

Two sentences, front-loaded with the purpose, and the usage tip is compact and actionable. No wasted 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 read-only list tool with full schema coverage, no output schema, and annotations declaring safety, the description covers the essential usage. It could mention pagination or return format, but these are less critical for a simple list endpoint.

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

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

The schema already describes all 6 parameters with 100% coverage, so the baseline is 3. The description adds slight extra meaning for the 'view' parameter, but overall the schema carries the parameter documentation burden.

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

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

The description uses the specific verb 'List' with the resource 'FreeAgent bills' and clarifies the domain meaning as 'money the company owes to suppliers (accounts payable)', which distinguishes it from sibling tools like list_invoices, create_bill, and delete_bill.

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

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

It provides a clear usage directive: 'Use view='open_or_overdue' to see what is still to pay.' This gives a concrete use case, but it doesn't explicitly contrast with alternatives or state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that results are cached after the first call, which is additional behavioral context beyond annotations.

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

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

Three concise sentences that front-load the action and purpose. Could be slightly trimmed but effectively communicates key information without redundancy.

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

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

Despite no output schema, the description lists return fields and mentions caching, providing adequate context for a simple list tool with no parameters. Sufficient for an agent to understand and invoke 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?

No parameters exist (schema coverage 100%), so parameter semantics are inherently satisfied. Baseline 4 per guidelines for zero-parameter tools.

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 it lists FreeAgent expense categories (chart of accounts) and specifies returned fields (URL, description, nominal code, group). This distinguishes it from sibling tools that deal with expenses or transactions.

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

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

Explicitly instructs to use the category URL when creating expenses or explaining transactions, providing clear use context. No explicit when-not-to-use, but the guideline is sufficient for this simple tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds the return field list and the note about using the contact URL in invoices/bills, which is useful but not additional behavioral disclosure beyond what annotations and schema provide. No contradictions exist.

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

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

The description is two sentences with no filler. The core action is front-loaded ('List FreeAgent contacts'), and the second sentence adds actionable guidance about the contact URL. 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?

Considering the low complexity, full schema coverage, and strong annotations, the description is nearly complete. It lists return fields, which compensates for the lack of an output schema, and the parameter descriptions cover pagination and filtering. It does not need to explain simple details like status meaning, so it is complete for the tool's purpose.

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

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

Schema description coverage is 100%, with each parameter (view, limit, search) fully described. The description's mention of 'clients and suppliers' aligns with the view enum but does not add meaningful semantic detail 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 begins with 'List FreeAgent contacts (clients and suppliers)', using a specific verb (List) and resource (FreeAgent contacts) with added scope (clients and suppliers) and return fields. It is unambiguous and distinguishes itself from sibling tools such as create_contact or list_invoices by being the only contact-listing tool.

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

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

The description does not explicitly state when to use this tool versus alternatives, but it provides downstream usage context: 'Use the contact URL when raising an invoice or entering a supplier bill.' This implies a need for contact data when performing those operations, but there are no explicit exclusions or alternative tool mentions, so usage guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful context about the returned data (status, outstanding balance) and filter behavior via views, but does not disclose pagination limits or API-specific edge cases.

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

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

Two sentences, front-loaded with the primary action and resource. The view guidance is concise and actionable, and every sentence earns its place without redundancy.

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

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

Given no output schema, the description does mention key return fields (status, outstanding balance), which partially offsets that gap. With all parameters optional and well-documented in the schema, and annotations indicating a safe list operation, the description is largely complete. Minor omission: no mention of default ordering or result limit behavior beyond the schema's 'default 50, max 100'.

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 100% parameter description coverage, including enums, regex patterns, and defaults. The description only re-emphasizes some view values and adds no new syntax or formatting details beyond the schema, so a 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?

Clearly states the verb 'List' and resource 'FreeAgent invoices', and specifies the output includes status and outstanding balance. It distinguishes itself from sibling tools like list_bills and list_contacts, and the mention of specific views (overdue, open_or_overdue, draft) reinforces 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?

Provides explicit guidance on when to use different view values (e.g., 'overdue' to chase late payers, 'draft' for unissued invoices), which is valuable context. However, it does not mention when not to use this tool or point to alternatives like get_invoice for individual invoice details, so it stops short of full 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?

Beyond the readOnlyHint annotation, the description discloses what the tool returns (project URL, name, status, contact) and that the project URL is used for expense tagging. This adds behavioral context without contradicting annotations, though it omits details like pagination or authentication.

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, immediately states the action and results. 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-only list operation with one optional parameter, the description covers purpose, return values, and a downstream use case. The output schema is absent, but the listed return fields suffice.

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

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

The input schema fully documents the single 'view' parameter with an enum and default, so the schema carries the parameter meaning. The description itself adds no additional parameter information, but since schema coverage is 100%, a 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 opens with 'List FreeAgent projects', a specific verb+resource that clearly identifies the tool's function. It also lists returned fields (URL, name, status, contact), distinguishing it from other list tools like freeagent_list_tasks or freeagent_list_contacts.

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 for when to use this tool: when you need project details, particularly to tag expenses to client engagements via freeagent_create_expense. It doesn't explicitly exclude alternative tools or state when-not-to-use, but the integration hint is valuable.

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 destructiveHint=false, so the safety profile is clear. The description adds the domain fact that time is always logged against a task, but does not disclose tool-specific behaviors such as default view, pagination handling, or response structure. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the purpose and immediately followed by actionable usage guidance. There is zero redundancy or irrelevant detail, earning a perfect score for conciseness.

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 fully described parameters and read-only annotations, the description covers the core purpose and a key use case. It does not mention return format or fields, but this is partially mitigated by the absence of an output schema and the simplicity of the tool. Overall, it is sufficiently complete for an agent to select and use 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%: all three parameters (view, limit, project) have descriptive text and constraints already. The tool description adds no additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List project tasks in FreeAgent.' It also distinguishes itself from sibling tools like freeagent_list_projects and freeagent_list_timeslips by noting that tasks are tied to time logging, which makes its 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 provides explicit usage context: 'Time is always logged against a task, so use this to find the task URL before creating a timeslip.' This tells the agent exactly when to use this tool and connects it to the downstream action of creating a timeslip, effectively naming the alternative or next step.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by noting that the tool returns per-project totals alongside individual entries and that the 'unbilled' view filters to uninvoiced timeslips, giving the agent a clearer picture of the output and filtering behavior.

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

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

The description is concise and front-loaded, stating the core purpose in the first sentence and adding relevant usage details in the following two sentences. Every sentence earns its place without redundancy or fluff.

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

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

For a read-only listing tool with a rich schema and annotations, the description provides sufficient context: it identifies the operation, the date-range scope, a specific view mode, and the shape of the return data. It could mention pagination or limits, but the schema already documents the limit parameter, so this is not a significant 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?

The input schema thoroughly describes all parameters (100% coverage), so the baseline is 3. The description adds marginal semantic value by explaining the meaning of 'view='unbilled'' in context, but does not significantly enhance understanding of the other parameters beyond what the schema already provides.

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

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

The description clearly states the tool lists logged time in FreeAgent for a date range, using a specific verb and resource. It also differentiates from siblings like freeagent_create_timeslip and freeagent_delete_timeslip by focusing on the listing 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 clear context for using the tool (listing time in a date range) and gives a specific use case ('view='unbilled'') to find uninvoiced time. It does not explicitly name alternatives or exclude other tools, but the usage context is clear enough for an agent to select it appropriately.

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 destructiveHint=false, so safety is covered. The description adds default filtering behavior and output fields, but it does not describe pagination, rate limits, or edge cases. This is moderate additional value, thus a 3.

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

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

The first three sentences are clear and front-loaded, but the final sentence about checking email/local sources before asking the user is a lengthy tangent that, while useful, is not essential to describing the tool's core function. This prevents a top score.

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 simple listing nature, the schema's full parameter documentation, and the annotations, the description provides enough context: default view, required ID source, and return fields. It lacks only deeper response details, but the mentioned fields suffice. A 4 is justified.

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 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds a useful pointer for bankAccountId, but no additional syntax or format 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?

The description clearly states 'List bank account transactions from FreeAgent' with a specific verb and resource. It further clarifies the default view (unexplained) and return fields, making it distinct from sibling listing tools for contacts, invoices, etc.

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

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

The description instructs to 'Use bankAccountId from freeagent_list_bank_accounts', providing a clear prerequisite. It implies the tool's intended use for listing transactions but does not explicitly state alternatives or when-not-to-use cases, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint true and destructiveHint false. The description adds value by specifying the content of the summary (income, expenses, operating profit, corporation tax estimate, dividends, retained profit) and the default period. It does not mention limitations like pagination or exact output structure, but the added detail goes 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 a single, well-structured sentence that front-loads the tool's purpose and uses a dash to introduce key details. It is concise and every word adds value, with no redundant filler.

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

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

For a read-only reporting tool with two optional parameters and good annotations, the description is sufficiently complete. It lists the expected components of the summary, which compensates for the absence of an output schema. No critical information is missing.

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

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

The input schema already provides full descriptions for both parameters (fromDate and toDate), including their defaults and formats. The description's mention of 'current accounting year' merely echoes the schema defaults and adds no new semantic meaning. Schema coverage is 100%, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a FreeAgent profit and loss summary, enumerating the included components (income, expenses, operating profit, etc.). This distinguishes it from sibling tools like trial balance or company summary. However, it lacks an explicit action verb (e.g., 'get' or 'list'), instead using a noun phrase that closely mirrors the tool name.

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 that the tool defaults to the current accounting year, giving some usage guidance. It implies this is the go-to tool for P&L data, but it does not explicitly state when to use it over alternatives or mention excluded scenarios. No clear when-not-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by specifying the types of tax items included and that amounts and dates are provided, which goes beyond the schema.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and key returns without any filler. It earns its place with relevant 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 simple read-only report with one optional parameter and no output schema, the description covers the essential return content (amounts due and dates) and the scope thoroughly. It is sufficiently complete for an agent 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%, as the only parameter includePersonal has a clear description in the schema. The tool description does not add additional meaning about the parameter, so it stays at the baseline of 3.

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

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

The description clearly identifies the tool as providing a timeline of upcoming tax and filing deadlines from FreeAgent, naming specific categories (VAT, corporation tax, Companies House, self assessment) and what it returns (amounts due and dates). This distinguishes it from sibling tools like freeagent_profit_and_loss or freeagent_company_summary.

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

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

The description clearly implies usage for tax-related deadline inquiries, which provides a clear context. It does not explicitly exclude other tools or mention alternatives, but the specificity of the scope makes the intended use obvious.

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

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

The description discloses a key behavioral detail (sign convention) and mentions 'every nominal account', but this conflicts with the nonZeroOnly parameter default (true), which omits zero-balance accounts. This creates ambiguity about actual default behavior. Annotations already cover read-only/destructive safety.

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 tool name and core purpose. The additional sign convention is essential. No wasted 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 report tool with no output schema, the description covers the main output (balances) and sign convention, but fails to mention the nonZeroOnly filter's default behavior, which conflicts with 'every account'. It also does not describe return format (though not required by schema). The ambiguity reduces 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%, so both parameters are well-documented. However, the description's phrase 'every nominal account' contradicts the nonZeroOnly parameter's default, potentially misleading agents about filtering behavior. The description does not add positive value beyond the schema and introduces confusion.

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 reports the balance on every nominal account with a sign convention (credits negative, debits positive). It does not explicitly distinguish from sibling financial reports like freeagent_profit_and_loss, but the specific resource (trial balance) 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 provides a clear context for use ('Useful for a full financial position') but lacks explicit guidance on when to prefer this over alternatives or when not to use it. No alternative tools are mentioned.

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 signal destructive and non-read-only behavior, but the description adds valuable context: 'no email is sent to the client' and explains what each transition does (e.g., 'issue it', 'pull it back'). This goes beyond the structured data and clarifies a key side-effect that users would otherwise assume. 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?

Two concise sentences front-load the purpose and immediately list the supported transitions. Every word earns its place, and the behavioral note about email is a single clause. No fluff 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?

The tool is a simple mutation with no output schema, and the description covers the core behavior, transitions, and a key side-effect (no email). It could mention prerequisites like invoice state, but the description is sufficient for most use cases given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the transition enum values in plain language (mark_as_sent = issue it, mark_as_draft = pull it back), which helps the agent select the right transition. This elevates it above the baseline.

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

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

The description clearly states the tool changes an invoice's status, enumerates the exact transitions (mark_as_sent, mark_as_draft, mark_as_scheduled, mark_as_cancelled), and explains their effects. This distinguishes it from sibling invoice tools like list_invoices or get_invoice which don't modify status.

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

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

The description implies when to use the tool: whenever an invoice's status needs to be changed. It doesn't explicitly mention alternatives or exclusions, but the scope is unambiguous given the sibling context. A clear 'use this instead of X' would push it to 5, but it's still well-contextualized.

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