taxapp.nz

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description adds genuinely non-derivable behavior: a same-name contact is answered rather than duplicated, a contact lacking the requested type is refused, and the return value is the saved contact with its organisation name.

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 purpose and examples, but the middle sentences are dense run-ons chained with colons and dashes that require careful parsing. Most sentences carry unique information, so little is wasted, though it could be tightened.

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 12-parameter creation tool with no output schema, the description supplies the return value, the permission precondition, the duplicate/refusal behavior, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the cross-field rule (business name vs person first_name/last_name) and the duplicate-handling semantics for allow_duplicate beyond what the schema field text states. It does not, however, add format constraints for the contact methods or address fields.

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

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

States a specific verb and resource ('Adds a contact') and immediately characterizes the entity (person or business the organisation deals with) with concrete examples. It distinguishes itself from update_contact and list_contacts by name, so an agent can route correctly without opening either schema.

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

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

Explicit routing: 'Check with list_contacts first', and the condition that selects update_contact ('add the type to that contact with update_contact instead'). It also states the precondition that the connection must permit adding records, verified via list_organisations.

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=false, idempotentHint=true and destructiveHint=false, but the description adds real context beyond them: duplicate-label requests resolve to the existing active type rather than erroring, the operation is permission-gated per organisation, and the response is the saved type. It does not mention failure modes or side effects on contacts already using other types, so it falls just short of exhaustive.

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

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

Four sentences, front-loaded with the purpose before prerequisites and the return value. Every sentence carries information, though the phrasing is slightly roundabout ("of the organisation's own", "the connection may add and change records") where terser wording would read faster.

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 usefully states that the answer is the saved type. Combined with the dedupe behaviour and permission gating, an agent has what it needs to call this correctly; only the shape of the returned type remains 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%, so every parameter (label, is_customer, is_supplier, allow_duplicate, organisation_id) is already well documented in the schema itself. The description only reinforces the label-duplication case and the organisation permission rule; it adds no syntax, format or default 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?

The description gives a specific verb and resource ("Adds a contact type") plus the scope that distinguishes it from siblings: it is for the organisation's *own* types, for contacts that no existing type describes. The concrete example ("Body corporate") removes any ambiguity about what a contact type is, and it is clearly separable from list_contact_types and update_contact_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?

It states an explicit pre-check ("Check list_contact_types first") and explains the consequence of skipping it (an active type with the same label is returned instead of created). It also names a hard prerequisite — the connection must be able to add/change records for the organisation, discoverable via list_organisations — which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds real behavior: the tool only works where the connection 'may add and change records' (a permission gate not encoded in annotations), and it discloses the response ('the saved record with its organisation's name') plus the instruction to report back where the record landed.

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 and dependencies, and nearly every clause carries information. It loses a point for one dense semicolon-heavy paragraph with an awkward mid-sentence capital ('; When the person's words...') that mixes user-facing scripting into the tool definition.

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 11-parameter mutation tool with no output schema, the definition covers prerequisites, every id source, ambiguity handling, permission gating, and the return value. Nothing an agent needs 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?

Schema coverage is 100%, so 3 is the baseline. The description goes beyond it by explaining the consequence of liable_contact_ids ('decides whose figures it reduces') and that a jointly owned property's cost is shared by every named owner, plus how to resolve the expense type and account by name or IRD line.

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 up front ('Adds one expense record: a bill or cost'), and the scope is unambiguous (a single record, not a list or update). The expense/income/update siblings are separable from the resource name alone without opening a schema.

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

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

Explicit routing guidance: supplier comes from list_contacts or create_contact, account from list_expense_accounts, property from list_properties, type from list_choices, and organisation eligibility from list_organisations. It also states the disambiguation policy ('show them the closest and ask which they mean; never guess an id') and the connection-permission precondition.

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 cover safety (readOnly=false, destructive=false) and idempotency, but the description adds real behavior: duplicate-name handling, IRD tagging consequence, and an external Xero sync side-effect beyond the closed-world annotation. It stops short of describing rate limits or error 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?

Front-loads the purpose, then sequences duplicate-check, IRD tagging, Xero sync, and permission constraints so each sentence carries distinct actionable information. Slightly dense but no wasted sentences.

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

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

For a mutation tool with no output schema, the description closes the key gaps: it names the return value ('the saved account'), the duplicate behavior, the external side-effect, and the permission precondition. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults. The description reinforces the ird_line and organisation_id concepts but adds no syntax or format beyond what the schema provides, 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 (Adds) and resource (expense account), then defines it concretely with an example ('a category expenses are filed under, such as “Pest control”'). It clearly distinguishes itself from the list_/update_ 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?

Explicitly tells the agent to check list_expense_accounts first because an active duplicate is answered instead, and restricts use to organisations where the connection may add records (per list_organisations). Conditions and alternatives are named, not 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?

Goes well beyond the annotations: it discloses the duplicate-handling contract behind allow_duplicate, the permission gate ('only for an organisation where this connection may add and change records'), the tax calculation behaviour (GST, KiwiSaver, ACC, income tax, take-home derived from the received amount), and what to report back to the user. These are behavioural facts annotations cannot express.

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 paragraph that front-loads purpose before branching into type-specific rules and workflow guidance. Almost every sentence carries distinct information, though the id-resolution and reporting instructions could be tightened without loss.

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 11-parameter write tool with no output schema and only basic annotations, the description covers input resolution, permission preconditions, duplicate semantics, the derived tax computation, and the shape of the returned record ('the saved record with its organisation's name'). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by adding cross-parameter conditional logic (which ids are relevant per income_type) and the workflow for obtaining each id from its list_* tool. It slightly overlaps the schema's own 'Commission only' / 'Tenant reimbursements only' notes, so not a 5.

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

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

Opens with a precise verb+resource ('Adds one income record: money the organisation received') and immediately disambiguates the three income_type variants, each with its own payer/payee semantics. An agent can distinguish this from create_expense, create_contact and update_income without opening a schema.

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

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

Explicitly states prerequisites and routing: match income type with list_choices, resolve every id via list_contacts/list_properties/list_expenses, never guess an id, ask the user when ambiguous, add a missing payer via create_contact, and only use where the connection permits adds/changes (list_organisations). It names both the alternatives and the conditions that select them.

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

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

Annotations declare idempotentHint and destructiveHint=false, but the description adds context they cannot carry: the rental-module prerequisite, the per-connection write permission constraint, the duplicate-resolution behavior (a match on every given part is returned instead), and the shape of the reply. It also explicitly discloses that the returned record is the saved property with its organisation's name, which is valuable given there is no output schema.

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

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

The purpose is front-loaded and every sentence carries information (prerequisites, duplicate check, owner sourcing, follow-up call). It is dense, though, with several long chained clauses, and a few statements restate schema content that the agent already receives.

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 5-parameter creation tool with no output schema, the description covers the full picture: prerequisites (module, permissions, org scoping), duplicate handling, owner sourcing and pre-creation of contacts, the return value, and the natural follow-up call. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the agent to ask the person who owns the property and in what shares rather than defaulting, and that the ownership split drives income/expense reporting. The mechanics of shares (sum to 100, 2 decimal places) remain in the schema, so this is a 4 rather than a 5.

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

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

The first sentence names a specific verb and resource ('Adds a rental property') and immediately scopes it by what the record contains: label, address, and owner shares. It is trivially distinguishable from sibling create_* tools (create_tenancy, create_contact) because it names them as separate steps rather than overlapping 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?

Explicit when-to-use and dependency routing: check list_properties first to avoid duplicates, source owners from list_contacts (contact type property-owner), use create_contact for a new owner, add tenancies afterwards with create_tenancy, and only use it where the rental module is enabled and the connection may write. Naming the alternative for each sub-task leaves nothing to inference.

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

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

Annotations only cover the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds high-value behavior the annotations cannot: this tool sends email to an external party, requires organisation-owner privileges, requires a write-enabled connection, and should be confirmed with the user first. It also states the return value ('the saved schedule with the date it first goes'), which is absent from annotations and there is no output schema.

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

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

The purpose is front-loaded and each subsequent sentence carries a real constraint (permissions, connection scope, confirmation, sourcing, return value) rather than filler. It runs slightly long at six sentences for a description whose schema already covers most field-level detail, but nothing is redundant.

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

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

For a 16-parameter mutation tool with no output schema and no field-level gaps in the schema, the description covers the non-schema essentials: authorization level, connection permission requirement, prerequisite lookups, the external-email side effect, and the shape of the response. An agent has what it needs to call this correctly or to decline.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds the non-obvious constraint that recipient and cc contacts each need an email address, and ties report_key/recipient/cc back to their source list tools. It does not add anything about the timing parameters (day_of_week, day_of_month, send_time, one-off dates), which remain schema-only.

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

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

The opening sentence gives a specific verb and resource — it creates a recurring or one-off emailed report schedule — which an agent can act on immediately. It does not explicitly distinguish itself from the sibling update_scheduled_report or send_scheduled_report_now, so the create-vs-modify-vs-send boundary must be inferred.

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?

Explicit prerequisites are stated: only an organisation owner can see or set up schedules, the connection must be permitted to add/change records in that organisation, and the recipient/cc contacts must each have an email address. It also names the upstream tools (list_scheduled_report_types, list_contacts, list_organisations) that must be called first, plus a human-confirmation step before sending mail outside the app.

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=false, idempotentHint=true and destructiveHint=false, but the description goes further: it names the exact dedupe key ('same property, tenants, room and start date is answered instead of added'), states the module must be switched on, states the organisation permission requirement, and names the return value. These are operational facts not derivable from 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?

Dense but front-loaded: the first sentence defines the resource, the next two cover dependencies, then duplicate handling, formats, gating and the return. Every sentence carries a distinct operational fact with no filler or restatement of the tool name.

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 15-parameter mutation tool with no output schema, the description closes every gap an agent needs: what is created, what it depends on, dedupe behavior, module/permission gating, units and date format, what is returned, and the natural next step (create_income). Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters including formats, enums and defaults. The description reinforces dates as New Zealand yyyy-MM-dd and money as NZD, but adds little parameter-level meaning beyond what the schema carries. Baseline 3 applies when the schema does the heavy lifting.

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?

Opens with a specific verb+resource ('Adds a tenancy') and immediately defines the domain object ('one or more tenants renting a rental property, or a room in it, from a start date at a weekly rent, with its bond'). An agent can distinguish this from update_tenancy, create_property and create_contact 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?

Explicitly states prerequisites and the alternatives to call first ('The property comes from list_properties (add a new one with create_property) and each tenant is a contact of type tenant from list_contacts (add a new tenant with create_contact first)'). It also names when-not conditions: the dedupe rule, the module requirement, and the permission gate via list_organisations.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial value: the tax-year scoping, newest-first ordering, per-row contents (suggested record type/contact), the summary counts (to process/reconciled/skipped/ignored), and the NZD currency. That is rich behavioral context beyond the structured fields.

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 what the inbox is, then the read-only clarification and alternatives. Two sentences are dense but every clause carries information; only the currency note feels slightly tacked-on.

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 carries the return-shape burden and does so: ordering, per-row fields, and summary counts. Combined with 100% schema coverage and clear annotations, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit, offset, and organisation_id are fully documented in the schema. The description adds no parameter detail, so baseline 3 applies.

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

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

States a specific resource (the bank inbox) with precise scope: bank-feed transactions 'still waiting to be recorded' for the current NZ tax year, sorted newest first, with suggested record type and contact. This content-level specificity naturally distinguishes it from siblings like get_reconciliation_status or list_expenses.

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?

Clearly frames this as a read-only tool and names the follow-up alternatives explicitly ('to add a record for one, use create_expense or create_income'). It lacks an explicit when-not for reading alternatives (e.g., vs get_reconciliation_status), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuine behavioral value by enumerating what the record contains (amount in NZD, liability people, reconciliation status), which matters because there is no output schema. It does not mention error behavior for a missing id, keeping it from 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?

A single front-loaded sentence that leads with the core purpose before the field enumeration. The long list of fields is slightly listy but earns its place since no output schema exists to convey the return shape.

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

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

For a read-only single-record fetch with no output schema, the description adequately covers both the input source (id from list_expenses) and the expected return contents. Only the failure mode for an unknown id is absent, which is a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including the conditional organisation_id rule. The description reinforces that the id comes from list_expenses but adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb ('Get'), resource ('expense record'), and scope ('in full, by its id'), and distinguishes itself from the sibling 'list_expenses' by naming it as the source of the id. An agent can tell this single-record fetch apart from the list tool without opening either schema.

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

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

The phrase 'by its id from list_expenses' establishes the workflow context for when to call this tool (after listing expenses) and where the required id comes from. It stops short of an explicit exclusion such as 'use list_expenses when you do not already have an id', so it is clear context without full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description usefully adds domain scope (only New Zealand tax years) and currency (NZD), but says nothing about granularity, how many years are returned, or how partial/current years are handled.

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 sentences, front-loaded with the core resource and scope, then the optional narrowing behavior and the currency note. No filler and nothing restated from the name or annotations.

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?

Three optional parameters and no output schema, so the description carries some burden for the return shape; it implies year-by-year income totals and NZD but does not state the structure. Combined with the absence of any alternative-tool routing, it is adequate but leaves real gaps.

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

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

Schema description coverage is 100%, with the enum for income_type and sourcing hints for organisation_id/contractor_contact_id fully documented in the schema. The description only restates that the filters are optional and single-valued, adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ('Income totals across past New Zealand tax years') and adds the agent-facing purpose ('to compare years or see a trend'), which cleanly separates it from per-record siblings like get_income_record or list_income. It stops short of naming any sibling explicitly, so it is clear but not sibling-differentiating at the top level.

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?

'To compare years or see a trend' implies the use case, and 'Optionally for one income type or one contractor' hints at the narrowing filters. There is no explicit when-not guidance or mention of the alternative tools (get_income_record, list_income, get_tax_summary) an agent should pick instead.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing what comes back in the record (amount in NZD with GST, indicative deductions, reconciliation state with the bank), which is the kind of detail annotations cannot carry.

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

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

A single sentence with the purpose front-loaded, followed by the field inventory. The trailing field list is long but each item earns its place given there is no output schema; only minor tightening would be possible.

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 field enumeration is what makes the return shape knowable, and it covers the record thoroughly. The only missing piece is any hint about error behavior when an id is invalid or belongs to another organisation.

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 income_id and organisation_id are already documented in the schema. The description reinforces the id provenance ('from list_income') but says nothing about organisation_id or the single-vs-multi-organisation conditional, so baseline 3 is appropriate.

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

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

States a precise verb+resource (retrieve one income record by id) and enumerates the exact fields returned, which distinguishes it cleanly from list_income and from the sibling get_expense_record. It also anchors the id source to list_income so the agent knows the retrieval path.

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

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

The phrase 'by its id from list_income' implies the precondition that you must first have an id from a listing call, which is useful usage context. However, it never says when to prefer this over siblings like get_income_history or get_expense_record, and it names no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful domain context: money is in NZD and each scope has defined cost/income meaning. It does not disclose anything about the shape of the result (line items, totals, per-period breakdown), which matters given there is no output schema.

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

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

Two sentences, zero filler, with the core resource and currency stated up front and the exclusion routed in the second sentence. 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 read-only report tool with fully documented parameters and no output schema, the description explains what each scope computes and the currency, which is enough to call it correctly. The main residual gap is that it never says what the returned report looks like or how it is structured.

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

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

Schema description coverage is 100%, so the baseline is 3; scope, tax_year, organisation_id and contractor_contact_id are all richly documented in the schema itself. The description's scope definitions duplicate the enum descriptions rather than adding new usage 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 resource (profit and loss) with explicit scope (one New Zealand tax year) and enumerates the two supported scope variants, defining each ('commission income less the costs of their work' vs 'the household's income and costs'). It also names the sibling to avoid (get_rental_report), so an agent can distinguish it from other report tools without opening a schema.

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

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

Explicitly routes rental-property questions to get_rental_report, which is a genuine when-not-to-use rule. However, it gives no guidance on when commission vs household is the right call beyond the parenthetical definitions, and no prerequisites or ordering relative to other report tools (e.g., tax summary).

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond them by clarifying 'Counts only; reconciling is done in the taxapp app' — telling the agent this tool cannot mutate anything and where the write path actually lives.

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

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

Two tight sentences with the core purpose front-loaded and the key constraint ('counts only') carried in the second. The parenthetical defining reconciliation is arguably extra, but it aids disambiguation and costs little.

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

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

No output schema exists, yet the description communicates the return shape as counts of reconciled vs still-to-do, which is enough for a read-only status tool. Notes on pagination or exact count fields are absent but not essential here.

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

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

With 100% schema description coverage, both tax_year (including the NZ year-ending convention and default) and organisation_id (when required vs optional) are fully documented in the schema. The description adds no parameter detail 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 with scope: 'how far bank reconciliation has got for one New Zealand tax year'. It even parenthesizes what reconciliation means and specifies the output is counts, which is enough to separate it from the sibling listing tools like get_bank_inbox.

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

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

Usage is implied (checking progress of reconciliation within a tax year) but the description names no alternative and gives no explicit when-to-use or when-not-to-use condition, e.g. versus get_bank_inbox or get_tax_year_overview.

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, idempotentHint, and non-destructive, so the safety profile is covered. The description adds substantive context beyond that: the report is computed per property, apportioned across owners by ownership share, and denominated in NZD. It stops short of stating permissions or behavior when multiple organisations are in scope, which the schema covers instead.

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 that front-loads the resource and its purpose, with the IR3R framing and currency note earning their place. It is readable and waste-free, though the sentence is long enough that a second shorter sentence would aid scanning.

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 carries the burden of explaining the return value, and it does so: income less deductible expenses, per property, apportioned by ownership share, in NZD. Nothing critical to invoking the tool is missing, though it does not describe behaviour under ambiguous multi-organisation connections.

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 parameter docs are strong (tax-year naming convention, id sources, when organisation_id is required). The description adds only indirect semantics — that results split per property and per owner — which does not extend the parameters themselves. 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 names a specific resource and scope: rental profit and loss for one New Zealand tax year, formatted for the IR3R return, broken down per property and per owner share. That is far more than a restatement of the title. It does not, however, explicitly distinguish itself from siblings like get_profit_and_loss or get_tax_summary, so an agent must infer the boundary from the 'rental' qualifier.

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

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

Usage is implied rather than stated: 'ready for the IRD rental return (IR3R)' signals when this tool is the right one. But there is no explicit when-to-use versus get_profit_and_loss, get_tax_summary, or get_tax_year_overview, and no exclusions or prerequisites are given.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile needs no restating. The description adds genuinely non-annotated context: the module must be enabled and all money is denominated in NZD. It stops short of stating caching or freshness behavior, but this is meaningful added 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?

Front-loaded with the resource, then a compact return-content enumeration followed by two short factual sentences on currency and prerequisite. The first sentence is long but every clause enumerates a distinct output field, so little 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?

There is no output schema, so the description must carry the return shape, and it does: opening balance, monthly planned vs saved, IRD/ACC payments, projected tax/ACC levy, amount still due, and whether savings are ahead. Combined with currency and the module prerequisite, nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so tax_year (with its end-year convention) and organisation_id (with its required-when-multi-org rule) are already fully documented. The description only echoes the tax-year scope and adds no format or syntax 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+resource (the savings plan for one NZ tax year) and then enumerates exactly what the plan contains: opening balance, monthly planned/saved amounts, IRD/ACC payments, and taxapp's tax/ACC workings. This is clearly distinguishable from sibling update_savings_plan and copy_savings_plan_from_previous_year 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?

It discloses a real prerequisite ('Needs the savings module switched on'), which tells the agent when the call will fail, but it gives no guidance on when to read the savings plan versus get_tax_summary or get_tax_year_overview, nor does it name any alternative. Usage is only implied by the domain.

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 read-only, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful context beyond that: the calculation methodology, that figures are indicative rather than an IRD assessment, and that values are in NZD. It omits whether results are cached or how the current-year default resolves.

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 resource and scope before the calculation detail and the disclaimer. Dense but almost every clause carries information; the parenthetical breakdown of income components is the only mild indulgence.

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 does the work of describing the return shape (income, deductions, tax/ACC/IETC breakdown), the currency, and the caveat that these are estimates. All three parameters are optional and fully documented in the schema, so nothing an agent needs is missing.

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

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

Schema description coverage is 100%, and the schema fully documents each optional parameter, including the tax-year naming convention and when organisation_id/contractor_contact_id become required. The description adds only a marginal gloss ('a person's'), 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 ('a person's tax summary for one New Zealand tax year') and then enumerates exactly what it contains: income components, deductions, indicative income tax, ACC levy, and IETC. That level of specificity (including the bracket-stepping order) clearly separates it from siblings like get_profit_and_loss and get_tax_year_overview.

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 hints at context ('planning figures to help the person file, not an IRD assessment'), which implies when the output is appropriate, but it never states when to choose this tool over get_tax_year_overview or get_income_history. Usage must be inferred from the described contents rather than being 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine domain context beyond the annotations: the fiscal-year definition (1 April–31 March), the reporting currency (NZD), and the fact that figures are as-of-now with drill-down records available.

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 resource and its scope, then a short drill-down routing sentence. No filler; every clause (period, breakdown dimensions, currency, next step) 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, zero-required-parameter aggregate with no output schema, the description covers what is returned (totals by type, currency) and how to drill down. It could be more complete by clarifying how this differs from get_tax_summary/get_profit_and_loss, its closest siblings.

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%, including the tax-year naming convention and the single/multi-organisation rule, so the schema carries the parameter burden. The description reinforces the organisation scoping and the NZD unit but adds no syntax or format detail beyond what is already documented.

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 resource and scope: the organisation's totals for one NZ tax year, broken down by income and expense type. It clearly frames itself as the high-level entry point versus the list_* record tools, but does not differentiate itself from similarly-named aggregate siblings such as get_tax_summary or get_profit_and_loss.

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 an explicit trigger ('how is this year going') and a concrete alternative path ('use list_income or list_expenses for the records behind a figure'), which is real routing guidance. It stops short of telling the agent when to prefer get_tax_summary or get_profit_and_loss instead.

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

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

Annotations already cover the safety profile (readOnly=true, idempotent=true, openWorld=false, destructive=false), so the bar is lower; the description still adds real value by disclosing the return shape (value vs label duality) and the exact scope of what is listed. It does not mention ordering, completeness, or paging, but for a static choice list those are minor.

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 what is returned, then how to use it; two sentences, each earning its place. The first sentence is long and comma-heavy, straining readability, which keeps it out of 5 territory, but nothing is redundant.

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

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

No output schema exists, so the description carries the return-value burden — and it does so by explaining that results are value/label pairs and what categories are covered. An agent has enough to call it and interpret the response. Minor gap: it doesn't state the shape of the collection itself (list length, 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?

Only one parameter (organisation_id) and schema description coverage is 100%, so the schema already explains the singleton-vs-multi-org behaviour fully. The description adds nothing about it. Baseline 3 applies when the schema does all the work.

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 resource — the value/label pairs that type fields of new records take — and enumerates the carried categories (income types, expense types, commission under the org's word, contact types). It implicitly ties itself to the 'adding tools' (the create_* siblings), so an agent can tell it apart. The vague tool name 'list_choices' is rescued by the description, but the description never contrasts this explicitly against the many list_* siblings it sits beside.

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 when-to-use guidance ('match what the person says ... to a value') with real examples ('my dental income', 'she is a tenant'), plus a fallback rule: when nothing matches, show labels and ask. This is clear operational context. It stops short of naming a specific alternative tool for the no-match case, so it is not a 5.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the safety profile is done. The description adds genuinely non-derivable behavior: IRD and bank account numbers are never included in results, and pagination is capped at 500 with a defined response shape (items, total, offset, limit). It does not describe ordering or error behavior, but the added 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?

It is one dense, front-loaded block covering resource definition, exclusions, id usage, ambiguity handling and pagination with no filler sentences. The long run-on structure across multiple concerns slightly hurts scanability, but 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?

There is no output schema, and the description compensates by naming the returned fields and the pagination envelope (items, total, offset, limit). Combined with the 100%-covered input schema and full annotation set, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds only marginal meaning ('search by part of the name', the 500-page cap), repeating the schema's own guidance on paging and default limit. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Finds the organisation's contacts') and then defines the resource concretely (suppliers, tenants, contractors, property owners, landlords, accountants) with the fields returned. This clearly separates it from create_contact, update_contact and list_contact_types in the sibling set.

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

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

Gives explicit operational guidance: use the returned ids with other tools, search by part of the name when a person names a contact, and when matches are ambiguous or absent show the closest and ask rather than guessing an id. This is when-to-use plus a when-not behavior (never guess an id) that an agent must follow.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real substance beyond that: it discloses that both system and custom types are returned, that inactive types are included ('active or not'), and that supplier/customer classification is surfaced.

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 front-loaded sentence that lists contents first and the downstream action last; every clause carries information. It is slightly long and could be split, but 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 carries the burden of describing returns and does so well: ids, values, labels, built-in vs custom, active flag, and buy-from/sell-to classification. It does not mention ordering or pagination, which is a minor remaining gap for a list tool.

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

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

Schema description coverage is 100% with a single optional organisation_id, so the schema already explains the 'omit when single organisation, required when multiple' rule. The description adds nothing about the parameter, which is the correct baseline when the schema does the work.

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 ('Lists the organisation's contact types') and immediately qualifies the scope: built-in types every organisation has plus custom ones, with their ids, values and labels. This distinguishes it from list_contacts and list_choices without the agent needing to open a schema.

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

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

Explicitly routes the agent forward: 'Use the ids to change a type with update_contact_type,' which names the downstream sibling and the reason to call this tool. No explicit statement of when not to use it versus create_contact_type or list_choices, so it falls short of a full 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by disclosing the returned fields (ids, names, accounting code, IRD line) and steering account creation elsewhere, though it says nothing about auth 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?

Front-loads the core purpose in the first clause and follows with concrete usage detail. It is slightly long, but each sentence (return fields, matching heuristic, creation path) earns its place.

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

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

With no output schema, the description correctly carries the burden of describing return values, and it also explains when to call the tool and how to handle ambiguous matches. For a low-complexity, single-parameter list tool, nothing essential is missing.

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

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

Schema description coverage is 100% and the single organisation_id parameter is fully documented in the schema. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Lists) and resource (expense accounts), then clarifies what they are (categories expenses are filed under) and what each row contains (ids, names, accounting code, IRD return line). An agent can immediately distinguish this from siblings like create_expense_account or update_expense_account.

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

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

Gives explicit when-to-use guidance: every new expense needs an account, so match the person's description to an active account's name or IRD line and ask for clarification when ambiguous. It also implies when-not-to-use (new accounts are added in the taxapp app), though it does not name sibling alternatives explicitly.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value beyond that by disclosing pagination semantics ('pages of up to 500') and the response envelope (items, total, offset, limit), which matters because there is no output schema.

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

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

Purpose is front-loaded and the three-beat structure (what it lists, what a record holds, how to filter, how it pages) is logical. The second sentence is a long dense enumeration, but since there is no output schema those field details earn their place.

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

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

With no output schema, the description compensates by describing record fields and the pagination envelope, and all ten parameters are documented in the schema. The only gap is that it does not address the multi-organisation requirement beyond the schema, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters in detail, including the tax_year convention and expense_type enum values. The description only restates the filterable dimensions at a high level and adds 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 ('Lists') and resource ('expense records') and then enumerates what each record contains (date, due date, supplier, type, account, amount in NZD, property, liable people), which is genuinely informative. It does not, however, differentiate itself from the singular sibling get_expense_record or from list_income, so an agent gets no explicit routing hint.

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?

'Filter by tax year, type, account, contact, property or dates' implies when the tool is useful, but there is no explicit when-to-use/when-not statement and no alternative tool is named. Usage must be inferred from the available filters 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the lower bar applies. The description still adds real context: pagination is capped at 500 per page, the response carries items/total/offset/limit, amounts are received-and-in-NZD, and commission records include GST plus indicative KiwiSaver, ACC levy, income tax and take-home. It omits any note on auth or organisation scoping, which the schema handles instead.

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

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

Purpose and record anatomy are front-loaded, then filtering, then pagination — a sensible order with no filler. The middle sentences are dense and run together, but every sentence carries distinct information.

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

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

For a 0-required, 11-parameter list tool with no output schema, the description usefully describes both what a returned record contains and the envelope shape (items, total, offset, limit), which the agent otherwise could not know. Remaining gap is guidance on alternatives and default/selection behaviour across the many optional filters.

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 every one of the 11 parameters documented in the schema (including the enum values and the organisation_id conditional requirement), so baseline 3 applies. The description restates the filterable fields but adds no syntax, format or interaction 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?

Opens with a specific verb+resource ("Lists income records") and then defines what one record is (an amount received with date, payer and income type), so the agent knows exactly what domain object it is paging through. It does not explicitly differentiate itself from get_income_record, get_income_history or list_expenses, 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?

"Filter by tax year, type, contact, contractor, property, tenancy or dates" implies when this tool is appropriate (bulk retrieval with filtering), but there is no explicit when-not or named alternative, and nothing tells the agent when to prefer get_income_record over this.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context by enumerating the returned fields (id, name, role, add/change permission, enabled features, NZ tax year), which the annotations cannot convey. It stops short of noting empty/error cases, so a 4 rather than 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?

Front-loaded with the verb and resource, then the definition, then the return fields, then the routing instruction. The mid-sentence enumeration of return fields is dense, but every clause carries unique information; only the parenthetical feature examples could be trimmed.

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 carries the full burden of describing return values and does so thoroughly, plus it supplies the critical cross-tool ordering rule. Nothing an agent needs to call this zero-parameter tool correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to add. The description correctly avoids inventing inputs and instead explains the payload's structure.

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 (Lists) and a well-defined resource (the taxapp organisations this connection covers), and even defines what an organisation is. The scope 'this connection covers' clearly separates it from the many list_* siblings that enumerate contacts, properties, expenses, 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?

Explicitly directs the agent: 'Call this first: every other tool needs organisation_id when the connection covers more than one organisation.' This gives both the ordering constraint and the condition under which it applies, which no sibling tool states.

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 that rent is split by owner share percentages, which is a semantic detail beyond annotations, plus the crucial instruction never to guess an id on ambiguity. It doesn't cover pagination or result ordering, keeping it short of a 5.

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

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

Front-loads what is listed and its shape, then moves to usage and matching guidance. It is dense but each clause earns its place; the long parenthetical about percentage splitting is slightly heavy but clarifies the data model.

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

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

No output schema exists, so the description must convey the return shape, and it does: properties with owners/shares and tenancies with tenants, rent and dates. Combined with the usage routing and matching advice, this is close to complete for a read-only list tool.

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

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

Schema coverage is 100% and the single organisation_id parameter is fully documented in the schema, so the baseline is high. The description reinforces the multi-org requirement implicitly through its data-scoping context, though it doesn't restate the organisation_id rules. Baseline 4 holds for a 1-param tool with full schema coverage.

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

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

The description states a specific verb (Lists) and resource (rental properties) and details what each result contains: owners with share percentages, and tenancies with tenants, rent and dates. It doesn't explicitly distinguish itself by name from sibling list tools like list_income, but the property/owner/tenancy scope is clear enough to differentiate.

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 names downstream tools (list_income, list_expenses, get_rental_report) and the actions (adding rental income, costs, tenancies) that depend on the property and tenancy ids returned here. It also gives a concrete matching workflow: match by label or address, show closest on ambiguity, never guess an id.

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

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

Annotations already cover readOnly/idempotent/non-destructive/no-open-world, so the description is not obligated to restate safety. It still adds real behavioral context beyond the annotations: the times are in New Zealand time, the payload includes delivery failures ('any problem sending it'), and it requires organisation-owner authorization. Pagination/return-shape details are absent, but the field enumeration largely substitutes for a return-value description.

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

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

Two sentences, front-loaded with the action and resource, with the permission caveat placed last where it belongs. The colon-separated field list is dense but each item carries information; 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 carries the return-value burden and does so by enumerating exactly what each scheduled report entry contains, plus the auth prerequisite. The only real gap is pagination/result-set size behavior, which is minor for a list tool scoped to one organisation.

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 is a single parameter with 100% schema description coverage, and that schema text already explains the optional-vs-required rule via list_organisations. The description adds nothing about organisation_id, so the baseline of 3 applies when the schema does all the work.

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 ('Lists the organisation's scheduled reports') and then enumerates the returned attributes (report, recipients, frequency/timing, last/next send, send problems, enabled state). That field-level detail makes it plainly distinguishable from create_scheduled_report, update_scheduled_report, send_scheduled_report_now, and list_scheduled_report_types.

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

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

Usage is implied by the verb and the ownership constraint ('Only an owner of the organisation can see...'), which usefully signals when the call will succeed. However, no alternatives are named (e.g., pointing to list_scheduled_report_types for report types or create_scheduled_report to add one), so the agent must infer routing from sibling names alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine behavioral detail beyond the annotations: the owner-only visibility/authorization requirement. It does not discuss pagination or result size, but the annotation coverage lowers 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?

It is a single dense sentence front-loading what the tool returns, followed by a short permission caveat. Every clause maps to a returned field or a constraint, so nothing is wasted, though the parenthetical nesting makes it slightly heavy to parse.

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

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

With no output schema, the description carries the return-shape burden and does so well, listing key, name, contents, subject and period. It also notes the authorization constraint. Combined with 100% schema coverage on the one input, an agent has enough to call and interpret the tool correctly.

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

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

Schema coverage is 100% for the single organisation_id parameter, so the schema fully documents it. The description mentions contractor_contact_id, property_id and tenancy_id, but those are return-value fields, not inputs, so they add no meaning to the actual parameter. Baseline 3 is appropriate.

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

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

The description states a specific resource (the report types this organisation can email on a schedule) and enumerates the fields returned: key, name, contents, subject and period. It even ties the 'key' to create_scheduled_report, helping distinguish this catalog-style tool from instance-oriented siblings like list_scheduled_reports. It stops short of explicitly naming that sibling, so it is clear but not perfectly de-conflicted.

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 strongly implied by 'its key (what create_scheduled_report takes)', which tells the agent this is the discovery step that feeds report creation. The permission note ('Only an owner...') adds a precondition. There is no explicit when-not or named alternative, so it is clear context without exclusions.

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

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

Annotations already declare non-read-only, non-idempotent, open-world. The description adds real value on top: an email is sent every single time (reinforcing non-idempotency with an operational warning to confirm first), the schedule itself is not modified, and the period covered is the next scheduled run's period. Return content is also noted.

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

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

Front-loads the action and keeps to a small number of dense, purposeful sentences; each sentence carries distinct information (source of id, recipient set, coverage period, immutability, non-idempotent warning, permission gate, return values). Slightly run-on but not wasteful.

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

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

No output schema exists, and the description compensates by stating the answer reports who it was sent to. Permission gating, side-effect warning, and immutability are all covered. Only the exact return payload shape is left vague, which is acceptable for a send action.

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 both parameters are documented there, including the conditional requirement on organisation_id. The description only reiterates that the id comes from list_scheduled_reports, adding nothing the schema does not already say, so baseline 3 applies.

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

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

States a specific verb and resource ('Emails a scheduled report now') and scopes it precisely: send the report tied to a schedule id, to its recipient and cc'd parties, without altering the schedule. This is clearly distinguishable from create_scheduled_report, update_scheduled_report, and list_scheduled_reports.

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 strong contextual routing: fetch the id from list_scheduled_reports, and only use it for an organisation where the connection may add and change records (check list_organisations). It also advises confirming with the person first. It stops short of explicitly contrasting with alternatives like update_scheduled_report, so it is not a full 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?

The annotations declare destructiveHint=true and idempotentHint=true, and the description earns its keep by spelling out exactly what is destroyed: 'The list replaces every period they have now ... an empty list removes them all' is in the schema, and the description reinforces the replace semantics. It also discloses the permission prerequisite and that the response is the changed contact, none of which the annotations cover.

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 purpose, then destructive semantics, then prerequisite. Every sentence carries information, though the middle sentences are somewhat dense. 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 still tells the agent what comes back ('The answer is the changed contact') and covers the mutation semantics, permission gate, and prerequisites. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the per-field meaning is already documented (baseline 3). The description adds meaning beyond the schema by framing contact_id as coming from list_contacts and clarifying that the acc_classifications array is a full replacement rather than a patch, which changes how an agent must construct 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?

States a specific verb (Sets) and resource (a contractor's ACC classification periods) plus the source of truth (their ACC invoice). The replace-all semantics are stated up front, so an agent can distinguish this from update_contact or set_contact_paye_salary without opening the schema.

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

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

Gives the operational approach explicitly ('start from the periods list_contacts shows and include the ones that stay, by id') and a hard precondition ('Only for an organisation where this connection may add and change records (list_organisations says which)'). It also points the agent at the two sibling tools it must consult first (list_contacts, list_organisations).

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 this is a write (readOnlyHint=false), idempotent, and destructive. The description adds context the annotations cannot: the value is stacked with commission and rental income to derive the tax rate, and the return value is the changed contact. It does not spell out what is overwritten when a salary already exists, which is the one gap given destructiveHint=true.

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 front-loaded paragraph that leads with the action and value, then the preconditions and return value. Dense semicolon-linked clauses but no filler sentences; slightly harder to scan than a bulleted equivalent.

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 everything an agent needs for a mutation tool with no output schema: the write precondition, the source of the ids, the return value ('the changed contact'), and the downstream effect of the value on tax calculations. Nothing material is left implicit.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the organisation_id default/required logic and the NZD-before-tax meaning of annual_paye_salary. The description restates the contact_id provenance and the organisation write-requirement rather than adding new parameter-level detail. 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 (sets), resource (yearly PAYE salary/wages), actor scope (contractor or property owner), and keying mechanism (contact id from list_contacts). It is clearly distinguishable from the other set_* sibling (set_contact_acc_classifications) and from update_contact.

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 real precondition: 'Only for an organisation where this connection may add and change records (list_organisations says which)', which routes the agent to list_organisations for the organisation_id. It also explains the effect on the tax-rate calculation, including the zero-salary case. No explicit when-not is given, 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.

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description adds important behavioural nuance beyond them, including partial-update semantics, the replacement behaviour of contact_types, the need to read/confirm before mutation, and permission constraints. There is no contradiction with the annotations.

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

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

Despite covering many parameters and constraints, the description is front-loaded and dense with no wasted sentences. Each clause serves a distinct purpose: scope, replacement semantics, alternative tools, partial-update rule, safety steps, permission requirement, and return 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 15-parameter mutation tool with no output schema, the description supplies the critical missing behavioural context: omission semantics, contact_types replacement, permission gating, pre-read/confirmation guidance, and the return value. This is complete 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 the baseline is 3. The description adds meaningful semantics by explaining that omitted parameters keep existing values and that contact_types replaces current types, though it does not explain the clear parameter beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Changes a contact that is already there') and lists the mutable fields, clearly distinguishing this tool from create_contact and from the specialised PAYE/ACC tools. An agent can identify the operation and its scope immediately.

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

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

It explicitly says to provide only changed values, that omitted parameters retain current values, to read the record first, and to confirm with the person before changing it. It also names alternatives for contractor PAYE salary and ACC classifications, and states the organisational permission prerequisite.

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?

Goes well beyond the annotations by disclosing partial-update semantics ('every parameter left out keeps the value the record has now'), the side effect of deactivating a type ('contacts keep it'), and the permission prerequisite. Annotations already flag destructiveHint/idempotentHint, so the remaining gap is minor (no error/rejection 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?

Front-loaded with the action and the target record, and every clause (partial update, permission, read-first, confirm) carries weight. It is a single dense run-on paragraph rather than scannable structure, which costs a point.

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

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

For a 6-param mutation with no output schema, the description covers scope, permission, partial-update behavior, side effects, and confirmation workflow. It does not address failure/rejection modes (e.g., attempting to edit a built-in type), a small remaining 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 per-parameter meanings are already documented and baseline is 3. The description adds cross-parameter semantics that the schema cannot express: omitted fields retain their current value and only changes should be passed, which is genuinely useful beyond the field-level docs.

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 (change a contact type) and enumerates exactly what can change: label, supplier/customer flag, active status. It also carves out scope by declaring that built-in types 'stay as they are', which cleanly separates it from create_contact_type and update_contact.

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?

Explicit preconditions and routing: the id comes from list_contact_types, the organisation id from list_organisations, the connection must permit add/change, and the agent should read the record first and confirm with the person. The restriction to organisation-added types is a clear when-not boundary.

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 cover the safety profile (destructiveHint=true, idempotentHint=true), and the description adds genuinely new behavior: omission means 'keep current value' for every non-sent parameter (clarifying the destructive clear path), expense type is immutable, and Xero-submitted records pin amount and date. This is the kind of context annotations cannot express.

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

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

Front-loads the purpose and packs a lot of high-value constraints into a compact block. Slightly dense and run-on (the long field enumeration plus several rule clauses), but nearly every sentence carries operational weight.

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

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

With no output schema, the description still states the return ('the changed record as list_expenses shows it'), plus preconditions, permission gating, immutability, and Xero interaction. For an 11-parameter mutation tool this is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the fields: patch semantics ('every parameter left out keeps the value the record has now'), the rule to send only user-supplied values, and the fact that taxapp derives totals. It does not spell out the 'clear' array behavior, which the schema handles.

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 (changes) and resource (an existing expense record), enumerates the mutable fields, and explicitly names the immutable one ('its expense type never changes'), which cleanly separates it from create_expense and update_* siblings.

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

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

Gives an explicit precondition ('Read the record first'), a workflow instruction ('confirm the change with the person before making it'), and a hard scope exclusion ('Only for an organisation where this connection may add and change records'). It also points at list_expenses/list_organisations as the sources of the required ids.

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?

Goes well beyond the annotations: it states PATCH semantics ('every parameter left out keeps the value the record has now'), discloses the consequence of deactivation ('an inactive account is not offered for new expenses; its expenses stay'), and flags that the default accounts cannot have their name and code changed. IdempotentHint and destructiveHint are already declared, but the preservation guarantees and field restrictions are described only here.

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 verb and resource, and most sentences carry distinct information (scope, active semantics, PATCH rule, permission gate). The opening sentence is a long multi-clause run-on and 'Give only what changes' slightly restates the following clause, costing a little efficiency.

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 7-parameter mutation with no output schema and annotated safety hints, the description covers semantics, permissions and preconditions well. It does not indicate what the call returns or how failures surface, which is the main remaining gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning the schema does not carry: the partial-update contract ('give only what changes'), the fact that omitted fields retain current values, and the constraint on editing name/code for starter accounts.

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 (Changes) plus resource (an expense account) and enumerates exactly which attributes can be modified: name, code, IRD return line, active. It also names the sibling that supplies the id (list_expense_accounts), so an agent can distinguish it from create_expense_account or update_expense without opening a schema.

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

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

Gives real preconditions – read the record first, confirm the change with the person, and only use it for an organisation where the connection may add and change records (list_organisations identifies which). It stops short of explicitly contrasting with the sibling create_expense_account / update_expense tools, so it is strong context rather than full when/when-not/alternatives routing.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), and the description adds genuinely non-obvious behavior: omitted parameters retain current values, tax fields are recomputed from the amount, and a Xero-synced record keeps its amount and date. It never explains the `clear` parameter that justifies destructiveHint=true, so the destructive dimension is left only to the annotation.

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

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

The purpose and field list are front-loaded, but the passage runs long and includes filler that does not inform the call, notably "exactly as the app does" and the redundant re-explanation that omitted parameters keep current values. Readable, but not maximally economical.

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 11-parameter mutation tool with no output schema, it covers the essentials: what can change, what cannot, partial-update behavior, tax recomputation, the organisation guard, and the return value ("the changed record as list_income shows it"). The unexplained `clear` parameter is the main remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters and the baseline is 3. The description adds framing (partial-update semantics, amount drives recomputed tax) but omits the semantically important `clear` parameter, which is the one case where omitted-vs-cleared diverges.

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?

Names a specific verb and resource ("Changes an income record that is already there") and enumerates the mutable fields, drawing a clear line against create_income and the read-side get_income_record/list_income siblings. It also explicitly carves out the immutable attribute ("Its income type never changes"), which no sibling states.

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 real operational guidance: "Read the record first, and confirm the change with the person before making it," "Send only what the person tells you," and the organisation gate pointing at list_organisations. It lacks an explicit when-not clause or a named alternative tool for the read step, which would have pushed it to 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?

Beyond the annotations it discloses the crucial destructive semantic that 'owners replaces every owner it has now, so include the ones that stay', the partial-update contract ('every parameter left out keeps the value the record has now'), the 100% share-sum constraint, and that the response is the changed property. This is exactly the kind of mutation context annotations alone cannot convey.

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

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

Single front-loaded block that leads with the purpose and changeable fields, then constraints and prerequisites. Every sentence earns its place, but the dense run-on packing of replacement semantics, confirmation, module and permission gating slightly hurts scanability.

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

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

For a destructive mutation tool with no output schema, it covers the full picture: partial-update behaviour, owner replacement, share arithmetic, confirmation workflow, permission/module requirements, and the return value ('the changed property'). Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express on its own: omitted fields retain current values and owners is a full replacement. That materially changes how an agent constructs the call, though the per-field detail is otherwise duplicated from the schema.

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

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

States a specific verb and resource ('Changes a rental property, by its id from list_properties') and enumerates exactly which fields change: label, address, owners/shares, active status. This cleanly separates it from create_property and update_tenancy without the agent needing to open a schema.

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

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

Gives concrete preconditions and workflow: 'Read the record first, and confirm the change with the person', plus module and organisation-permission gating with list_organisations cited as the check. It stops short of naming a sibling alternative (e.g. create_property for new records), so it is strong context rather than full alternative routing.

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

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

Annotations only flag destructiveHint/idempotentHint generically; the description explains the actual destructive mechanic (each list replaces that list as a whole, an omitted list keeps its value), the permission prerequisite checked via list_organisations, and that derived values (tax, levy, amount due) are computed server-side. It also discloses the return shape, which matters since there is no output schema.

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

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

Front-loaded with the change scope, then replacement semantics, then permission and return behavior. Every sentence carries information, though it is a dense multi-clause paragraph rather than cleanly separated statements.

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 mutation semantics, partial-update rules, authorization preconditions, and the return value (plan as get_savings_plan shows it), compensating for the absence of an output schema. Nothing an agent needs to invoke this correctly appears missing.

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

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

Schema description coverage is 100%, so the schema already documents each field, setting a baseline of 3. The description adds semantics not in the schema: the replace-as-a-whole behavior of each list parameter and the instruction to omit lists that should not change, which materially affects how arguments must be constructed.

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 ('Changes the savings plan of one New Zealand tax year') and enumerates exactly what fields can change (opening balance, monthly planned/saved amounts, IRD/ACC payments). It is clearly distinguishable from get_savings_plan (read) and copy_savings_plan_from_previous_year (copy).

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 tells the agent to start from get_savings_plan and include entries that should stay, names the sibling to read first, and gives an exclusion ('Only for an organisation where this connection may add and change records'). It also constrains input scope ('Send only what the person tells you').

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds genuinely new behavior: partial-update semantics (omitted parameters keep current values), the read-first/confirm workflow, the owner permission requirement, and the return value. It never explains the destructiveHint=true rating or what is overwritten when a field list is replaced, which keeps it from a 5.

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

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

Purpose and the changeable fields are front-loaded; the partial-update rule follows immediately. Five sentences with little redundancy, though the opening sentence is dense and the 'by its id from list_scheduled_reports' clause interrupts the field list.

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 18-parameter mutation tool with no output schema and full schema coverage, the description covers prerequisites, permission gating, partial-update behavior, and the return value, which is enough to call it correctly. Minor gaps remain around the 'clear' parameter and the destructive potential of replacing field lists.

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, and the description adds a cross-cutting rule the schema cannot express: supply only what changes, since every omitted parameter retains the record's current value. It also enumerates the changeable field groups, though it omits the 'clear' parameter and cc-replacement semantics.

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 (changes) plus the resource (a scheduled report identified by id) and enumerates exactly which fields can change: name, report, recipient, cc, frequency/timing, and on/off state. An agent can distinguish it from create_scheduled_report and list_scheduled_reports without opening the schema.

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

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

Gives real operating context: read the record first, confirm with the person, owner-only visibility, and that the organisation must be one where the connection may add and change records. It does not name a sibling alternative (e.g. send_scheduled_report_now) or state when not to use this tool, 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?

Goes well beyond the annotations (destructiveHint, idempotentHint, openWorldHint=false). It discloses partial-update semantics ('every parameter left out keeps the value the record has now'), replacement rather than merge for contact id lists, immutability of property, required module/org capability, and that the response is the changed tenancy. This is exactly the extra context the annotations cannot carry.

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

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

Front-loads the core verb/resource/scope and each sentence carries information (immutability, replacement semantics, formats, prerequisites). The opening sentence is a somewhat dense field-list, but the density is functional rather than padded.

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

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

For a 15-parameter mutation tool with no output schema, the description covers everything an agent needs: scope, partial-update rule, list-replacement rule, formatting conventions, prerequisites, and the return value ('The answer is the changed tenancy').

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 3 baseline applies, but the description genuinely adds meaning the schema does not encode: contact id lists replace the existing lists, left-out parameters are preserved, dates are New Zealand yyyy-MM-dd, and money is NZD. The 'clear' mechanics are clarified against the schema's parameter-name list.

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 ('Changes a tenancy, by its id from list_properties') and enumerates exactly which fields it can alter (tenants, landlords, term, dates, rent, bond, room, notes). It also draws a hard boundary ('Its property never changes'), which cleanly distinguishes it from update_property and create_tenancy.

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 real workflow and precondition guidance: 'Read the record first, and confirm the change with the person before making it', 'Needs the rental module switched on', and 'Only for an organisation where this connection may add and change records'. It does not explicitly name sibling tools to route away from (e.g. create_tenancy vs update_property), so it falls just short of the 5 bar for alternatives.

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