RevExOS

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavioral context beyond that: deterministic math matching a public calculator, single-performance-obligation scope, and explicit limits (not for multi-element or variable contracts). It does not describe error behavior for invalid model/parameter combinations.

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

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

Front-loaded with the core action and output shape, then model semantics, then a scope caveat. Dense but nearly every clause carries information. The long parenthetical model list is a single sentence, which slightly hurts scannability but avoids padding.

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 takes on the burden of return semantics and does so by naming the four monthly columns. It also bounds the domain (single performance obligation) and covers all three models. It leaves the actual response shape and unit conventions 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 already 90%, so 3 would be the baseline; the description goes further by giving computation semantics the schema lacks, e.g. how billing frequency interacts with the subscription model, that partial months use their own days, and that usage overage is billed monthly with breakage at expiry. It does not restate per-parameter constraints.

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+resource (build a revenue recognition schedule), states the accounting standard (ASC 606 / IFRS 15), the granularity (month-by-month), and the exact output columns (billed, recognized, deferred, unbilled). This is clearly distinguishable from every sibling, all of which are invoice/PO-oriented utilities.

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

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

Gives strong model-selection guidance by explaining when each of the three models applies (subscription = equal per month with partial first/last; milestone = recognized on delivery, optional deposit; usage = prepaid draw-down with overage and breakage). It also states when-not-to-use via the accountant caveat for multi-element/variable contracts. It stops short of naming sibling alternatives (e.g., calculate_proration) for the partial-period cases.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real behavior beyond that: weekend dates roll to Monday by default, terms like EOM and Net 30 EOM are handled, and it reveals the two-part output (due date plus actual cash-landing date). It doesn't state the exact return shape, which is a minor gap given 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?

A single dense sentence, but it is front-loaded with the core operation and then layers in the modifiers. Every clause carries information. The run-on structure makes it slightly harder to scan than a short bulleted form would, keeping it below a 5.

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 burden, and it does identify the two useful results (due date and cash-landing date). Defaults for roll_weekends and payment_method are stated, and the custom_days linkage to terms='custom' is at least implied by the schema. The precise output field names are not given, a small omission for a tool of this complexity.

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 83%, so the schema baseline is already 3. The description nonetheless adds meaning the schema lacks, notably the clearing-time mapping for each payment method (card 0, wire 1, ACH 2, check 7 business days) versus the schema's bare 'Default ach.' It also expands the terse enum values (receipt, net30eom) into plain English.

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

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

The description names a specific verb+resource ('work out an invoice due date') and then enumerates the exact domain it covers: payment terms, late-payment cash landing, and payment-method clearing windows. It clearly separates this pure-calculation tool from siblings like calculate_late_payment_interest or calculate_proration. An agent can tell immediately what computation this performs.

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 input domain (you have an invoice date and terms; you want a due date), but there is no explicit when-to-use, when-not-to-use, or named alternative among the seven sibling finance tools. It never says, for example, to use calculate_late_payment_interest instead when interest rather than a date is needed. 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 readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavioral context: the exact interest formula, the x12 monthly conversion, the UK 8% + base rate rule and GBP 40/70/100 fixed compensation tiers, plus the jurisdiction caveat.

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

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

Front-loads the formula and mode definitions, then closes with the caveat. Dense but every clause carries information; the mode enumeration is a bit compressed but not wasteful.

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

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

For an 8-parameter calculator with no output schema, the description supplies the computation logic so an agent understands what the result represents (interest plus flat fee). It does not explicitly name the returned field/structure, which is the only notable gap.

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

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

Schema coverage is high (88%), so the schema documents most fields. The description still adds meaning the schema lacks: the mode enum values are only listed as strings in the schema, but the description explains what each mode means and which rate parameter applies, plus the flat fee behavior.

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 ('Calculate Late Payment Interest') and immediately clarifies it is simple interest on an overdue invoice with the exact formula. The three mode semantics (annual/monthly/uk) further distinguish it from generic date or proration calculators among siblings.

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

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

Explains which mode to pick (contract annual rate, monthly rate converted x12, UK statutory) and warns that charging interest depends on contract and jurisdiction. It does not explicitly route against siblings like calculate_invoice_due_date or calculate_proration, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds context about calculation methods and references an external calculator, which is useful, but it doesn't disclose API-specific behavior, rate limits, or error conditions beyond what annotations provide. A 3 is appropriate given the lower bar with 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?

The description is front-loaded with the core purpose in the first clause, then moves to output and method details. It is efficient but includes a reference to an external website that may not be necessary for an agent and slightly dilutes conciseness.

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 tool's complexity (8 parameters, financial calculations) and the absence of an output schema, the description does a good job of explaining the calculation outputs and method differences. It is nearly complete, lacking only explicit guidance on parameter constraints (e.g., change_date must fall within period) which the schema already covers.

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

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

Schema coverage is 100%, so the schema already documents all parameters in detail. The description clarifies the 'months' vs 'days' method distinction beyond the schema's terse enum documentation, adding some semantic value, but it does not explain the quantity parameters or the cycle parameter further. Baseline 3 is correct when 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?

The description states a specific verb and resource ('Prorate a mid-period plan change') and names the exact scenarios it covers (upgrade, downgrade, seat change). It also enumerates the three outputs (credit, charge, net amount), which no sibling tool produces, making it clearly distinguishable.

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 the context (mid-period plan changes, upgrades/downgrades/seat changes) but does not explicitly state when to use this tool versus alternatives like calculate_invoice_due_date or build_revrec_schedule. No exclusions or prerequisites are mentioned, so the guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the email is tuned by overdue stage (1-6) and relationship intent, the email field is required to attribute the request, and a side effect is disclosed (occasional updates, never spam). This is richer than the annotations alone.

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; the first front-loads what the tool produces, the second covers the requirement and side effect. No wasted words, though the side-effect disclosure adds a bit of length.

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 generation tool with a rich 13-param schema and no output schema, the description covers the core behavior, tuning dimensions, and the required email parameter plus a disclosure about usage. It omits details like output format (which the API likely defines implicitly) but is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, including the stage enum values, relationship enum, and usage notes for daysOverdue. The description adds only a high-level mention of the stage/relationship axes and the email's role, not new parameter syntax or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Generate a ready-to-send accounts receivable follow-up email for an overdue or upcoming invoice') and adds the tuning axis. Clearly distinct from siblings like parse_invoice or calculate_invoice_due_date, which do not produce email content.

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 when to use it (overdue or upcoming invoice) and mentions the stage/relationship tuning, but provides no explicit when-not-to-use or guidance on choosing among the sibling tools. Usage context is present but thin.

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 past the annotations (which only cover read-only/open-world/idempotency) by disclosing accepted input sources, the email requirement, a concrete rate limit (5 per email per day), the shape of the returned checks, and a prompt-injection caveat that extracted values are data, not instructions.

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

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

Front-loaded with purpose, then inputs, then outputs, then constraints. Dense but nearly every sentence carries operational weight; the enumeration of check types is long but useful for interpreting results.

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 adequately: it enumerates header checks and all five line-item check categories. Inputs, limits, and auth (email) are all covered, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and each field is already documented in the schema, including the URL-vs-attachment exclusivity. The description restates the input forms ("public https URL or a file attached in ChatGPT") but adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ("Compare") and resources ("a purchase order with the invoice billed against it"), and positions the tool within the three-way match workflow. An agent can immediately distinguish it from sibling single-document tools like parse_invoice and parse_purchase_order.

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?

Clear context for use ("the PO and invoice legs of a three-way match") plus an explicit scope boundary telling the agent to handle the goods-receipt leg itself. It never names the sibling alternatives (parse_invoice/parse_purchase_order) for single-document extraction, so routing between tools is still partly inferential.

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 readOnly/destructive annotations: states the file is not stored, the rate limit (5 parses per email per day), the mandatory email and why it is collected, the marketing-email disclosure, and a prompt-injection caveat that extracted values are data not instructions. These are exactly the operational facts an agent needs before invoking.

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

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

Purpose and accepted inputs are front-loaded in the first sentence, followed by the validation behavior, then constraints and disclosures. Slightly long, and the RevExOS update blurb is arguably padding, but nearly every sentence carries 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?

With no output schema, the description properly enumerates the returned fields and the derived consistency checks (line items vs subtotal, subtotal+tax vs total), so an agent knows what a result contains. Input constraints, cost (daily quota), and privacy behavior are all 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%, so baseline is 3, but the description adds real meaning: accepted formats and the 10MB ceiling, the login-free public-URL requirement, and the rationale for the required email. It also clarifies file vs URL usage already hinted at in the schema ('Use this or the URL field, not both').

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 ('Extract structured data from an invoice') and enumerates exactly what is returned: invoice number, dates, PO number, vendor/customer, currency, terms, subtotal, tax, total, line items, plus arithmetic cross-checks. An agent can distinguish this from parse_purchase_order purely from the description.

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

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

Gives concrete input conditions: accepts a public https URL or a ChatGPT attachment, the URL must download directly without a login, and Google Drive links must be set to 'Anyone with the link'. It stops short of naming sibling alternatives (e.g., parse_purchase_order for POs), so it is clear context without explicit 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is partly covered. The description adds substantial non-obvious behavior: 10MB size limit, no server-side storage of the file, a mandatory email, a 5-per-email-per-day quota, and a prompt-injection caveat that extracted values are data not instructions. The quota is the only trait left ambiguous (per calendar day vs rolling window).

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

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

Front-loaded with the core action and return payload, then constraints and caveats. It is a single dense paragraph rather than a run-on of filler, though the email/quota and injection caveats could be split for scannability.

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 compensates by enumerating the extracted fields, and it also covers input limits, auth (email), quota, and data-handling policy. For a single-shot extraction tool with one required parameter, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the email parameter's purpose (required, and used for both quota tracking and tool updates) and the mutual exclusivity/constraint on the URL versus the ChatGPT-attached file. It does not clarify the nested file object's file_id/download_url split, which the schema carries.

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 (Extract) and resource (purchase order), enumerates exactly what is returned (PO number, dates, buyer/vendor, currency, terms, totals, line items with SKU/qty/price), and scopes the input formats (PDF or image). An agent can distinguish this from parse_invoice or match_po_to_invoice without opening any schema.

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

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

Gives clear preconditions for use: the URL must download the file directly without a login, and the file may alternatively be attached in ChatGPT. It does not explicitly name an alternative or state when not to use it (e.g., use match_po_to_invoice once the PO is parsed), so it falls short of full routing guidance.

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