RevExOS

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

Annotations already declare readOnlyHint, idempotentHint and a closed world, so the safety profile is covered. The description adds value beyond that by disclosing the calculation methodology, partial first/last month handling, breakage at expiry, and an explicit limitation on multi-element/variable contracts. It does not mention rate limits or pagination, but none are relevant for a pure computation.

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 deliverable, then the three model behaviors, then the disclaimer; every clause carries information. The 'same math as revexos.com/revenue-recognition-calculator' line is closer to promotion than guidance and slightly inflates the 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?

With no output schema, the description correctly compensates by naming the returned columns (billed, recognized, deferred, unbilled per month), so an agent knows what it gets back. Model-specific parameter interactions are covered, leaving only minor gaps such as term/commitment defaults for usage beyond what the schema states.

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 90%, so the baseline is 3, but the description adds genuine semantics the schema lacks: partial first/last month prorated 'by its own days', billing 'in advance', optional deposit on milestone, and breakage at expiry for usage. These rules tell the agent how parameter choices change the math, not just their names.

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 (build a month-by-month revenue recognition schedule) and enumerates the exact output columns (billed, recognized, deferred, unbilled per month). The three named models and the ASC 606 / IFRS 15 framing clearly separate it from the invoice/AR 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 what each model means and when it applies (subscription = ratable monthly with upfront/annual/quarterly/monthly billing, milestone = recognition on delivery, usage = prepaid drawdown with overage), and adds a scope exclusion ('not a substitute for an accountant on multi-element or variable contracts'). It does not name a sibling alternative or state prerequisites, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the bar is lower, yet the description still discloses real behavior: weekend dates roll to Monday by default, clearing times per payment method, and the terms it accepts. It does not state what the response contains, which is the only notable omission.

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 purpose and the reference URL is a small, tolerable addition. No filler sentences, though the sentence is long enough to be slightly hard to parse.

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

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

For a 6-parameter computation tool with no output schema, the description covers inputs, defaults, and the business rules that govern the computation well. It only omits what the returned values look like (due date vs. cash date fields), which is a minor gap.

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

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

Schema coverage is already 83%, but the description meaningfully enriches several fields: it expands the terms enum into human phrasing (receipt, Net 7/10/.../90, EOM, Net 30 EOM, custom), supplies the payment-method clearing delays (card 0, wire 1, ACH 2, check 7 business days), and confirms the weekend-roll default.

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 (calculate an invoice due date) and enumerates the exact terms it understands, which singles it out from siblings like calculate_late_payment_interest and calculate_proration. An agent can pick this tool without opening the schema.

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

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

Gives clear context: compute the due date from payment terms and also the date cash lands after late payment and clearing time. It does not name an alternative or an explicit when-not condition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description goes beyond them by disclosing the exact computation, the monthly-to-annual conversion, and the UK fixed compensation tiers (GBP 40/70/100 by debt size), which materially affect the result. It does not describe the response shape, but the deterministic formula largely substitutes for that.

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 the jurisdiction caveat, which is the right order. Slightly dense, and the 'Same math as revexos.com/...' sentence is a promotional reference that does not help an agent invoke the tool correctly.

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 and 8 parameters, the description covers the calculation logic, mode semantics, and legal caveat well. The one gap is the return shape (what fields come back, whether the fixed compensation and interest are itemized), which the agent must infer.

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 88%, so the baseline is 3, but the description adds real value: the 'mode' enum has no schema description, and the description supplies its semantics plus the rate-conversion and UK compensation rules that the schema does not. It stays silent on flat_fee/paid_date beyond what the schema already documents.

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 ('Simple interest on an overdue invoice') and immediately backs it with the exact formula (amount x annual rate x days overdue / 365, plus a flat late fee). The three modes are named and defined, so an agent can distinguish this calculator from siblings like calculate_invoice_due_date or calculate_proration 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?

Explains which mode to select for which scenario ('annual' contract rate per year, 'monthly' converted x12, 'uk' statutory 8% + base rate) and adds a real precondition caveat: whether interest can be charged depends on the contract and jurisdiction. No explicit routing to sibling tools or statement of when NOT to use it, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuine behavioral substance beyond them: exactly what is computed (credit for unused old plan, charge for the remainder on the new plan, net amount) and how each method treats whole vs partial periods. This is valuable because there is no output schema defining the result.

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, front-loaded with the operation and followed by method semantics; almost every clause earns its place. The closing reference to an external calculator URL is the one element that adds little for an agent.

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 the result and does so (credit, charge, net amount). All 8 parameters are documented in-schema, edge cases are noted, and method behavior is fully specified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what 'months' vs 'days' actually do mathematically and flagging 'days' as the Stripe default — meaning the schema's terse '"months" (default) or "days"' never conveys. Quantity defaults are left to the schema, which documents them adequately.

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 ('Prorate') and resource ('a mid-period plan change') and immediately enumerates the covered cases (upgrade, downgrade, seat change). An agent can distinguish it from siblings like calculate_invoice_due_date or build_revrec_schedule without opening the schema.

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

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

Gives real decision guidance for the method choice: 'months' (default) vs 'days' (Stripe default), plus the useful edge case that monthly plans yield the same answer either way. It does not state when this tool should not be used or name a sibling alternative, but the purpose is narrow enough that this is not a practical gap.

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 does disclose two useful traits: the email address is required for attribution, and RevExOS will send occasional updates to it ('never spam') — a genuine side-effect/data-usage disclosure. It still omits what happens on invalid input or whether the email is ever sent automatically.

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, purpose front-loaded, no filler. The second sentence is slightly long because it folds in the email-attribution and marketing-notice clauses, but both carry real information.

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

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

For a 13-parameter generation tool with no annotations and no output schema, the description covers purpose, the key tuning dimensions, and the required email constraint; 'ready-to-send' also implies the tool drafts rather than sends. Minor gaps remain around error behavior and the exact output 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?

Schema coverage is 100%, so all 13 parameters are already documented in the schema. The description only restates the stage (1-6) and relationship tuning, adding 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 and resource ('Generate a ready-to-send accounts receivable follow-up email') plus the scoping condition (overdue or upcoming invoice). It is unambiguously distinct from every sibling, which are calculators/parsers rather than generators.

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 context for when the tool applies ('overdue or upcoming invoice') and names the two tuning axes (overdue stage, relationship). It does not state exclusions or point to any alternative, but no sibling competes for this task, so the guidance is adequate.

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

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

Annotations only cover safety (readOnly, openWorld, non-idempotent), and the description goes well beyond them: it discloses the required public-https URL constraint, the mandatory email, a concrete quota (5 per email per day), the full enumeration of returned check categories, and an anti-prompt-injection note about extracted values.

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

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

Dense but front-loaded: the core operation and the three-way-match boundary come first, then returns, then constraints. Every sentence carries distinct information — scope, sibling boundary, return format, quota, injection guard — with no filler.

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

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

With no output schema, the description carries the full burden of explaining results, and it does so by enumerating header checks and all five line-level check outcomes. For a five-parameter tool with a quota and external URL inputs, an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why email is required (it is the quota and delivery key) and reinforces that both file parameters must be public https URLs rather than local uploads. It does not document the optional name/company fields, so it stops short of 5.

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

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

States a specific verb (compare) on two named resources (a purchase order and the invoice billed against it), scoped explicitly to the PO and invoice legs of a three-way match. An agent can place it precisely against parse_purchase_order, parse_invoice, and the calculation siblings 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 the when (comparing a PO to its invoice), the when-not boundary (this is only two legs of a three-way match; the goods receipt comparison must be done by the caller), and the input precondition (both files at public https URLs). Rate limit context is also supplied, leaving nothing to inference.

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

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

With no annotations to lean on, the description carries the full burden and does so thoroughly: file is not stored, 5 parses per email per day, email address required and reused for occasional updates, and a prompt-injection guard noting extracted values are data, not instructions. It also discloses the internal consistency checks performed on line items, subtotal, and tax.

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

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

It is front-loaded with the core action and the extracted fields, then layers constraints, validation behavior, and privacy/rate-limit terms in descending order of importance. Every sentence conveys a distinct operational fact with no filler, and the consent-style disclosure about email usage justifies its own sentence.

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?

Though no output schema exists, the description effectively documents the return shape by listing extracted fields and the arithmetic cross-checks. Combined with input constraints, rate limits, and storage behavior, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: file_url must be publicly reachable without a login (with a Google Drive sharing example) and email drives the rate limit. Name and company remain undocumented beyond the schema's own descriptions.

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 and resource — extract structured data from an invoice — and enumerates exactly what is extracted (invoice number, dates, PO number, vendor, currency, terms, subtotal, tax, total, line items). This cleanly differentiates it from the sibling parse_purchase_order, which targets a different document type.

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

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

Constraints on the input (public https URL, direct download with no login, formats, 10MB limit) are stated, which implies when the tool is usable. However, there is no explicit guidance on when to choose this over siblings like match_po_to_invoice or calculate_invoice_due_date, nor any stated alternatives.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses non-obvious behavior: the file is not stored, there is a rate limit of 5 per email per day, an email is required, and extracted values are treated as data rather than instructions (prompt-injection guard). These are exactly the traits annotations cannot convey.

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

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

Front-loaded with purpose and payload, then constraints and safety notes in tight declarative sentences. Every clause carries information; nothing is 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?

There is no output schema, so the description correctly enumerates the returned fields an agent would rely on, and it covers input constraints, rate limits, persistence, and safety. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description adds real meaning beyond the schema: the URL must be a direct-download public link with no login, and a 10MB size cap, neither of which appears in the parameter descriptions.

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

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

Opens with a specific verb+resource ('Extract structured data from a purchase order') and enumerates the extracted fields (PO number, dates, buyer/vendor, currency, payment terms, totals, line items with SKU/qty/price). An agent can immediately distinguish this from the sibling parse_invoice based on the resource alone.

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?

States clear preconditions: public https URL, up to 10MB, PDF or image, must download directly without a login. It does not explicitly name parse_invoice or say when a purchase order should be parsed versus an invoice, so it stops short of full routing guidance.

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