InvoiceFlow

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

With no annotations, the description must carry the behavioral load. It does disclose the key outcome ('Returns the new client id') and the ordering constraint, which is genuinely useful. But it says nothing about permissions, duplicate-email handling, or whether repeated calls create duplicates — significant gaps for a write tool with zero annotation 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?

Three short sentences, each earning its place: the action, the business prerequisite, and the return value. Front-loaded and waste-free.

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 four-parameter create with a fully documented schema and no output schema, the description covers the action, prerequisite, and return value. Missing duplicate/uniqueness behavior and error cases keeps it from a 5.

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 itself spells out name, email, notes, and company semantics, so the baseline is 3. The description adds no parameter-level detail beyond what is already structured.

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 customer record.' Combined with the note that a client is a prerequisite for an invoice, an agent can tell this apart from invoiceflow_create_invoice and invoiceflow_list_clients. It stops short of explicitly naming those siblings as 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?

'A client is required before an invoice can be created' gives a clear condition that triggers use of this tool. There is no guidance on the reverse case (e.g., checking list_clients for an existing record before creating a duplicate), so work is left 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?

Without annotations, the description provides essential behavioral traits: amounts must be in 'integer cents', the server automatically calculates totals, and it does not trigger an email notification. These are critical operational details.

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 perfectly sized. The first sentence establishes the core action, and the second sentence immediately addresses critical implementation constraints, ensuring no waste of words.

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

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

Given the complexity of billing and invoicing, the description addresses all necessary constraints: unit handling (cents), calculation logic (server-derived totals), and side effects (no email). It is contextually complete for the operation.

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?

While the schema confirms the data types, the description adds high-value semantics by explaining the conversion rule (25000 means $250.00) and clarifies that the `total` is not an input parameter as it is derived by the server.

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

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

The description clearly and immediately defines the tool's purpose: creating a DRAFT invoice for an existing client. This scope distinguishes it from other invoice-related siblings like list_invoices or share_invoice.

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

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

It clearly states the required context ('for an existing client'), which is a usage guideline. However, it does not explicitly guide the agent on when to use this tool versus potentially an 'invoice generation' tool (if one existed), focusing instead on the state (Draft).

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?

No annotations exist, so the description bears the full burden. It does add value by disclosing that line items and derived totals come back, but says nothing about permissions, error behavior for a missing id, or whether totals are computed server-side at read time.

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

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

One sentence, zero waste, and the key information (single invoice, by id, returns line items and totals) 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 simple single-parameter read with a complete schema, the description covers what it returns well enough that an agent can call it confidently. The absence of any output schema makes the brief return-value note valuable, though error and permission context is still 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% for the single 'id' parameter, so the schema already does the documentation work. The description adds only 'by id' with no format, prefix, or example, which is the expected baseline when the schema is complete.

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 ('one invoice') and scope ('by id'), with a note that line items and derived totals are included. It is distinguishable from invoiceflow_list_invoices by the singular/id-based framing, though it never names that sibling.

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

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

Usage is only implied: the singular 'by id' framing signals retrieval of one known invoice rather than a listing. There is no explicit when-to-use statement and no pointer to invoiceflow_list_invoices as the alternative for discovery.

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 no annotations, the description must carry the behavioral burden; it implies a read-only listing and gives a dedupe motivation, which is useful. But it never states result limits, pagination, ordering, or what happens when the list is large — material gaps for a listing tool with zero annotation 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?

Two tight sentences, zero filler, with the action and the motivating workflow constraint 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 one-optional-param read tool with no output schema and no annotations, the definition covers purpose, trigger condition, and the one parameter via schema. The only meaningful omission is return behavior such as result caps or whether the full client list is returned.

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 `query` parameter is fully documented as an optional substring match on name or email. The description adds no extra semantics 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 existing clients"), immediately distinguishing it from the sibling write tool create_client. It doesn't mention the other list sibling (list_invoices), but the resource noun makes the split obvious.

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 says to call this before create_client to avoid duplicate customer records, which names the alternative and the ordering condition. It stops short of saying when not to use it (e.g., when a client ID is already known), so 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?

With no annotations, the description carries the full burden, and it delivers a genuinely non-obvious trait: invoices from other accounts appear as absent rather than raising errors, which prevents an agent from misreading a missing record as a permission failure. It stops short of covering ordering, pagination defaults, or required scopes.

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

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

Two short sentences, both load-bearing: the first frames the resource and return payload, the second front-loads the cross-account gotcha. Nothing is redundant or buried.

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

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

For a read-only two-optional-parameter list tool with no output schema, the description covers purpose and the key visibility caveat. Only minor gaps remain, such as default limit or result ordering, which are not essential to invoking 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 both limit and the status enum are already fully documented in the schema. The description adds no format, default, or interaction 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 invoices') and adds what each result carries (status and totals). It is clearly distinguishable from the singular get_invoice and the mutating create_invoice, though it never names a sibling explicitly.

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

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

The verb 'List' implies the browsing use case versus get_invoice for a known ID, but the description never says when to prefer one over the other or any preconditions. Usage is inferred from the 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?

With no annotations, the description carries the full burden. It usefully discloses the key non-obvious behavior — no email is sent to anyone — but leaves open whether fetching a Checkout link creates a Stripe session, whether links expire, whether it is idempotent, and what permissions are needed. Those are real open questions for a tool that touches Stripe state.

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, zero filler, with the core purpose front-loaded before the usage clarification and the 'does not email' exclusion. 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?

For a one-parameter read tool with no output schema, the description covers what the tool produces (a payable Checkout link) and the key behavioral caveat (no email). The remaining gap is the return shape — a bare URL string versus a structured object — which is not stated and no output schema compensates for it.

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 'id' parameter, so the schema already documents it as 'Invoice id.' The description adds no guidance on id format, whether it accepts a number or a Stripe id, or what happens with an unknown id. 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 and resource — 'Get the payable Stripe Checkout link for an invoice' — and names the concrete artifact returned (a payable link). The follow-up sentence clarifies the distinct purpose versus a generic invoice read like invoiceflow_get_invoice: it produces something a human can act on.

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?

'This is what you give a human so they can actually pay' gives a clear selection context, and 'Does not email anyone' rules out the mistaken assumption that this sends a payment request. It stops short of naming an explicit alternative sibling, but the contrast with the email-sending behavior is stated outright.

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 no annotations, the description carries the burden and does disclose the cost profile ('cheapest') and its validation role, implying a non-mutating read. It stops short of explicitly stating it is read-only or whether failures surface as errors, but the fail-early framing conveys the key behavioral trait.

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

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

Two short sentences, zero waste, with the primary purpose front-loaded and the usage directive immediately after.

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 ideally would hint at what comes back (account name/ID, key validity). It covers purpose and when-to-call well but leaves the return shape unspecified, a minor gap for a zero-param diagnostic.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies the implicit input is the API key itself.

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: check which InvoiceFlow account the key belongs to and whether the key works. This is unmistakably an identity/credential diagnostic, distinct from every sibling (create/list/get/share tools), though it doesn't explicitly contrast itself 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?

Explicitly directs 'Call this first' and explains why: 'the cheapest way to fail early.' That is a clear when-to-use rule with a stated rationale, leaving little to inference.

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