Codat MCP by usefulapi

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

Opens with 'MUTATES Codat data', which is consistent with the destructiveHint=true annotation and warns the agent before it writes. It also discloses the underlying endpoint and the return shape ('includes its id'), adding value beyond the annotation. It does not state auth/permission requirements, 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?

Four compact clauses, front-loaded with the mutation warning, then the resource, the parameter guidance, the endpoint, and the return value. No filler 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?

With no output schema, the description usefully states that the created company (including its id) is returned, which is what the agent needs to chain into codat_create_connection. Minor gap: 'tags' is mentioned as an optional attribute but no such typed parameter exists, so the agent must fall back to the fields escape hatch.

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 and the schema already documents name, fields, and description. The description restates those in prose but adds no syntax, format, or constraint details the agent can't already read in the schema.

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

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

Names a specific verb and resource ('create a new company') and immediately disambiguates it from the sibling read tools by defining a company as 'a container for a customer's data connections'. Includes the concrete API operation POST /companies, so an agent can distinguish it from codat_create_connection at a glance.

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?

Implies usage ('Provide a name; optionally a description, tags, or other attributes via fields') but never states when to reach for this tool versus siblings like codat_create_connection, nor any prerequisites such as needing an existing Codat account. Adequate context, no explicit routing or exclusions.

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

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

The only annotation is destructiveHint=true, so the description carries most of the burden — and it delivers: it flags the mutation ('MUTATES Codat data'), states the resulting PendingAuth lifecycle state, and explains that authorization happens outside the tool via the returned linkUrl. It omits permission/scope requirements and failure 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?

Four tight sentences with zero filler, front-loaded with the mutation warning and followed by the required inputs, the resulting lifecycle state, and the API mapping. Every sentence earns its place.

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

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

There is no output schema, and the description compensates by stating that the created connection is returned and that linkUrl is the field the caller needs. Combined with the PendingAuth state disclosure, this is complete enough to call correctly, though error or duplicate-connection behavior is unaddressed.

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 already 100%, so the baseline is 3, but the description adds real value by giving a concrete platformKey example ('gbol' for QuickBooks Online sandbox) and re-emphasizing the source of that value. The 'fields' escape hatch is left to 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 ('create a new data connection on a company for a given source platform'), plus the underlying endpoint POST /companies/{companyId}/connections. It is clearly distinguishable from the read-side siblings codat_get_connection and codat_list_connections.

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 routes the agent to the prerequisite tool explicitly ('platformKey from codat_list_integrations') and explains the downstream flow (customer completes authorization via linkUrl). It does not, however, contrast when to use this versus codat_get_connection or how to recover if a connection already exists.

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

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

readOnlyHint=true already covers the safety profile. The description adds a useful behavioral note ('BOTH required by Codat') and the underlying endpoint, but omits data-freshness/sync-state requirements and return-shape hints, which matter for a read-only financials endpoint.

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 before the constraint note and API endpoint. The required-parameter sentence partly duplicates the schema's required array, but overall there is little waste.

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 what comes back, and it says only 'broken into periods' without describing the balance-sheet structure or line items. Adequate for invoking the call but thin on result expectations.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including ranges and defaults. The description largely restates the required-parameter constraint and periodLength's meaning, adding no syntax or semantics beyond what the schema provides.

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

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

States a specific verb and resource ('Get a company's balance sheet') with the added scope qualifier 'broken into periods'. The resource name distinguishes it from financial-statement siblings like get_cash_flow_statement and get_profit_and_loss, though the description does not explicitly name or contrast those alternatives.

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

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

No when-to-use guidance and no mention of alternatives or prerequisites such as required company data being synced first. The note that periodLength and periodsToCompare are required hints at invocation needs but is not framed as usage 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?

readOnlyHint=true already establishes this as a safe read. The description adds that Codat rejects calls without both period parameters, plus the underlying endpoint (GET /companies/{companyId}/data/financials/cashFlowStatement), which is useful for debugging. It says nothing about pagination, rate limits, or what a company with no synced financials returns.

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 action front-loaded and the constraint second. The trailing endpoint reference is mildly redundant with the tool name but is compact and arguably aids debugging, so it does not seriously bloat the 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?

There is no output schema, so the description has to carry the return-value burden; 'broken into periods' only sketches the shape. For a financial reporting tool an agent would still benefit from knowing the period granularity/response structure and behavior on missing data, which is not covered.

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 (companyId, startMonth, periodLength, periodsToCompare) is already documented with ranges and defaults. The description only echoes the required status of two of them, adding no new 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?

States a specific verb and resource ('Get a company's cash flow statement') and adds the shape of the result ('broken into periods'). Siblings like codat_get_balance_sheet and codat_get_profit_and_loss are clearly the same family of financial statements, so the resource noun alone distinguishes this one.

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

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

The description notes that periodLength and periodsToCompare are BOTH required by Codat, which is a usage precondition, but it never says when to reach for the cash flow statement versus the balance sheet or P&L, nor any when-not guidance. Usage is implied by the financial-statement name rather than stated.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds the concrete API route (GET /companies/{companyId}) and the fields returned, but says nothing about not-found behavior, auth requirements, or error cases for an id lookup.

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 tightly packed sentences: identity/scope first, source endpoint second. No filler, nothing 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?

With no output schema, the description usefully enumerates the returned fields, which is exactly what an agent needs to judge fitness. Minor gaps remain around error handling, but the core call contract is covered.

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 companyId parameter is already documented as a UUID in the schema. The description adds only the notion of keying by id, which is baseline-consistent but not incremental.

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?

Specific verb ('Fetch') plus resource ('a single company'), with the return payload enumerated (name, platform, dataConnections, created/lastSync) and the underlying API route given. The word 'single' plus the id requirement clearly separates it from codat_list_companies.

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 'by id' and 'single company', which suggests the keyed-lookup case versus the bulk listing sibling, but no explicit when-to-use or when-not-to-use guidance is given and codat_list_companies is never named.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the raw HTTP endpoint and the shape of the returned summary fields, which is useful context, but says nothing about auth requirements, error cases when the id is unknown, or whether the underlying data is cached.

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 with zero filler; the purpose is front-loaded and the endpoint reference is a short, useful appendix. Nothing needs to 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 usefully enumerates the key fields returned (platformKey, status, sourceType, lastSync), so an agent knows what it will get back. Given a simple 2-param idempotent read with annotations covering safety, that is nearly sufficient, though pagination/error behavior is not addressed.

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

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

Schema description coverage is 100%, so both parameters (companyId, connectionId) are already documented as UUIDs in the schema. The description adds slightly by mapping them into the REST path /companies/{companyId}/connections/{connectionId}, but contributes no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single data connection by id') and enumerates the returned fields, which distinguishes it from the list-style siblings. It stops short of naming codat_list_connections as the contrasting alternative, so differentiation is implied rather than explicit.

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 id' implies usage when a specific connectionId is already known, which is the natural inverse of the list tool. However, there is no explicit when-to-use or when-not-to-use guidance, and no reference to sibling tools like codat_list_connections or codat_get_data_status.

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

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

readOnlyHint=true already establishes this as a safe read. The description usefully adds the underlying endpoint (GET /companies/{companyId}/data/info) and enumerates what the metadata contains, which goes beyond the annotation, but says nothing about auth requirements, rate limits, or failure modes.

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: the purpose and return contents come first, the API endpoint second. No filler and nothing that does not earn 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 partially compensates by sketching the return contents (base currency, supported data types, etc.), which is enough for a simple single-parameter read. A slightly fuller enumeration of the metadata fields would make it 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?

One parameter at 100% schema description coverage, so the schema already defines companyId as a UUID. The description only reaffirms that it scopes the metadata to a single company, adding no new format or constraint information.

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?

Specific verb+resource ('Get a company's accounting metadata') with concrete content examples (base currency, supported data types). It is clear enough to distinguish from data-listing siblings like codat_get_data_status, though it never explicitly names that sibling or states the contrast.

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

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

Usage is implied: an agent reads this as the metadata look-up for a company, but there is no explicit when-to-use, when-not-to-use, or pointer to codat_get_data_status / codat_get_company as alternatives. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: it enumerates the returned fields and gives the underlying endpoint (GET /companies/{companyId}/dataStatus), which compensates for the absence of an output schema. It omits any note on scoping (e.g., all data types vs. one), 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?

Two sentences plus the endpoint reference, front-loaded with the purpose and followed immediately by the use case. No filler, no restatement of the title.

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

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

With no output schema, the description correctly names the key returned fields and the endpoint, which is enough for an agent to call and interpret the tool. It does not mention error behavior or pagination, but for a single-company status lookup those gaps are minor.

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 companyId parameter is documented as a UUID in the schema. The description adds no syntax or format detail beyond what the schema provides, 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 and resource ('Get the freshness/status of each accounting data type for a company') and names the returned fields (lastSuccessfulSync, currentStatus, dataType), which separates it from the sibling list_* data endpoints. An agent can distinguish it from codat_refresh_data_type and codat_get_data_info 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?

Explicitly states the use case: 'Use this to check whether a dataset has been pulled before reading it.' That gives clear when-to-use context. It stops short of naming alternatives or exclusions (e.g., distinguishing it from codat_refresh_data_type, which mutates the same data), 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?

readOnlyHint=true already covers the safety profile, so the description is free to add payload context, which it does by disclosing that the full object includes lineItems and paymentAllocations. It does not mention auth scopes or rate limits, but for a read-only fetch this is solid added value beyond the annotations.

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

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

Two tight sentences: the purpose and payload scope come first, the API endpoint second. No filler, nothing repeated from the title.

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

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

With no output schema, the description must hint at the return shape; it does so by naming lineItems and paymentAllocations. A brief note on pagination or error behavior for a missing id would round it out, but nothing essential is missing for a simple two-param read.

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

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

Schema description coverage is 100%, with both companyId and invoiceId documented in the schema, so the baseline is 3. The description reinforces the id-based lookup and the API path placement of each parameter but adds no new format or constraint detail.

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

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

The description states a specific verb and resource ('Fetch a single AR invoice by id') and names the sibling it is distinct from implicitly via 'single' vs the list_invoices sibling. It also includes the underlying API route, making the operation unambiguous.

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

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

The phrase 'by id' and 'single' implies this is the lookup-one counterpart to codat_list_invoices, but the description never explicitly names that alternative or states when to prefer one over the other. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context: that it returns the account itself (org name, redirect URLs, features) and that it can serve as an API-key health check. It doesn't describe return format beyond the field list, but with annotations carrying the read-only status this is adequate.

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 stating what is fetched and why, followed by the endpoint reference. No filler, every clause earns its place.

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

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

With no output schema, the description compensates by naming the key fields returned (organization name, redirect URLs, features) and the endpoint. An agent has enough to call it correctly and understand the response shape.

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

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

The tool takes zero parameters, so the schema (trivially) covers everything and there is nothing for the description to clarify. Baseline of 4 applies for a no-parameter tool.

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

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

States a specific verb (Fetch) and resource (the authenticated Codat account's profile), and enumerates the returned fields (organization name, redirect URLs, features). This clearly distinguishes it from the sibling data-retrieval tools like codat_get_company or codat_get_balance_sheet.

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

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

Provides a concrete usage context — 'a quick way to verify the API key works' — which tells the agent when this tool is useful. It stops short of naming alternatives or stating when-not to use it (e.g., vs codat_request), so it doesn't reach the top of the scale.

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

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

The readOnlyHint annotation already declares this a safe read, so the bar is lower. The description adds that results are periodized and cites the underlying API endpoint, but says nothing about return shape, pagination, or auth needs beyond what 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?

Three short sentences, front-loaded with the core purpose and zero padding. The API endpoint citation is mildly redundant but potentially useful for an agent reasoning about the request.

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

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

For a simple read-only retrieval tool with full schema coverage and a readOnlyHint annotation, the description covers purpose, required params, and scoping. Nothing critical is missing, though a note on what the periods contain would round it out.

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 four parameters are already documented, including the 1-12 bounds. The description reinforces that periodLength and periodsToCompare are both required, but 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 (Get) and resource (profit & loss / income statement) and adds the 'broken into periods' detail. The resource name inherently distinguishes it from siblings like get_balance_sheet and get_cash_flow_statement, though it doesn't explicitly name 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?

Usage is implied by the resource (financial statement retrieval) but the description gives no explicit when-to-use, when-not, or sibling routing. It only adds the constraint that two params are required, which is a setup note rather than usage 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds real value by disclosing that results come back in a paged envelope, but it does not describe pagination limits, ordering defaults, or whether filters are pushed to the source system — the remaining behavioral gaps are left open.

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

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

Three short statements: what is listed and the returned fields first, then the endpoint, then the response shape. No filler, and the most important information is front-loaded.

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

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

For a read-only, single-required-param list tool with full schema coverage, the definition covers identity, returned fields, and response envelope. Without an output schema the field list is a helpful substitute, though ordering/filter semantics and pagination defaults are only in the schema, not elaborated.

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 page, pageSize, query, orderBy, and companyId are all documented inline with examples and ranges. The description adds no parameter-level meaning beyond the schema; 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 (List) and resource (chart of accounts), enumerates the returned fields (id, name, nominalCode, type, status, currency, currentBalance), and gives the underlying endpoint. This clearly separates it from siblings like codat_list_account_transactions and codat_list_journal_entries.

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 purpose implies when it is used (fetching a company's chart of accounts), but there is no explicit when-to-use guidance, no mention of prerequisites (e.g. an existing connection or data sync), and no routing to alternatives such as codat_list_account_transactions. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds that the call is connection-scoped and returns a paged envelope, which is genuine extra context, but it says nothing about whether the underlying data is cached/stale until codat_refresh_data_type runs, nor 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?

Four short sentences, front-loaded with the purpose before the scoping warning and the endpoint reference. The REST path is arguably redundant given the tool name, but everything else 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 usefully signals the paged envelope return shape, and 100% schema coverage handles parameters. The remaining gap is operational context — data freshness, dependency on a healthy connection — but for a straightforward read-only list tool this is close to complete.

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

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

Schema description coverage is 100%, so page, query, orderBy, pageSize, companyId and connectionId are all already documented in the schema with examples. The description adds no syntax or format 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 and resource ('List a company's account transactions (bank/GL transactions)') and pins down the scope as connection-scoped, which distinguishes it from the company-scoped list siblings such as codat_list_accounts or codat_list_companies. It stops short of naming an alternative tool directly, so it falls just short of the top mark.

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 connection-scoped note implies when this endpoint applies (you must already have a connectionId), which is useful, but there is no explicit when-not guidance, no mention of prerequisites such as connection status or data refresh, and no named alternative. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: it names returned fields (id, supplierRef, date, currency, totalAmount, lines), gives the exact API path, and states the response shape as a 'paged envelope'.

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 in the first sentence, the endpoint and return shape follow immediately, and every sentence earns its place. There is no wasted text, and the parenthetical field list is compact and useful.

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

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

For a read-only list tool with rich schema coverage and an output-less design, the description supplies what structured fields do not: the exact API route, the semantic meaning of 'bill payments', field-level return content, and the paged envelope shape. Nothing an agent needs in order 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 schema already fully documents page, query, orderBy, pageSize, and companyId. The description only reinforces companyId via the endpoint path and adds no extra meaning for the pagination or filtering parameters, making the baseline 3 appropriate.

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

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

States a specific verb ('List') and resource ('bill payments'), and immediately clarifies the resource with '(money paid out to suppliers)' and the returned fields. This distinguishes it from sibling list tools such as codat_list_payments and codat_list_bills without needing to open their schemas.

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

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

The description gives no explicit when-to-use guidance, no when-not-to-use conditions, and never names an alternative sibling tool. It states what the tool does but leaves the agent to infer that this is the right choice for supplier payments versus customer payments.

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

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

readOnlyHint=true already covers the safety profile, so the description's job is to add context — and it does: it names the REST endpoint, lists the concrete fields returned, and notes that the response is a paged envelope. It stops short of describing the envelope's shape (results/pageNumber/totalResults) or any rate-limit behavior, but this is meaningful added context beyond the annotation.

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

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

Three tight clauses: purpose + field list, endpoint, return shape. The parenthetical field enumeration is dense but earns its place given there is no output schema. No filler 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?

With no output schema, the description sensibly enumerates the bill fields and flags pagination; with 100% schema coverage the parameters need no further explanation. The main residual gap is the structure of the paged envelope and any guidance on filtering by status/date via query, which the schema only gestures at.

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 agent already knows page, query, orderBy, pageSize and companyId in detail (including query syntax and orderBy descending convention). The description adds nothing about parameter syntax, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a company's accounts-payable bills') and even enumerates the returned fields (id, supplierRef, status, etc.), leaving no ambiguity about what is fetched. It does not explicitly contrast itself with adjacent siblings like codat_list_invoices or codat_list_bill_payments, but the resource noun alone is discriminating.

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

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

The description gives no when-to-use or when-not-to-use guidance, no prerequisites, and names no alternative tool. It cites the underlying API route, but that is an implementation detail rather than a selection cue for the agent.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds the underlying endpoint (GET /companies) and the paged response envelope { results, pageNumber, pageSize, totalResults, _links }, which compensates for the absent output schema. It does not mention auth requirements, rate limits, or default ordering.

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

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

Three short sentences, front-loaded with the action, then the domain gloss, then the endpoint and return shape. No filler or repetition of schema content.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage and annotations covering the safety profile, the description supplies the missing pieces: what a company is, the API surface, and the paged return shape that stands in for the missing 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% (page, query, orderBy, pageSize are each documented in-schema with examples and bounds), so the schema already carries parameter semantics. The description adds nothing beyond that, which is the expected baseline.

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

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

States a specific verb and resource ('List the companies in your Codat account') and goes further by defining what a company is, which makes the boundary against codat_get_company and codat_create_company obvious 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?

Usage is implied by the resource definition (companies are the customer businesses holding data connections), but there is no explicit when-to-use guidance, no statement about when to prefer codat_get_company or codat_list_connections, and no mention of when filtering via the query parameter is warranted.

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

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

The readOnlyHint annotation already declares this a safe read, so the bar is lower. The description adds that it 'Returns the paged envelope,' which hints at the response shape, but says nothing about pagination behavior, rate limits, or auth scope beyond annotations.

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

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

Three compact sentences, zero waste. The purpose and resource definition are front-loaded before the API endpoint detail.

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

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

For a read-only list endpoint with no output schema and full schema coverage, this is nearly complete — it names the operation, the resource, and the endpoint. Only routing guidance to the single-connection sibling 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 all five parameters (including query, orderBy, page, pageSize) are already fully documented in the schema. The description adds no additional syntax or format detail beyond that. 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?

States a specific verb+resource ('List a company's data connections') and explains the resource itself — each connection links a company to a source platform like QuickBooks or Xero. This clearly distinguishes it from siblings like codat_get_connection (single) and codat_create_connection.

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

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

The description implies usage by describing what connections are, but gives no explicit when-to-use guidance or exclusions — e.g. it never says to prefer codat_get_connection when a specific connectionId is known. Adequate context, no 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 declare readOnlyHint=true, and the description usefully adds that the response is a 'paged envelope' and lists the concrete fields returned. That is real context beyond the annotation, though it stops short of describing default page size or total-result behavior.

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

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

Three tight sentences: purpose first, then the endpoint, then return shape. No filler, no repetition of the title, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by naming the fields and the paged-envelope structure. Parameter documentation is fully covered by the schema, so only minor details like pagination defaults are left implicit.

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

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

Schema coverage is 100%, with page, pageSize, query, orderBy, and companyId all documented in the schema itself, so the baseline is 3. The description adds nothing about parameter syntax or constraints 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?

States a specific verb and resource ('List a company's credit notes') and enumerates the returned fields, which distinguishes it cleanly from the invoice, bill, and payment list siblings. The underlying endpoint (GET /companies/{companyId}/data/creditNotes) reinforces exactly what is being fetched.

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 clearly (retrieve credit notes for a given company), but there is no explicit when-to-use guidance and no mention of alternatives such as the generic codat_request escape hatch. Nothing is misleading, but nothing routes the agent either.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the underlying API route and that the response is a paged envelope, but it says nothing about pagination iteration, rate limits, or what an empty result means.

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

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

Three tight sentences, front-loaded with the purpose before the route and return-shape details. No filler, though the field enumeration is slightly list-like.

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 (id, customerName, contactName, emailAddress, addresses, status, defaultCurrency) usefully compensates for the missing return contract, and paging inputs are covered by the schema. Only behavioral edge cases remain unaddressed.

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 well-documented page, pageSize, query, orderBy and companyId, so the schema carries the parameter burden. The description's parenthetical lists returned fields (an output concern), not input parameter semantics, 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?

The description gives a specific verb+resource (list a company's customers), names the returned fields, and cites the exact REST route GET /companies/{companyId}/data/customers. It is clearly distinguishable from siblings like codat_list_suppliers or codat_list_companies, though it never explicitly contrasts with 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?

There is no statement of when to use this tool versus alternatives (e.g., codat_get_company for a single company, or the other list_* endpoints). Usage is only implied by the resource name and the companyId requirement.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value on top: it names the exact upstream endpoint (GET /companies/{companyId}/connections/{connectionId}/data/directCosts), flags the connection-scoping constraint, and discloses that the response is a paged envelope. It stops short of describing pagination mechanics or failure modes for un-synced connections.

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

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

Three sentences, front-loaded with what the entity is, then the scoping caveat, then the endpoint and return shape. No filler; every clause carries information an agent needs.

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

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

For a read-only list endpoint with full schema descriptions, this covers purpose, scope, endpoint identity, and paginated return shape. The remaining gap is that no output schema exists, so the actual envelope fields (e.g. results, nextPage) are only hinted at by the phrase 'paged envelope'.

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

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

Schema coverage is 100%, with page, query, orderBy, pageSize, companyId and connectionId all documented inline in the schema, so the baseline is 3. The description reinforces the scoping of companyId/connectionId but adds no filter syntax, ordering semantics, or default behavior 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?

States a specific verb (List) and resource (direct costs) and immediately disambiguates the domain with a parenthetical definition: point-of-sale card/cash spend and refunds. That definition cleanly separates it from sibling endpoints like codat_list_payments, codat_list_bills, and codat_list_account_transactions without needing their schemas.

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

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

The CONNECTION-scoped note gives useful routing context (this requires a companyId + connectionId pair, unlike company-wide endpoints), but it never states when to prefer this tool over alternatives or what prerequisites must hold (e.g. data must have been synced for the connection). Usage is implied rather than stated.

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

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

readOnlyHint=true already tells the agent it is a safe read, and the description adds genuinely new context: the underlying Codat API endpoint (GET /integrations) and that results come back in a paged envelope. Auth, rate limits, and envelope field shape are not covered, but this is solid disclosure beyond the annotation.

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

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

Three short sentences, front-loaded with what is listed, followed by the key field, endpoint, and return shape. Nothing is redundant or 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?

With no output schema, the note that it 'returns the paged envelope' usefully sets pagination expectations, and pagination parameters are fully covered by the schema. Only minor gaps remain (no indication of filterable fields for the query param), so it is nearly complete for a simple 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%, so page, pageSize, query, and orderBy are all already documented with examples and bounds. The description adds no parameter meaning of its own, which is the expected baseline 3 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 (List) and resource (accounting/commerce/banking platforms, i.e. integrations) and even names the key field returned (platformKey). No sibling lists integrations, so the agent can distinguish it from codat_list_companies/connections/accounts 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?

Usage is only implied: mentioning platformKey hints that this is the lookup needed before creating a connection, but the description never says when to call it or what to do instead. No exclusions or alternatives are named.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds real value beyond annotations: the underlying API route, the field set returned, and the fact that results come back in a paged envelope. It does not discuss pagination limits or rate limiting, but it clearly exceeds the annotation's coverage.

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

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

Front-loaded with purpose, followed by API route, return shape, and a filter tip, with no filler sentences. The embedded endpoint path is borderline but arguably useful for cross-referencing Codat docs.

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 enumerating the return fields and noting the paged envelope is genuinely necessary and provided. The main omission is that the description never routes the agent to the single-invoice sibling for the detail case.

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 parameters are already documented (page, query, orderBy, pageSize, companyId). The description adds only a filter example, and that example ('status=Submitted&&amountDue>0') diverges in style from the schema's own examples, so it adds little beyond baseline.

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

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

States a specific verb and resource ('List a company's accounts-receivable invoices') and enumerates the returned fields, which cleanly separates it from the singular sibling codat_get_invoice. An agent can pick this over the sibling 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 'Tip: filter with query' line implies a usage pattern (narrow with filters), but there is no explicit when-to-use versus codat_get_invoice or the other list tools, and no stated prerequisites. Guidance is implied rather than stated.

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

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

Annotations supply readOnlyHint=true, so the safety profile is covered, and the description adds genuinely new behavioral context: results come back in a 'paged envelope', which tells the agent to expect pagination rather than a flat array. It still omits things like rate limits, auth scopes, or whether data freshness requires a prior refresh, which keeps it out of 5 territory.

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

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

Three compact fragments: purpose + returned fields, then the raw API endpoint, then the envelope note. It is front-loaded and free of filler, though the endpoint path is arguably operator-facing detail that pads the line.

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 naming the top-level fields and the paged envelope. Combined with the fully documented input schema and the readOnly annotation, an agent has enough to invoke it correctly, though pagination defaults and refresh expectations are left unstated.

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 (page, query, orderBy, pageSize, companyId) are already documented in the schema with examples. The description only lists response fields, not parameter behavior, 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 ('List a company's journal entries') and even enumerates the fields returned (id, postedOn, createdOn, journalLines...), so the agent knows exactly what entity is being fetched. It does not, however, contrast itself with any sibling list tool (bills, invoices, payments), so it stops 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?

There is no statement of when to use this tool versus the many other codat_list_* siblings, nor any prerequisite or exclusion. The endpoint path implies a straightforward read of one company's data, but the agent must infer that from the name 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 readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the returned field set, the REST endpoint, and the fact that responses come in a paged envelope, which tells the agent to expect pagination.

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 resource, then the return fields and endpoint in two compact fragments. No wasted words, though the telegraphic dash-separated field list is slightly dense rather than flowing prose.

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

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

With no output schema, the description usefully enumerates the main returned fields and notes the paged envelope, so the agent knows both shape and pagination. Only distribution/rate-limit or error-behavior detail is missing, which is minor 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 description coverage is 100%, so every parameter (page, query, orderBy, pageSize, companyId) is already documented with examples and constraints. The description adds no new parameter semantics beyond the mention of a paged envelope, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a company's payments received') and immediately disambiguates scope with '(money in against invoices)', which separates it from the sibling codat_list_bill_payments. It even names the underlying API path, so an agent knows exactly what is being fetched.

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

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

The parenthetical 'money in against invoices' gives clear selection context against the money-out sibling, and the required companyId is implied by 'a company's payments'. It stops short of explicit when-to-use/when-not guidance or naming codat_list_bill_payments as the alternative.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: the concrete response shape (paged envelope) and the returned fields, 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?

Compact and front-loaded: purpose first, then fields, then endpoint. Only minor redundancy between the field enumeration and the paged-envelope note, but nothing is wasted.

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

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

For a read-only list tool with a fully documented schema and no output schema, the description covers purpose, endpoint, return fields, and response shape. Pagination controls live in the schema, so the overall picture 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 description coverage is 100%, so the schema already documents page, query, orderBy, pageSize, and companyId with examples and defaults. The description adds no parameter-level meaning, making the baseline 3 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 (List) and resource (suppliers/vendors), enumerates the returned fields, and pins the exact API endpoint (GET /companies/{companyId}/data/suppliers). This clearly separates it from the many sibling list tools such as codat_list_customers and codat_list_invoices.

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

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

Usage is implied by the resource: list suppliers for a given company. There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives or when not to reach for this tool over, say, codat_request or codat_list_accounts.

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 destructiveHint annotation by disclosing that it MUTATES Codat state, that Codat re-pulls from connected source platforms, that it is asynchronous (enqueues rather than returning data), and which endpoint is called. This is exactly the behavioral context an agent needs before invoking a mutating tool.

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

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

Three tight sentences with zero filler, front-loaded with the mutation warning and scope, followed by async semantics and the follow-up tool. Every sentence carries distinct, actionable 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?

Complete for a one-param async mutation with no output schema: it explains there is no returned data and how to poll status. It stops short of saying what happens to previously synced data or any cost/rate implications of a full refresh, which would round out the destructiveHint profile.

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 and schema description coverage is 100%, so the schema already documents companyId as a UUID. The description adds no format or constraint detail beyond what the schema provides, which is the baseline 3 case.

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+scope: queue a refresh of ALL data types for a company, and cites the underlying endpoint POST /companies/{companyId}/data/all. The 'ALL' scope plus the sibling codat_refresh_data_type lets an agent distinguish bulk refresh from single-type refresh 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?

Gives clear operational context: asynchronous enqueue, and explicitly routes the agent to codat_get_data_status to track progress. It does not, however, explicitly state when to prefer this over codat_refresh_data_type (single type) or what preconditions (an existing connection) are required.

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 supply destructiveHint=true, but the description goes well beyond that: it flags state mutation, explains the async queue semantics ('it enqueues a pull, it does not return the data'), and names the underlying endpoint. That async/non-returning behavior is exactly the trait an agent needs and is not present in any structured field.

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 mutation warning is front-loaded in caps, followed by two tight sentences covering scope and async behavior, then the API path. Every clause carries information and nothing is 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 two-parameter write tool with no output schema, the description supplies the missing behavioral facts (async, no data returned, mutation) and the endpoint. An agent has everything needed to call it correctly and interpret the absence of a payload.

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 both parameters are already documented there, including dataType examples, so the description's restatement of example values adds little. Baseline 3 is appropriate when the schema carries the 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 and resource ('queue a refresh of ONE data type for a company') and scopes it to a single dataset, which cleanly separates it from the sibling codat_refresh_all_data. Examples of valid dataType values further pin down what a 'data type' is.

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

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

The 'ONE data type' scoping plus the presence of codat_refresh_all_data effectively signals when to use this versus the bulk-refresh alternative. However, the alternative is never named explicitly, so the agent must infer the routing rule rather than being told it.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this ('READ-ONLY — only GET is allowed'), clarifying that no other HTTP method is permitted. It adds the path-format constraint and passthrough nature but says nothing about rate limits, auth, or error behavior, so it adds value without being 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?

Three tight sentences, front-loaded with the tool's role and constraint, with no filler. The examples of valid paths earn their place by clarifying scope.

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

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

For a generic passthrough whose response is inherently arbitrary, the description covers what an agent needs: read-only constraint, path format, and escape-hatch scope. It could note that responses vary by endpoint, but 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%, so both `path` and `query` are already documented in the schema. The description's slash requirement and examples duplicate what the schema already provides, adding no meaning beyond it — the baseline 3 applies.

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

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

States a specific verb and resource (GET any Codat API path) and explicitly positions itself as the escape hatch for paths 'not wrapped by a dedicated tool', which cleanly distinguishes it from the ~27 dedicated sibling tools.

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

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

Clearly signals the usage context: a 'power-user escape hatch' for paths without a dedicated wrapper, which implicitly steers agents to prefer the dedicated tools first. It does not state this preference as an explicit rule or give a when-not condition, so it falls just short of 5.

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