Hiveage MCP by usefulapi

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

The 'WRITE:' prefix plus 'Hiveage: POST /network' discloses the mutation and the underlying endpoint, which is real value given annotations only carry destructiveHint=false and a title. It stops short of saying what happens on validation failure or duplicate connections, and there is no output schema to explain the response.

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, front-loaded fragments with no wasted language; the write marker and the conditional-shape rule come first. Minor redundancy in repeating schema-level field rules, but overall tight.

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?

A 17-parameter create tool with no output schema and only title/destructiveHint annotations needs more: the description omits most field semantics and the entire post-creation behavior. An agent can call it, but only by reading the raw 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 coverage is only 41% across 17 parameters, so the description needed to compensate. Instead it restates the name/first_name/last_name logic already documented in the schema and says nothing about the two other required fields (business_email, currency) or the many undocumented optional fields (address, phone, country, primary_contact_*, etc.).

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 connection') and clarifies the domain meaning of 'connection' as client, vendor or company, which is non-obvious. It does not explicitly differentiate from the sibling hiveage_create_contact, so an agent must infer the distinction.

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 conditional guidance for the organization-vs-individual shapes, which is genuinely useful for choosing fields. However, it says nothing about when to create a connection versus a contact, no preconditions, no duplicate-handling advice, and no 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 'WRITE:' prefix and the POST endpoint meaningfully disclose that this is a mutation, adding context beyond the lone destructiveHint=false annotation. It does not say what happens if the contact already exists, whether auth/permissions beyond the connection are required, or how failures surface — gaps the sparse annotations leave 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?

Two short sentences with the mutation signal front-loaded and the endpoint appended efficiently. Nearly every clause earns its place; only the parenthetical about statements could be tightened.

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 write tool with no output schema and very low schema coverage, the definition omits the purpose of three optional fields and any note on duplicate-email behavior or response shape. An agent can call it, but cannot confidently fill or interpret all the inputs.

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 only 17%, so the description must compensate, and it only partly does: it names 'name and email' (mapping roughly to first_name/last_name/email) and explains the email's purpose. It says nothing about phone, mobile, or the hash_key scoping parameter, leaving half the inputs undocumented anywhere.

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: add a contact to a connection, plus the underlying endpoint POST /network/{hash_key}/contacts. It is distinguishable from hiveage_update_contact and hiveage_get_contact by the 'add' verb, though it never names those siblings 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 phrase 'used when sending statements' gives a hint about why a contact exists, implying use when you need an email recipient for statements. However, there is no explicit when-to-use vs when-to-prefer-update_contact guidance, and no stated prerequisites such as needing an existing connection.

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 destructiveHint=false, so the description carries most of the burden and does well: it flags this as a WRITE, clarifies the record is created in draft state and no email is dispatched, and surfaces the uniqueness constraint on statement_no. It does not say what is returned (e.g. the new estimate id) needed for chaining to send_estimate.

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 with the WRITE marker front-loaded, then behavior, then constraint, then endpoint. 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 14-parameter creation tool with no output schema, the description covers intent and the email-suppression behavior but omits what the call returns (the created estimate's id) and gives no shape guidance for the many optional line-item arrays beyond what the schema already says.

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 79%, so the baseline is 3. The description's 'statement_no must be unique' reinforces rather than adds to the schema's own 'Unique estimate number' text, and it says nothing about the 14 parameters — line types (items/tasks/trips/expenses/discounts/taxes), date formats, or which fields are conditionally expected.

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 an estimate'), disambiguates the business term with the alias 'quote', and scopes it to a connection. The 'starts as a draft, nothing is emailed' clause distinguishes it from send_estimate without naming it.

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?

'Starts as a draft, nothing is emailed' gives the agent the key operating condition and implies the send_estimate follow-up, and the endpoint reference frames it as the POST-only creation path. It stops short of explicitly naming hiveage_send_estimate or hiveage_create_invoice as the 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?

With only destructiveHint=false and a title in annotations, the description carries most of the burden and does well: it discloses that creation is non-destructive and reversible-feeling (draft, nothing emailed) and that statement_no has a uniqueness constraint. It does not say what happens on a duplicate statement_no or what permissions/plan are required.

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 clauses, front-loaded with the WRITE marker and the draft caveat, all doing work. The trailing 'Hiveage: POST /invs.' endpoint notation is the only piece an agent can't act on.

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 18-parameter creation tool with no output schema, the description covers the essentials an agent needs to call correctly: it's a write, it's a draft, the id source, and the uniqueness constraint. Missing is any hint about the return value (presumably an invoice id) or that line items may be optional given draft state.

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 67%, so several parameters (note, summary, po_number, send_reminders, allow_partial_payments, send_receipts_automatically) are undocumented in both places. The description adds real value on the two most important fields — connection_id's provenance (numeric id from hiveage_list_connections, not hash_key) and statement_no uniqueness — but says nothing about the many line-item arrays or the boolean flags.

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 an invoice') plus the scope caveat that it starts as a draft and emails nothing, which separates it cleanly from hiveage_send_invoice in the sibling list. The 'WRITE:' prefix makes mutation intent unmistakable 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?

The draft/no-email note implicitly tells the agent that a follow-up send step is needed, and the pointer to hiveage_list_connections for connection_id gives the prerequisite call. It stops short of explicitly naming hiveage_send_invoice or hiveage_update_* as the next/alternative step.

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 destructiveHint=false; the description adds that this is a write/POST operation, which is useful. It does not disclose duplicate-name behavior, idempotency, account scoping, or what happens on validation failure, which matters for a create operation.

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 clauses, mutation type front-loaded, zero filler. Every element 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 simple 4-parameter create with no output schema, this covers purpose, mutation type, and endpoint mapping. Missing only edge-case behavior (duplicates, validation) which is a minor gap given the tool's simplicity.

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 50% (unit and price documented; name and description not). The description only restates the field names 'name, price, unit' without adding format or constraint meaning, and says nothing about the optional 'description' parameter.

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: 'save a reusable line item (name, price, unit) for statements,' and adds the underlying endpoint POST /categories/items. No sibling tool creates items, so differentiation is not an issue, though 'for statements' is a slightly loose scoping phrase.

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 'WRITE:' prefix hints at mutation, but there is no guidance on when to create a new saved item versus reusing an existing one, no mention of whether names must be unique, and no prerequisites or permissions context.

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 annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying Hiveage endpoint GET /network/{hash_key}, which is useful context, but it does not disclose return behavior, error conditions, or authorization requirements.

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, front-loaded with the core action and scoped to a single record. There is no filler and the endpoint reference is brief.

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 one-parameter read operation with readOnlyHint and a fully described schema, the description is nearly complete. It identifies the resource and endpoint, though it could say more about the returned connection object if an agent needed to understand response content.

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 already explains that hash_key is a short string, not a numeric id. The description reinforces that the lookup is by hash_key but does not add meaning 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?

The description clearly states a specific verb and resource: retrieving one connection by hash_key, and it clarifies that 'connection' means a client, vendor, or company. It does not explicitly differentiate itself from list_connections or get_contact, but the singular scope and hash_key identifier make its purpose clear.

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 hash_key': use this when you have a connection hash_key and need one record. However, there is no explicit guidance on when to use this versus list_connections, nor any stated exclusions or prerequisites.

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 establishes this as a safe read operation. The description adds that the lookup is scoped to a connection and uses a numeric contact id, but it does not add behavioral context such as error behavior, permissions, or response characteristics.

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 two short sentences, front-loads the operation, and includes the endpoint without unnecessary filler. Every sentence contributes to identifying the tool.

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 get-by-id tool with full schema coverage and annotations, the description is largely sufficient. It could mention the return value more explicitly since no output schema exists, but the operation itself is clear.

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 are already well documented in the schema. The description slightly reinforces that the contact is identified numerically and belongs to a connection, but it does not add meaningful semantics 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?

The description states a specific verb and resource: 'Get one contact of a connection by its numeric id.' It clearly distinguishes this from bulk contact listing by emphasizing a single contact and numeric id, though it does not explicitly name the sibling tool it replaces.

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 when retrieving a single contact by numeric id, but it does not explicitly say when to choose this over list_contacts or how to obtain the required hash_key and id. There are no exclusions or alternative-tool 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, and "get" is consistent with that. The description adds one useful behavioral detail — that line items come back with the estimate — but says nothing about error behavior for an invalid or unknown hash_key, which matters since 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?

Two short sentences with zero waste: the retrieval semantics lead, and the raw endpoint note trails as optional context. Nothing is padded 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 single-parameter read tool with full schema coverage and a readOnlyHint annotation, the essentials are covered, and the note about line items compensates for the absence of an output schema. Only failure-mode 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 100% and the schema's hash_key description is already richer than the prose (it warns against using the numeric id and gives a format example). The description adds nothing beyond repeating "by hash_key," 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 ("Get one estimate by hash_key") and adds scope (single record plus line items), which implicitly separates it from hiveage_list_estimates and hiveage_create_estimate. It stops short of naming the sibling tools explicitly, so it is clear but not maximally differentiated.

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 only implies usage via "by hash_key" — an agent is expected to infer that this is the retrieval tool when a hash_key is known. It never states when to prefer this over hiveage_list_estimates or what to do without a hash_key, so there is no real when-to-use 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, so safety is covered; the description adds genuinely new behavioral detail by disclosing the enriched response contents (line items, taxes, discounts, shipping) and the underlying endpoint. No mention of error behavior for an invalid hash_key, 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?

Two short sentences, both front-loaded with the key information (what is fetched, what comes back), with zero redundant 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 a single fully-documented parameter and no output schema, the description supplies the most important missing piece — the shape of the returned invoice — leaving nothing an agent needs in order 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 coverage is 100% and the schema already explains that hash_key is a short string rather than a numeric id. The description names the parameter but adds no format or validation 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 ('Get one invoice by hash_key') and enumerates what the payload includes (line items, taxes, discounts, shipping). It is clearly distinguishable from hiveage_list_invoices, which returns many.

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?

'Get one invoice by hash_key' clearly implies the retrieval scenario and contrasts implicitly with the list_* siblings. It does not explicitly name when to prefer list_invoices or get_payment instead, so it stops short of a full routing instruction.

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 is a safe read. The description adds useful structural context — that payments are nested under an invoice identified by hash_key — but says nothing about error behavior for unknown ids or what the response contains.

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 filler, with the core operation front-loaded before the endpoint mapping.

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 two-parameter read with full schema coverage and a readOnly annotation, the description covers what the tool does and how the resource is addressed. Only minor gaps remain, such as return shape and not-found behavior.

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 both parameters are already documented, including that hash_key is not the numeric invoice id. The description reinforces that the payment id is numeric but adds little 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 (get), resource (one payment), and scoping (of an invoice, by numeric id). This clearly separates it from hiveage_list_payments, though it does not name the 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?

Usage is implied: use when you have an invoice hash_key and a payment id and want a single payment rather than a list. There is no explicit when-to-use/when-not guidance or reference to alternatives such as hiveage_list_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 tells the agent this is a safe read, and the endpoint mapping (GET /rinv/{hash_key}) reinforces that it is a non-mutating fetch. However, nothing is said about error behavior for an unknown hash_key, permissions, or what the returned profile contains, so it adds little 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?

Two short sentences with the key requirement front-loaded; nothing is buried. The REST endpoint fragment is mildly redundant with the tool name but still provides a useful mapping for an agent crossing MCP and API 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?

For a one-parameter read tool with readOnlyHint and no output schema, the description is minimally sufficient to call correctly. It does not describe the shape of the returned recurring invoice profile (fields, line items, schedule) even though no output schema carries that burden.

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 already clarifies that hash_key is a short string rather than a numeric id. The description only restates "by hash_key" and adds no format guidance beyond the schema, 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?

States a specific verb and resource ("Get one recurring invoice profile") and scopes it to a single record via hash_key, which distinguishes it from hiveage_list_recurring_invoices. It never names that sibling explicitly, but the singular/by-key framing makes the distinction inferable.

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 agent can infer this is the lookup-by-key path when it already holds a hash_key. No explicit when-to-use or when-not guidance, and no mention of sibling tools like list_recurring_invoices or list_connection_recurring_invoices as 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower. It adds the underlying endpoint mapping (GET /categories/{kind}), which is helpful context, but says nothing about pagination defaults, ordering behavior across kinds, or what an empty result looks like.

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, front-loaded with the verb and resource, then the kind breakdown. The trailing API reference is compact and non-redundant. 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?

For a four-parameter filtered-list tool with a fully documented schema and a readOnly annotation, the description covers scope and kind semantics adequately. The one gap is that no output schema exists and the description does not characterize the returned category objects (fields, 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 3 is the baseline, but the description goes beyond the schema's terse 'Which saved list to read' by explaining what each kind actually contains (items with price and unit, tasks/trips with rate). The page/order/per_page parameters are left entirely 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 ('List') and a precise resource ('saved line-item templates') and then disambiguates the four kinds with distinguishing attributes — items carry price and unit, tasks/trips carry a rate. This makes it clearly distinct from siblings like hiveage_list_invoices or hiveage_list_contacts 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 description establishes what the tool returns and for which 'kind', which implies the usage context, but it never states when to prefer this over an alternative or any prerequisite (e.g., needing existing categories). Usage is inferred rather than instructed.

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 only the underlying REST endpoint as context and says nothing about pagination behavior, result ordering, or what happens if the connection has no estimates – modest added value beyond structured fields.

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, front-loaded with purpose and scope, zero filler. The endpoint mapping is arguably redundant but costs little.

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?

Adequate for a simple read-only list, but with no output schema the description could say what each estimate entry contains or note paginated results; those details are left entirely to inference.

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, per_page and hash_key all documented in the schema itself (including the note that hash_key is not the numeric id). The description only reflects hash_key via the URL template, so it adds nothing 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 (List), resource (estimates), and a scoping constraint (of one connection/client) that separates it from the unfiltered hiveage_list_estimates. It does not name the sibling explicitly, so differentiation is implied by scope rather than spelled out.

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 scoping phrase implies when to use it (you have a connection and want its estimates), but there is no explicit when-to-use/when-not guidance and no reference to the sibling list_connection_invoices or list_estimates 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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds the underlying endpoint (GET /network/{hash_key}/invoices) and ordering by date, but says nothing about pagination defaults or result shape beyond what the schema provides.

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, front-loaded with the core action and scope, followed by a compact endpoint pointer. Nothing redundant, though the endpoint reference adds little decision value 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?

For a simple read-only filtered list with full schema coverage and a safety annotation, the description is sufficient to call it correctly. Only pagination behavior and return shape are left implicit, and the latter is partly covered by 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%, so page, per_page, and hash_key are already fully documented in the schema. The description's only added signal is the 'connection (client)' gloss on hash_key, which is marginal over the schema's existing explanation.

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 (invoices) scoped to one connection/client, and adds the ordering ('by date'). It distinguishes itself in substance from hiveage_list_invoices by the 'one connection' scope, though it never names that 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?

Usage is implied by 'one connection (client)': use it when you already have a connection's hash_key. But there is no explicit guidance on when to prefer hiveage_list_invoices or hiveage_get_invoice, and no mention of prerequisites beyond the required hash_key.

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 declares the safe-read profile, so the bar is lower. The description adds only the underlying HTTP route, which does not tell the agent anything about pagination behavior, ordering, or what a returned profile contains; it is neutral rather than contradictory.

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 with the purpose front-loaded; the API route in the second sentence is mild filler but does no harm. No redundancy beyond the restated 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?

A read-only paginated list tool with no output schema, so the description should ideally say something about the returned shape or pagination semantics. The parameter schema covers the inputs, but the description is silent on output and on how pages relate to results.

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 all three parameters (hash_key, page, per_page) are documented in the schema, including the hash_key-vs-numeric-id distinction and the enum-like per_page values. The description adds nothing beyond that, 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?

States a specific verb (List) and resource (recurring invoice profiles) plus the scoping qualifier 'of one connection (client)', which distinguishes it from hiveage_list_recurring_invoices and hiveage_get_recurring_invoice. It stops short of naming those siblings explicitly, so it is clear but not fully disambiguating by name.

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 scope phrase 'of one connection' implies the use case (recurring invoices belonging to a given client), but there is no explicit when-to-use, when-not, or named alternative such as the global list or the single-get tool. The agent must infer the routing decision.

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; the description adds real context on top — default sort key (name), the shape of each record, and the dual identifier scheme with its downstream purpose. It omits pagination/result-envelope behavior, but the page/per_page/order params are schema-documented.

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, front-loaded with the core purpose, then the record shape and identifier guidance. 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?

With no output schema, the description does the work of describing the returned record fields and their purpose, which is the key gap for a list tool. It doesn't address pagination totals or empty results, but nothing essential for correct invocation 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%, so baseline is 3, but the description adds meaning the schema lacks: it establishes that ordering applies to the name field and clarifies the two identifiers (hash_key vs numeric id) that the schema does not distinguish. Page/per_page semantics are left entirely 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 and explains what a 'connection' is (companies, clients, vendors in the network) plus the sort order. It does not explicitly distinguish itself from hiveage_get_connection or the potentially confusing hiveage_list_contacts sibling, 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?

Implies list-style usage and usefully tells the agent where the returned values go (hash_key for other tools, id as connection_id when creating invoices), which nudges toward create-invoice workflows. However, it never says when to use this versus hiveage_list_contacts or hiveage_get_connection, which is the main ambiguity in this tool family.

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 useful scoping detail that results are contacts with an email address on a connection, plus the underlying API route, but says nothing about result volume, pagination or ordering beyond what the schema declares.

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, front-loaded with the action and resource, with the API route as a trailing implementation note. The route reference earns little for an agent but adds negligible 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 read-only, single-required-parameter list tool with full schema coverage, the definition covers what is needed to invoke it correctly. With no output schema, the shape of returned contacts is left implicit, which is the main remaining 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 description coverage is 100%, including the hash_key clarification and the per_page enum values, so the baseline is 3. The description only echoes that listing is per-connection and adds no new meaning about page, order or per_page 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 and resource ("List the contacts ... of a connection") and clarifies what a contact is ("people with an email address for sending statements"), which distinguishes it from hiveage_list_connections and hiveage_get_contact. It stops short of naming a sibling explicitly, so it does not reach 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?

The phrase "of a connection" implies the tool is scoped to a single connection and requires its hash_key, and the sibling get_contact implies a different retrieval path for a single record. However, there is no explicit when-to-use/when-not statement or named alternative, so usage must be inferred.

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 that results are date-sorted and maps to GET /estm, which is modest extra context. It says nothing about whether results are paginated envelopes, how many records come back, or whether draft/sent statuses are all included.

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 with the resource stated first and the endpoint mapping last. Nothing is padded, though the raw endpoint reference contributes little for an agent that already reads structured fields.

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, fully-documented read-only list tool with no output schema, the description supplies the essential scope (all estimates, date-ordered). Only the relationship to the connection-scoped variant is missing, which is a minor gap at this complexity level.

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, order, and per_page are all fully documented with defaults and enum values. The description's 'sorted by date' hints at the sort key but adds no syntax 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 ('List estimates (quotes)') plus the underlying endpoint, so the operation is unambiguous. It does not distinguish itself from the sibling hiveage_list_connection_estimates, which is the one nearby tool an agent could confuse it with.

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?

Listing all estimates is implied by the absence of any filter parameters, but the description never states when to prefer this over hiveage_list_connection_estimates or hiveage_get_estimate. Usage must be inferred from the schema being filter-free.

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 useful context (which states are returned, that totals accompany the records, and that results are date-sorted), but says nothing about pagination behavior or the shape of the response for a paged list with 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 front-loaded sentence carrying the scope, the states, and the sort basis, followed by a short API endpoint reference. Nothing is padded or repeated.

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 paged listing with full schema coverage and no output schema, the description covers purpose, filter scope, and sort basis adequately. The remaining gap is the paged response envelope, which is not described anywhere but is not essential to invoking the tool 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% and all three paging parameters are documented, so the baseline is 3. The description earns an extra point by noting results are sorted by date, which is the missing piece the schema's 'order' parameter never names — it clarifies what field the sort direction applies to.

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), plus the invoice states and the fact that totals and date sorting are included. It does not distinguish itself from the closely related siblings hiveage_list_connection_invoices or hiveage_list_recurring_invoice_invoices, so an agent must infer that this returns the unscoped, account-wide 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?

Usage is only implied: the absence of any contact/recurring filter suggests this is the broad listing, while the sibling tools handle scoped listings. There is no explicit statement of when to prefer this over hiveage_list_connection_invoices or hiveage_get_invoice.

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 'GET /invs/{hash_key}/payments' reference corroborates that this is a safe read. The description adds nothing further about result ordering, empty-invoice behavior, or pagination beyond what the schema shows.

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 terse sentences with the core purpose front-loaded and zero redundant wording; the endpoint reference is compact rather than verbose.

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 list tool with fully documented parameters and annotation coverage, the description gives enough to call it correctly. The only minor gap is that no output shape exists, so return structure (payment fields) is 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%, with page, per_page, and hash_key all documented in-schema (including the hash_key vs numeric id warning). The description adds no parameter meaning of its own, 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?

States a specific verb and resource ('List the payments') with explicit scope ('entered on an invoice'), which separates it from hiveage_get_payment (single payment) and hiveage_list_invoices (invoice-level). It does not explicitly name those siblings, so it falls 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 versus hiveage_get_payment or listing payments through another route, no prerequisites, and no note about pagination flow. The only usage signal is the implied invoice-scoped context.

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 declares the safe read profile, so the description's only added value is the underlying endpoint reference (GET /rinv/{hash_key}/invoices). It says nothing about result volume, whether the parent profile must exist, or any pagination behavior beyond what the schema covers.

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, purpose first, endpoint second. Efficient, though the raw API route is of marginal use to an agent and is the less valuable half.

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 list with a fully documented 3-parameter schema and no output schema, the description is adequate but thin — it does not indicate what an invoice record contains or that an empty list is a valid outcome.

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 hash_key is already documented as a short string rather than a numeric id, so the description adds no parameter meaning of its own. 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 the invoices a recurring invoice profile has generated'), which cleanly scopes it to one profile rather than all invoices. That implicitly separates it from hiveage_list_invoices and hiveage_list_connection_invoices, though neither sibling is named.

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 by the resource scoping; there is no explicit statement of when to prefer this over hiveage_list_invoices or hiveage_get_recurring_invoice, and no prerequisites or exclusions are given.

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 value by naming the fields present in each profile, but says nothing about pagination behavior, ordering, result caps, or authentication beyond the raw endpoint reference.

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, front-loaded with the resource description. The 'Hiveage: GET /rinv' endpoint mapping is cheap and occasionally useful for debugging, though it is marginal value rather than behavioral explanation.

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 read-only list tool with no output schema, the definition covers resource identity, returned fields, and endpoint. The only real gap is pagination/enumeration behavior, which the schema largely compensates for.

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 page and per_page fully documented including allowed per_page values. The description contributes nothing about pagination parameters, so the baseline 3 for schema-covered params 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 states a specific verb and resource (list recurring invoice profiles) and even previews the returned fields (interval, next billing date, occurrences). It does not, however, distinguish this from siblings like hiveage_get_recurring_invoice or hiveage_list_connection_recurring_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?

'List recurring invoice profiles' implies usage for enumeration, but there is no explicit when-to-use guidance and no mention of when the scoped variants (connection recurring invoices, single get) should be preferred. The agent must infer the choice from sibling names 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 idempotentHint=true and destructiveHint=true, so safety and repeat-call behavior are covered elsewhere. The description adds the business effect ('counts as received'), which is genuinely useful context beyond the annotations, but it says nothing about preconditions (must be unrealized), failure behavior, or what changes on the invoice.

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 'WRITE:' and the core semantics, the second gives the transport endpoint. Zero 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?

For a two-parameter mutation with rich annotations, a complete schema, and no output schema, the description covers purpose, effect, and endpoint. It only lacks precondition/error guidance (e.g., what happens when the payment is already realized), which is a minor gap at this complexity level.

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 well documented, including the important hash_key-vs-numeric-id distinction. The description reinforces this with the endpoint template showing where each parameter lands. Nothing is missing.

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 (mark an offline/unrealized payment as realized) plus the resulting state semantics ('counts as received'), which distinguishes it from hiveage_record_payment. The API endpoint is included as corroboration. An agent can tell exactly what this does 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?

The parenthetical '(unrealized)' plus 'so it counts as received' clearly implies this applies to existing pending payments, not new ones — implicitly steering away from hiveage_record_payment. However, no sibling is named explicitly and there is no statement about what to do if the payment is already realized.

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; the description goes further by marking this as a WRITE, disclosing that invoice paid/due totals change, and explaining the unrealized/realized lifecycle for offline payments. It does not say whether a payment can be edited or removed afterward, leaving part of the mutation risk unstated.

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, led by an all-caps WRITE prefix that flags the mutation before anything else. Every sentence carries distinct information (mutation, side effect, lifecycle, endpoint) 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?

For a 5-parameter mutation with full schema coverage and no output schema, the description covers purpose, side effects, and post-state well. It omits any hint about the response (e.g. whether the created payment is returned) and failure modes, which are the remaining gaps.

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 including the hash_key-vs-numeric-id distinction and the payment_method enum is already documented. The description adds no additional parameter-level meaning, 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?

States a specific verb (enter a payment), the resource (invoice payment), and the concrete effect (changes paid and due totals), plus the underlying endpoint. An agent can distinguish it from hiveage_mark_payment_realized and hiveage_list_payments 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 context — recording a payment received on an invoice — and notes that offline methods (cash, check, bank_transfer) are saved unrealized, which implies the follow-up step via hiveage_mark_payment_realized. It stops short of naming that sibling explicitly or stating exclusions, so it is clear but not fully 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 flag destructiveHint=true; the description earns credit by adding that the action cannot be undone and that it emails real people, plus the default/custom template distinction. It stops short of describing delivery failure behavior 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?

Two sentences, front-loaded with the write/irreversible nature, then the mode and endpoint. Nothing 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 7-parameter mutation with full schema coverage and no output schema, the description covers purpose, mode selection and irreversibility adequately. Return-value expectations are unspecified, 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 description coverage is 100%, including the strong confirm=true note and the hash_key vs numeric-id warning, so the schema carries the parameter burden. The description's 'default template, or custom' adds only marginal framing on top.

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 plus resource ('email an estimate to the client') with the default-vs-custom mode spelled out, and the endpoint reference anchors it. An agent can distinguish it from hiveage_send_invoice purely by resource name.

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 default-template-or-custom framing implies when each mode applies, but there is no explicit guidance on when to use this versus hiveage_send_invoice, or on prerequisites beyond what the schema's confirm parameter enforces. 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 only declare destructiveHint=true; the description reinforces this with 'Cannot be undone' and clarifies it emails real people from the connection's contacts, which is meaningful beyond the annotation. Missing are failure modes (invalid recipient, already-delivered invoice) and whether the response reports delivery status, so it stops at 4.

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, front-loaded with the 'WRITE, SENDS EMAIL' safety marker, followed by scope, irreversibility, and the API route. No 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 7 params at full schema coverage, no output schema, and a sparse annotation set, the description covers purpose, mode selection, and irreversibility adequately. It could say more about what happens on partial input (e.g. recipients without subject/message) or the return shape of a delivery call, which keeps it at 4.

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%, including the confirm const, hash_key format note, and the custom-delivery grouping rules, so the structured data already carries the semantics. The description's mention of 'custom recipient/subject/message' largely restates the schema's own mode documentation rather than adding new meaning, so the baseline 3 is 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 and resource ('email an invoice to the client') and immediately discloses the two delivery modes (default template to the connection's contacts vs. custom recipient/subject/message), plus the underlying endpoint POST /invs/{hash_key}/deliver. An agent can distinguish this from hiveage_send_estimate and hiveage_send_invoice_reminder 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?

Clear about the two calling modes (omit recipients for the default template, supply custom recipients/subject/message otherwise) and warns 'Cannot be undone', which sets the bar for when to use it. It does not name alternatives such as hiveage_send_invoice_reminder or state when-not-to-use (e.g. invoice already sent / unpaid), 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?

Beyond destructiveHint it discloses that this sends a real email people will receive and that it 'cannot be undone' — genuine impact context. The confirm-required gate is only in the schema, and rate limits/permissions aren't discussed, so not 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?

Front-loads 'WRITE, SENDS EMAIL' and irreversibility in two dense lines with no filler. The trailing API endpoint notation is mildly redundant for an agent but harmless.

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 7-parameter mutation with no output schema, the description plus rich schema covers what's needed: the destructive nature, the mode selection, and full parameter docs. Only the confirm gate and permission requirements live solely in the 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%, so the schema already documents hash_key, confirm, recipients, subject, message, attachment and blind_copies in detail. The description only implies the default/custom split that those parameters implement, adding little on top of 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: 'email a payment reminder for an invoice', with the two modes (default template vs custom) named. It is clearly distinct in practice from send_invoice or send_estimate, but never explicitly contrasts with those siblings, 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?

Explains the default-vs-custom delivery choice and that results cannot be undone, which tells the agent when to supply custom fields. It does not explicitly say when to prefer this over siblings like hiveage_send_invoice or hiveage_get_invoice, so no 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?

Annotations already declare idempotentHint=true and destructiveHint=true; the description adds the important PATCH behavior that unspecified fields are left untouched, which materially informs an agent about mutation scope. It stops short of saying whether overwritten values are recoverable or what the response body contains, but the key behavioral fact is stated.

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, front-loaded clauses with zero filler — the operation class and the partial-update rule come first, with the endpoint as trailing technical detail. Every element 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 7-parameter mutation with low schema coverage and no output schema, the description covers the essential mutation semantics but leaves per-field meaning and return behavior unaddressed. Adequate to invoke correctly, but not rich enough to be fully self-sufficient.

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 only 29%, so the description must compensate; it does so partially by explaining that all field parameters are optional and only supplied ones apply. It gives no guidance on individual fields (first_name vs last_name, phone vs mobile) or on hash_key versus id, but the core optionality semantics are covered.

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?

Starts with a clear 'WRITE' marker plus a specific verb and resource ('change fields of a contact'), and the parenthetical clarifies partial-update semantics. It is distinguishable from create_contact/list_contacts by the 'change fields' phrasing, though it never explicitly names 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?

The parenthetical 'only the fields you pass are sent' implies when this tool is appropriate (patching an existing contact) versus a create call, and usage is reasonably inferable from the 'WRITE' prefix. However, there is no explicit 'use this instead of X when Y' routing or stated precondition (e.g., contact must already exist).

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