FreeAgent MCP by usefulapi

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

Annotations only supply destructiveHint=true, i.e. that this is a mutating call; the description adds the mutual-requirement rule and the underlying POST /v2/contacts endpoint, which is mild context. It says nothing about whether re-creating the same contact duplicates data, what permissions are needed, or what happens on failure.

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, purpose first, binding constraint second, endpoint trivia last; nothing wasted and the most decision-relevant information is front-loaded.

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

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

Covers the identity requirement and the write nature of the call, but for a 19-parameter creation tool with no output schema it omits what is returned (no created-contact ID hint) and whether the remaining fields are all optional, leaving gaps the agent must infer.

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 descriptive per-field text, so baseline is 3, but the description adds a real cross-parameter constraint (organisation_name XOR first_name+last_name) that the schema cannot express since it declares zero required fields and no oneOf.

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

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

States a specific verb and resource ('Create a client or supplier contact') and names the two contact flavours, which cleanly separates it from freeagent_update_contact and freeagent_get_contact among the siblings.

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

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

Offers one invocation rule ('Give either organisation_name, or first_name and last_name') which is genuinely useful, but gives no when-to-use context, no prerequisites (e.g. auth/company scoping), and no exclusions relative to update_contact or list_contacts.

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

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

Adds real behavioral context beyond the destructiveHint annotation: no customer notification, no income posting until sent, and the draft is editable/discardable in FreeAgent. This meaningfully clarifies the side-effect profile, though it doesn't note auth requirements or response behavior.

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

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

Three tight sentences, front-loaded with the core action and state, then the behavioral caveat, then the API mapping. No wasted text and nothing buried.

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

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

For a creation tool with no output schema and fully documented params, the description covers the important state semantics an agent needs. It could say more about auth/scopes or the returned draft identifier, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so every parameter (contact, dated_on, payment_terms_in_days, invoice_items, etc.) is already documented in the schema. The description adds no parameter nuance beyond that, so the baseline 3 applies.

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

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

States a specific verb, resource, and lifecycle state: 'Create a sales invoice in DRAFT status.' This cleanly distinguishes it from siblings like freeagent_list_invoices and freeagent_get_invoice without the agent needing to open any 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?

Explains the operative context: a draft is not sent nor posted as income until marked sent, and can be edited or discarded. That tells the agent what kind of invoice it is producing, though it stops short of naming explicit when-not conditions or alternative 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 destructiveHint=true, so the safety profile is partly covered. The description adds value by disclosing the POST /v2/timeslips endpoint and that the slip remains 'Editable or removable in FreeAgent afterwards'. It does not discuss permissions, auth, or side effects on the project/task totals.

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

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

Front-loaded with the core action, followed by the prerequisite hint and endpoint. Four short sentences, each carrying information, with no filler.

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

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

There is no output schema, so the description carries return-value burden, but for a create call it is adequate: it names the resource, prerequisites, and mutability. Missing details on permissions or error behavior are minor for a 6-param tool with full schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool sourcing meaning for the user and task parameters that the schema does not provide. It still does not clarify hours limits or date format 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 specific verb+resource ('Log time against a project task') and clearly distinguishes itself from sibling list/get tools by describing the create action. An agent immediately knows this creates a timeslip record.

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 concrete prerequisite workflow by naming freeagent_get_current_user and freeagent_list_tasks as the sources for the required user and task ids. It does not state explicit exclusions or when-not to use it, 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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds the useful default ('today') and the underlying endpoint (GET /v2/accounting/balance_sheet), but says nothing about auth requirements, response shape, or whether comparative periods are returned.

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

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

A single front-loaded sentence with no filler; the resource and its contents come first, the scoping clause and endpoint reference follow. 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 one-optional-parameter, read-only reporting tool with no output schema, the description covers purpose, contents, default date, and the endpoint. Return structure is only hinted at via the line-item enumeration, which is acceptable but slightly thin.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a default value ('default today') that the schema itself does not encode as a default. That is a genuine increment over the structured field for this single optional 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?

States a specific verb+resource ('Balance sheet') and enumerates its contents ('capital and current assets, liabilities and owners' equity') plus the temporal scope. This effectively separates it from the sibling freeagent_get_profit_and_loss without naming it, though no explicit sibling differentiation is stated.

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 through the 'as at a date (default today)' scoping and the accounting context, but never says when to prefer it over freeagent_get_profit_and_loss or the other financial reporting siblings. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that: it lists what comes back, characterizes the call as cheap, and maps it to the underlying endpoint (GET /v2/company), which helps an agent reason about cost and scope.

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

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

Two tight sentences, front-loaded with the verb and resource, followed by the payoff ('cheap way to confirm setup') and an endpoint reference. No filler.

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

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

With no output schema, the description usefully enumerates the returned fields, which is exactly what an agent needs here. It stops short of mentioning failure modes (e.g. invalid credentials returning an error), leaving a minor gap for a credentials-validation tool.

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

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

There are zero parameters, so there is nothing to disambiguate; the baseline for a no-param tool is 4. The description correctly implies no arguments 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?

States a specific verb (Fetch) and resource (the FreeAgent company these credentials belong to), and enumerates the returned fields (name, type, currency, start date, VAT status). This clearly distinguishes it from siblings like freeagent_get_current_user and the various list_* 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?

Adds a clear usage context — 'A cheap way to confirm the setup works' — telling the agent this is a low-cost validation/health-check call. It does not name an explicit alternative or state when not to use it, so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the upstream mapping (FreeAgent: GET /v2/contacts/:id), which is mildly useful, but says nothing about behavior on a missing contact, auth requirements, or rate limits.

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, front-loaded with the action and scope, followed by the endpoint reference. Nothing is padding; every clause carries information.

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

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

For a one-parameter read tool with readOnlyHint and full schema coverage, this is nearly sufficient. The only real gap is what the call returns (a contact object) and how a not-found id behaves, which is minor given there is no output schema to defer to.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'numeric id or full FreeAgent URL'. The description's 'by id or URL' merely restates the schema rather than adding format or resolution details, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single contact by id or URL') and implies the single-record scope that separates it from freeagent_list_contacts. It does not name the sibling explicitly, so an agent still has to infer the list-vs-get split.

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

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

Usage is only implied: you call it when you already have a contact id or URL. There is no explicit statement of when to prefer this over freeagent_list_contacts (e.g., discovery by name) or any prerequisite/permission context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description goes further by naming what the response contains (user URL, permission level) and naming the downstream consumer of that URL. It does not mention auth failure behavior or token scopes, which is a minor omission rather than a contradiction.

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

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

Two sentences, no filler, with the tool's identity and the actionable dependency ('needed for freeagent_create_timeslip') front-loaded before the endpoint reference. 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 zero-parameter read with no output schema, the description carries the useful return-value burden by naming the URL and permission level. It stops short of describing error or invalid-token behavior, but nothing required to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly adds no parameter guidance because there is nothing to parameterize.

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

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

States a specific verb and resource (fetch the token's FreeAgent user) and enumerates the payload that matters: URL and permission level. It distinguishes itself from sibling getters like freeagent_get_company or freeagent_get_contact by scoping to the authenticated user, and it even cites the underlying endpoint GET /v2/users/me.

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 parenthetical '(needed for freeagent_create_timeslip)' is an explicit dependency pointer that tells the agent when this tool must be called before another. There is no stated when-not or alternative, but for a zero-parameter identity lookup the routing 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by enumerating the returned payload (line items, totals, due and paid values) and mapping to the underlying endpoint GET /v2/invoices/:id, which an agent cannot infer from the annotations or the single-parameter 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?

A single front-loaded clause delivers the operation, the scoping key, and the returned content, with the API mapping appended compactly. No sentence is wasted.

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

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

For a one-parameter read tool with no output schema, the description correctly compensates by naming the return fields, and annotations handle the read-only safety signal. It falls short only on edge behavior such as not-found or permission errors, which is minor for this tool shape.

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

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

Schema coverage is 100%, and the schema already documents the parameter as 'The invoice's numeric id or full FreeAgent URL.' The description's 'by id or URL' simply mirrors that, adding no format examples or id-discovery guidance beyond the structured field. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Fetch a single invoice by id or URL') and adds what comes back (line items, totals, due and paid values). 'Single' implicitly contrasts with the sibling freeagent_list_invoices, but no sibling is named explicitly, which keeps this just below the top tier.

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

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

Usage is only implied: it fetches one invoice, so the caller must already hold an id or URL. There is no explicit statement of when to prefer this over freeagent_list_invoices or what to do when the identifier is unknown.

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

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

Annotations only declare readOnlyHint=true; the description adds genuinely useful behavior beyond that: the default time window (current year to date), the mutually exclusive input modes, the line items the report contains, and the underlying endpoint for traceability. It does not cover auth requirements or error/empty-period behavior, but for a simple read-only report this is solid 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?

One dense sentence with the report contents and default front-loaded, followed by a short endpoint tag. Nothing is padded, though the raw 'GET /v2/...' reference is marginal value for an agent that only needs selection and invocation cues.

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-required-parameter, read-only summary tool with no output schema, the description covers purpose, input modes, default behavior, and the shape of the returned figures. Missing only minor details such as error handling for invalid or future periods.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: that from_date/to_date and accounting_period are alternative ways to specify the same window, and what the no-parameter default is. Only the non-mixing constraint is left implicit.

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

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

States a specific verb and resource ('Profit and loss summary') and enumerates the report contents (income, expenses, operating and retained profit), so the agent knows exactly what data comes back. It is naturally distinct from the balance-sheet sibling, though it never explicitly contrasts itself with any sibling 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 phrase 'for a date range or an accounting period' implies the two parameter modes are alternatives, and the default ('current year to date') tells the agent what happens with no arguments. However, there is no explicit when-to-use guidance, no exclusion (e.g. that accounting_period and dates should not be mixed), and no routing to alternative reports.

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 safety is covered and the description's added value is limited to naming the returned content categories and the FreeAgent API path. It says nothing about ordering, horizon of 'upcoming', or whether amounts are settled vs. estimated.

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

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

Two short sentences with zero filler: the payload is described first, the backing endpoint second. Nothing is redundant or buried.

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

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

For a parameterless, read-only tool with no output schema, the description gives an agent enough to know what it will receive and that no inputs are required. Minor gaps remain around the time horizon of 'upcoming' and result ordering.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly signals a no-argument call by describing only the returned data.

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

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

States a specific verb (List) plus resource (upcoming tax deadlines and amounts due) and enumerates the categories covered (VAT, corporation tax, self assessment). This distinguishes it cleanly from sibling read tools like get_balance_sheet or get_profit_and_loss without opening any schema.

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

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

The description makes the use case evident — consult this for what tax obligations are coming and how much is owed — but never states when to prefer it over a sibling or any prerequisite (e.g., company context, date scoping). Usage is implied rather than specified.

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?

readOnlyHint=true already declares this is a safe read, so the description's main added value is noting that balances are returned. It does not describe pagination, rate limits, or response shape; with annotations carrying the safety profile, this is adequate but thin.

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 what is listed, followed by the follow-up tool and the underlying API endpoint. No filler.

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

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

For a simple read-only list tool with no output schema, the description conveys the resource and that balances are returned, plus the API path. It omits any mention of the view parameter's filtering role and the exact response 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 single view parameter is fully documented in the schema with an enum. The description does not mention the view filter at all, so it adds nothing beyond the schema—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?

States a specific verb (List) and resource (bank, credit-card and PayPal accounts) plus the returned data (current balances). It is clearly distinguishable from freeagent_list_bank_transactions, which it names as a separate 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?

Explains the workflow relationship to freeagent_list_bank_transactions by telling the agent to use an account's URL with that tool, which implies this must be called first. No explicit when-not guidance, but the context is clear for a simple listing 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, so the safety profile is covered. The description adds only the endpoint path, with no mention of pagination defaults, auth, rate limits, or result shape; it neither enriches nor contradicts 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 compact clauses: the action/scope is front-loaded and the endpoint reference follows. 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 an 8-parameter list tool with full schema coverage and no output schema, the description covers the essential purpose. It omits return/pagination behavior, but the schema supplies paging parameters, leaving only a minor gap.

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

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

Schema description coverage is 100%, so every one of the 8 parameters is already documented in the schema. The description's note that unexplained means 'not yet reconciled' merely repeats the schema's own enum explanation, adding no new meaning.

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

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

States a specific verb (List) and resource (transactions on one bank account), plus the underlying endpoint GET /v2/bank_transactions. It is clearly distinguishable from freeagent_list_bank_accounts, though it does not name that sibling explicitly.

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

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

"e.g. view=unexplained for what still needs reconciling" hints at the reconciliation use case, which implies a purpose context. However, there is no guidance on when to prefer this over other listing tools or any exclusions, so usage is only implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description adds the upstream endpoint (GET /v2/bills) and confirms that all filters are optional. It omits anything about pagination behavior, result size, or defaults, which matter for a list endpoint with 9 params.

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, front-loaded with the resource and filters, with the API reference trailing as a secondary detail. Nothing is padded, though the endpoint string adds little for tool selection.

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 parameter-rich list tool with no output schema, the description does not describe what comes back (fields, pagination envelope, totals) or the default page size. The schema fully covers inputs, so the gap is limited but real.

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 every parameter including the 'view' enum, date formats, and nested_bill_items is already documented in the schema. The description only restates the broad filter categories and adds no syntax or semantics beyond them.

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

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

States a specific verb ('List') and resource ('supplier bills'), and the parenthetical '(purchases)' disambiguates it from sales invoices among the many list_* siblings. It does not, however, name any sibling tool to route against, so an agent must infer the bills-vs-invoices distinction on its own.

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

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

The description conveys the available filter axes (date range, contact, project, status) which implies when the tool is useful, but gives no when-to-use vs. when-not guidance, no prerequisites, and no hint about which filter combination is typical. Usage is implied rather than prescribed.

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 safety is covered. The description adds useful context that results include account balance and identifies the underlying endpoint (GET /v2/contacts), but says nothing about pagination behavior or default result window beyond what the schema provides.

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 plus an endpoint reference, front-loaded with the core action and resource. No filler; every clause earns its place.

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

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

For a read-only list tool with a fully documented schema, most of what is needed is present. However, there is no output schema and the description only hints at one returned field (account balance), leaving the shape of each contact record largely unspecified.

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

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

Schema description coverage is 100% with detailed enum descriptions (view, sort) and pagination bounds, so the schema carries the parameter burden. The description adds no parameter meaning beyond that, making baseline 3 appropriate.

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

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

States a specific verb and resource ('List contacts (clients and suppliers)') and adds the returned field ('account balance'), which separates it from sibling get_contact / create_contact / update_contact. It does not explicitly name a sibling or scope limitation, so it falls short of a 5.

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

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

No statement of when to use this versus get_contact (single record), or when to prefer a filtered view. Usage is only implied by the verb 'List'. The schema's view enum hints at filtering scenarios, but the description itself provides no 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 the description's 'FreeAgent: GET /v2/expenses' is consistent with that. It adds no behavioral context beyond the annotation, such as pagination behavior, default ordering, or rate limits.

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, front-loaded with the purpose and resource, with no filler. The API endpoint reference is compact and clearly separated.

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 documentation and no output schema, the description covers what the tool returns (expense claims) and its filter scope. Only return shape and paging defaults are left implicit, which the schema largely covers.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema with formats and defaults. The description only restates the date-range and project filters, adding no syntax or behavioral detail beyond the schema.

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

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

The description states a specific verb and resource ('List expense claims'), and usefully scopes what counts as an expense (out-of-pocket spending and mileage). It doesn't need to differentiate from a sibling since no other expense-listing tool exists, but it also makes no explicit contrast.

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 notes the listing is 'optionally by date range or project,' which hints at when the filters apply, but gives no guidance on when to prefer this tool over alternatives or any exclusions. Usage 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?

The readOnlyHint=true annotation already establishes the safe-read profile, so the bar is lower. The description adds that results can be scoped by contact/project/status, which is useful context, but says nothing about pagination behavior, default result size, or the shape of returned 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?

Two short sentences, front-loaded with the action and scope, followed by the underlying endpoint reference. Nothing is wasted and the key information comes first.

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 8 optional parameters and no output schema, the description is adequate but thin: it does not describe the paginated return structure or default page size, which an agent would need since no output schema exists. For a filtered-list tool it is minimally sufficient.

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

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

Schema description coverage is 100% across all 8 parameters, so the schema fully documents page, sort, view, contact, project, per_page, updated_since, and nested_invoice_items. The description adds no syntax or format detail beyond what the schema already provides, so the baseline of 3 is correct.

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

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

The description states a specific verb+resource ('List sales invoices') and adds scope qualifiers ('optionally for one contact or project, filtered by status'). This distinguishes it from get_invoice and create_draft_invoice, but it never explicitly names those siblings or clarifies what a list returns vs. a single get.

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

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

Usage is only implied: the mention of filtering by contact, project, or status hints at when the tool is useful, but there are no explicit when-to-use/when-not statements or named alternatives (e.g., get_invoice for a single invoice).

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds nothing behavioral on top of that — no pagination behavior, no default result size, no rate-limit or ordering notes. The only extra content is the raw API endpoint mapping, which is documentation plumbing rather than 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?

Extremely tight — two short clauses with the operation and scope front-loaded, and no filler. The trailing endpoint reference ("FreeAgent: GET /v2/projects") is marginally useful for docs lookup but is not something an agent needs to call the tool.

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

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

For a read-only list tool with no output schema, the description should at least signal pagination or result shape; it instead relies entirely on the schema's page/per_page descriptions. Given full schema coverage and a readOnly annotation, this is adequate but leaves clear gaps about what the listing returns and how paging behaves.

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 all six parameters (page, per_page, sort, view, nested, contact) are fully documented in the schema. The description's "optionally for one contact" merely restates the contact parameter, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List projects") and adds the scope qualifier "optionally for one contact", so the operation is unambiguous. It does not distinguish itself from the many sibling list_* tools (list_tasks, list_contacts, list_invoices) beyond the resource name, so it falls short of a 5.

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

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

The phrase "optionally for one contact" hints at a filtering scenario but never states when to use this tool versus alternatives, nor any prerequisites (e.g., that no filters returns everything, or how it relates to other project/task lookups). No when-not guidance is present.

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?

readOnlyHint=true already declares the safety profile, so the description goes further by disclosing the underlying API endpoint (GET /v2/tasks), the fact that billing rates are returned, and the workflow dependency on task URLs for timeslip creation. Pagination behavior is left to the schema, which is a minor omission for a read-only list.

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

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

Three compact sentences, front-loaded with the purpose, then the dependency, then the endpoint. Every clause conveys something the agent can act on and there is no filler.

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

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

With no output schema, the description usefully flags the key returned attribute (billing rates) and the resource path. Combined with 100%-covered input schema and readOnly annotations, an agent has enough to call it correctly; only explicit pagination/return-shape framing is absent.

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

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

Schema description coverage is 100%, so all six parameters (page, sort, view, project, per_page, updated_since) are already documented in the schema. The description only echoes the project filter ('optionally for one project') without adding format or behavioral detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('List project tasks'), adds the notable return attribute ('with their billing rates'), and notes the optional single-project scope. It also ties itself to a downstream sibling (freeagent_create_timeslip) via the task URL, giving some sibling differentiation, though it doesn't contrast with freeagent_list_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?

'optionally for one project' signals the filtering use case, and 'A task's URL is needed for freeagent_create_timeslip' tells the agent exactly when this call is a prerequisite. No explicit when-not or alternative-listing guidance, 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 declare readOnlyHint=true, so the safety profile is covered. The description adds the business meaning of view=unbilled and the underlying GET /v2/timeslips endpoint, but says nothing about pagination behavior, default page size, or what ordering results come back in.

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 dense sentence plus a one-line endpoint reference, with the filterable dimensions and the unbilled view front-loaded. No filler.

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

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

For a read-only list tool with 10 optional params, full schema coverage and no output schema, the description plus schema give an agent enough to call it correctly. It falls just short of complete by omitting pagination/ordering context that a listing tool would benefit from.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema, including defaults and formats. The description's mention of date range, user, task, project and view maps to parameters but adds no syntax or semantics beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb+resource ('List logged time') and enumerates the filterable dimensions, so it is immediately distinguishable from the sibling freeagent_create_timeslip, which writes a timeslip rather than listing them.

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 when the tool applies by listing filters and calling out view=unbilled for 'time not yet invoiced', which is genuine context. However, it never states when to prefer this over alternatives or any preconditions, so usage must be inferred.

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 offer destructiveHint=true, a bare safety flag. The description adds genuinely useful behavior: the operation is a partial patch, so unspecified fields survive, and the Hidden status is reversible with Active — context that materially softens and clarifies the destructive hint. It doesn't cover auth or failure modes, keeping it below 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?

One sentence plus two tight clauses; the partial-update rule is front-loaded, then the status behavior, then the endpoint. No filler and nothing an agent needs is buried.

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

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

For a 21-parameter mutation with a single required param and no output schema, the description covers the two riskiest pieces an agent must know — patch semantics and the reversibility of hiding. It omits any hint about the required `contact` identifier or error behavior, so it is strong but not exhaustive.

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% across 21 parameters, so the schema already carries the field semantics; baseline is 3. The description adds only marginal value by explaining what status=Hidden does (reversible with Active) beyond the schema's 'Hide or unhide the contact.'

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

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

States a specific verb and resource ('Update fields on an existing contact') plus the patch semantic 'only the fields you pass change', which cleanly separates it from freeagent_create_contact and the read-only freeagent_get_contact. The API endpoint reference (PUT /v2/contacts/:id) reinforces the exact 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?

Makes the partial-update contract explicit ('only the fields you pass change') and notes that status=Hidden is the hide path, reversible via Active. It never names an alternative tool or states when not to use it, so it falls short of a 5.

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