company_customers

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

The description is transparent about source limitations ('no due or paid dates: due comes from the plan's terms and days to pay stay unknown') and about raising exceptions. However, it directly contradicts itself: 'record (persist under the window)' versus 'Read-only'. With no annotations provided, this ambiguity about whether the tool mutates state is material.

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

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

The description is a dense run-on paragraph with nested clauses and awkward interjections like 'and it says so'. It is not front-loaded with a clear statement of the tool's primary behavior. All sentences carry information, but the structure makes the tool behavior harder to parse rather than easier.

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

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

For a tool with 7 generic string parameters, no annotations, and no schema descriptions, the description leaves major call-construction gaps: it does not state valid operation values, which parameters apply to build versus record versus list, or the expected format for window_start/window_end. It provides strong domain context but insufficient operational completeness.

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

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

Schema description coverage is 0%, so the description must carry parameter documentation. It does explain that payload_json takes source {provenance, payload} plus optional window_start/window_end and names build/record/list operations. But it does not explain project_id, entity_ref, bundle_json, engine, or now, nor map operation names to parameter values or requirements, leaving most of the 7 parameters underdocumented.

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 identifies the resource as a customer ledger derived from sales invoices and enumerates the ledger contents: invoices, revenue, balance outstanding, aging buckets, and days-to-pay, plus operations build/record/list. 'Revenue and cash behaviour, not profit' helps separate it from profitability-focused siblings. It loses a point because the main statement is a noun phrase rather than an explicit action statement like 'returns/builds/list'.

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 use for AR/cash-related customer views through 'customer ledger', 'balance outstanding', 'past due', and 'slow payer', and mentions the weekly review carrying raised exceptions as actions. However, there is no explicit when/when-not guidance, no named alternatives, and no direction on choosing this over company_receivables, company_collections, or company_customer_profitability.

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