Buildium MCP by usefulapi

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

Annotations only carry destructiveHint=true, so the description has to carry the rest. It discloses that the task is internal, must be assigned to a staff user, and may be linked to property/unit/category with a due date — useful scoping. It says nothing about required permissions, whether the created task is returned, or what happens on failure, so it only partly compensates for the thin annotation set.

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 core meaning, followed by a short endpoint reference. No redundant or filler text.

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

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

No output schema exists, so an agent has no idea what the call returns (e.g. a task id), which matters for chaining into buildium_update_todo_task. For a 10-parameter creation tool with only a destructiveHint annotation, the description also omits permission requirements and error 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 description coverage is 100%, so all 10 parameters are already documented in the schema, including the cross-field constraint that unit_id must belong to property_id and the enum values for status and priority. The description only restates a subset of that (assignee, property/unit, category, due date) without adding format or constraint detail, 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 ('Create an internal to-do task') plus scope (assigned to a staff user, optionally tied to a property/unit and category, with a due date) and the backing endpoint POST /v1/tasks/todorequests. The word 'internal' and 'to-do task' distinguish it from the sibling buildium_create_work_order.

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

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

Usage is implied by 'internal to-do task' versus the work-order sibling, and by the optional property/unit linkage, but the description never says when to choose this over buildium_create_work_order, buildium_update_todo_task, or buildium_list_tasks. No prerequisites are 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?

destructiveHint=true already flags this as a mutating operation, so the bar is lower. The description adds one genuinely useful behavioral fact beyond the annotations: creating a work order can also create and link a new task, and task_id versus task are alternative modes. It says nothing about permissions, consequences, or what the call returns.

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 dense sentences plus the endpoint, with the core purpose front-loaded and the task-vs-task_id branching given next. It loses a little to redundancy, since 'vendor_id and entry_allowed are required' and the line-item shape are already in the schema.

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 12-parameter mutation with nested objects and no output schema, the description covers purpose, the two task modes, required fields, and line items. It leaves half the parameters (entry_notes, vendor_notes, work_details, chargeable_to, invoice_number, entry_contact_ids) unmentioned and gives no sense of the response body an agent should expect.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, including the nested task and line_items objects. The description restates required fields (vendor_id, entry_allowed) and line-item shape, which duplicates the schema rather than adding new semantics such as cross-field validity rules.

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 ('Create a work order for a vendor') and pins it to POST /v1/workorders, which cleanly separates it from buildium_get_work_order and buildium_list_work_orders. It does not, however, distinguish itself from the overlapping buildium_create_todo_task sibling, even though it can create a task as a side effect.

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 real argument-level routing ('Attach it to an existing task (task_id) or create a new task with it'), which tells the agent how to pick between the two creation modes. It offers no tool-level guidance, though — no when-to-use/when-not, no mention of alternatives like buildium_create_todo_task or buildium_update_work_order.

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 the safe read profile, so the bar is lower; the description adds real value by disclosing the returned payload composition (tenants, cosigners, account details, move-out data). It also cites the underlying API endpoint, though it does not discuss auth requirements or whether missing ids error versus return empty.

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 that names the operation and its payload, followed by a compact API reference. No filler, nothing 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 one-parameter read with readOnlyHint and no output schema, the definition is nearly complete: it tells the agent what data comes back. It omits only edge-case behavior such as not-found handling, which keeps it short of a 5.

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

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

Schema coverage is 100% for the single lease_id parameter, so the schema already carries the semantics and a 3 baseline applies. The description only restates that the fetch is keyed by id, adding no format or constraint detail 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 ('Fetch') and resource ('one lease by id') and enumerates the included data (tenants, cosigners, account details, move-out data). The singular 'one lease' cleanly distinguishes it from the sibling buildium_list_leases.

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 id' versus the list counterpart, but the description never states when to prefer this tool over buildium_list_leases or buildium_list_lease_transactions. No exclusions or preconditions 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, and the description is consistent with that. It adds the REST endpoint mapping (GET /v1/rentals/{propertyId}), which is mild routing context, but nothing about error behavior (e.g. what happens for an unknown id) or the returned structure.

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, the action front-loaded and the endpoint detail relegated to a second clause. No wasted words.

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

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

For a trivial single-parameter read whose safety profile is covered by annotations and which has no output schema, the description is sufficient. It could be improved by noting behavior on a missing/invalid id, but nothing essential 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?

With 100% schema description coverage, the single property_id parameter is fully documented in the schema. The description adds only 'by id', which is redundant, 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 ('Fetch one rental property by id'), and the word 'one' implicitly distinguishes it from buildium_list_rental_properties. However, it never names that sibling explicitly, so differentiation relies on inference.

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 singular 'one' versus the list tool. There is no explicit statement of when to prefer this over buildium_list_rental_properties or buildium_get_rental_unit, and no prerequisites are mentioned.

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 only the underlying REST path (GET /v1/rentals/units/{unitId}), which does not disclose any behavioral trait such as what is returned, error behavior for a missing unit, or auth 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 short sentences, zero filler, with the core action front-loaded and the API mapping as supporting detail. Nothing wastes an agent's attention.

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

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

For a simple single-id read tool with full schema coverage and readOnlyHint set, the description covers what an agent needs to invoke it. It would be complete at 5 only if it hinted at the returned unit shape or failure mode, but nothing essential 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% and unit_id is documented with type, positivity constraint, and max value, so the schema carries the parameter semantics. The description adds no format or id-source detail beyond 'by id', making the baseline 3 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 (Fetch) and resource (one rental unit) scoped by id, and the singular 'one' implicitly separates it from list_rental_units. It stops short of explicitly naming the sibling it is not, so it doesn't reach the top tier.

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?

No guidance on when to use this versus buildium_list_rental_units or buildium_get_rental_property, and no stated prerequisites. The intent is only implied by the singular 'one rental unit'.

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 structurally. The description adds only the underlying REST endpoint mapping, with no disclosure of auth requirements, not-found/error behavior, or response shape — modest added value given a low bar.

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 action front-loaded and the endpoint reference following as secondary detail.

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

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

For a simple single-param read tool with annotations covering read-only safety and no output schema to explain, the definition is nearly sufficient; only error/not-found behavior is unaddressed, 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?

With 100% schema description coverage and a single param, the schema already documents tenant_id fully. The description's 'by id' merely restates the parameter rather than adding format or constraint detail 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 and resource ('Fetch one rental tenant by id'), clearly a single-record retrieval. It does not explicitly name buildium_list_tenants as the alternative, but the singular 'one ... by id' contrasts reasonably well with the list sibling.

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

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

Implies usage: call this when you already have a tenant id and need one record. No explicit when-to-use, prerequisites, or contrast with buildium_list_tenants is stated, so the guidance is inferable but not spelled out.

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 only the raw REST endpoint path, which is minor context; it says nothing about error behavior for a missing/invalid id or whether the call is scoped to an authenticated account.

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 very short sentences with the core action front-loaded. The endpoint path in the second sentence is borderline filler for an agent but is harmless and terse.

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?

This is a simple one-parameter read, but no output schema exists and the description never characterizes what a work order record returns, so an agent cannot anticipate the response shape. Adequate but with a clear 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% with a single documented parameter ('The work order id.'), so the baseline of 3 applies. The description's 'by id' adds no format or range detail beyond the schema's integer/positive constraint.

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 with scope: 'Fetch one work order by id.' This inherently separates it from buildium_list_work_orders, buildium_create_work_order, and buildium_update_work_order. It does not explicitly name a sibling, so it stops short of the top mark.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The agent must infer that this is the single-record counterpart to buildium_list_work_orders and that it needs a valid id from a prior list call.

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 safety profile, so the bar is lower. The description adds the return contents and the underlying GET endpoint, but says nothing about pagination behavior, result caps, or default ordering beyond what the schema already provides. Adds some value but not rich behavioral context.

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 purpose followed by filter scope and endpoint mapping. Nothing is redundant or padded; every clause carries information.

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

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

With no output schema, the description responsibly notes the returned payload (contact details, status, applications), and all 13 parameters are documented in the schema. Annotations cover the read-only safety stance. Only the omission of paging/ordering behavior and when-not-to-use guidance keeps it short of complete.

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% across all 13 parameters, so the schema does the heavy lifting and the baseline is 3. The description mirrors several filter names (status, unit, name, email, submission date, entity) but adds no format or constraint detail beyond the schema, and omits limit/offset/orderby entirely.

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 (rental applicants), and even names what the records contain (contact details, status, applications). It also maps to the API endpoint. No sibling of this list family competes for 'applicants', so differentiation is implicit rather than stated.

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 enumerates the filterable dimensions (status, unit, name, email, submission/update date, entity), which implies how to narrow results, but it never states when to prefer this over related lookups (e.g. list_tenants) or any conditions/exclusions. Usage is implied, not prescribed.

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 the read-only safety profile, so the description's added burden is small. It contributes the upstream endpoint (Buildium: GET /v1/associations) and the shape of returned records, but says nothing about default result volume, paging behavior, or empty-result handling beyond what the schema's limit/offset already state.

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

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

Two short sentences: the resource and returned fields are front-loaded, followed by the endpoint. No filler, no repetition of schema content.

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 100% schema coverage, no output schema, and a readOnlyHint annotation, the main missing piece would be the return shape — and the description partially covers that by naming the fields each association carries. Only the pagination/volume characteristics of a 9-parameter list call go 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 description coverage is 100%, so all nine parameters (ids, limit, offset, status, orderby, location, last_updated_from/to, operating_bank_account_ids) are already documented with formats and defaults. The description adds no filtering, sorting, or paging semantics, 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 clear verb ('List') and specific resource ('community/HOA associations'), plus the fields the records carry (address, manager, reserve, fiscal year, operating bank account). No sibling does this resource, so an agent can select it unambiguously 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?

Usage is only implied — 'list associations' tells the agent this is the retrieval path for association data, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative or exclusions. Adequate but with a clear 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?

Annotations already declare readOnlyHint=true, and the description restates 'Read-only', which is consistent rather than contradictory. It adds the backing endpoint (GET /v1/bills) but no pagination behavior, result caps, or rate-limit context beyond what the schema's limit/offset already convey. With annotations carrying the safety profile, this is adequate but not rich.

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, front-loaded with what is returned before the read-only note and endpoint. Very little waste, though 'Read-only' mildly duplicates the annotation and the endpoint reference is optional metadata for an agent that never calls the raw API.

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 11 optional parameters, no output schema, and no nested objects, the description usefully compensates by enumerating the shape of returned bills. Pagination and filtering semantics live in the schema, so nothing critical is missing, but it stops short of describing paging defaults or result ordering 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 description coverage is 100% across all 11 parameters (limit, offset, orderby, entity_id/entity_type, paid_status, paid dates, reference_number, approval_statuses), so the schema does the heavy lifting. The description adds no parameter-level detail (e.g. that entity_type is required alongside entity_id) beyond the schema text. Baseline 3 is correct.

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+resource ('List vendor bills (accounts payable)') with a parenthetical clarifying the domain, plus an enumeration of the returned fields (dates, memo, vendor, work order, reference number, approval status, lines). It also names the backing endpoint, so an agent can distinguish it from the other list_* siblings (leases, vendors, work orders) 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?

Usage is implied by the resource (fetch AP bills), but there is no explicit when-to-use vs. alternatives, no mention of filtering strategies, and no note about when a different sibling (e.g. buildium_list_outstanding_balances) would be preferable. Minimum-viable context only.

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 signals a safe read, and the description adds real value on top by listing the shape of the returned records and naming the backing endpoint (GET /v1/glaccounts). With no output schema, this return-content disclosure is the main behavioral signal an agent needs, though pagination behavior is left entirely to the 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?

Three short sentences, front-loaded with what is listed, followed by the use case and the endpoint mapping. Nothing is padded, though the raw endpoint reference is of marginal value to an agent that already sees the tool name.

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, no-required-parameter list tool with full schema coverage and annotations covering safety, the description is nearly complete: it says what is returned, why to call it, and what endpoint it maps to. Only explicit paging behavior is missing, and that is inherited from 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% -- limit, offset, orderby, and account_types all carry their own documentation, including defaults and the enum values. The description adds nothing about parameters, 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 (List) and resource (chart of accounts / GL accounts) and even enumerates the fields returned: number, name, type/subtype, sub-accounts, and bank/credit-card flags. It is unambiguous and easily separable from the other list_* siblings, none of which touch the GL chart of accounts.

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 a concrete use case -- finding the gl_account_id needed for work order line items -- which tells the agent when this tool belongs in a chain. It offers no explicit when-not or named alternative, but no sibling overlaps in scope, so the guidance is sufficient in practice.

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 the safe-read profile, so the bar is lower. The description adds the backing endpoint (GET /v1/leases) and the return payload composition, which is useful context. It says nothing about pagination behavior, rate limits, or authentication, which the annotations do not cover either.

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 dense sentences with no filler: the return payload leads, the filter surface follows, and the endpoint tag closes it. Every clause carries distinct information.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields, and it covers 15 optional filters adequately through the schema. The only gap is the absence of guidance on paging behavior and on the single-lease alternative, minor for a read-only list tool.

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 all 15 parameters are already documented with types, formats, and ranges. The description mirrors the filter categories and repeats the Active/Past/Future status values that the schema enum already supplies, adding no syntax or format detail beyond it. 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 ('List leases') and enumerates the fields the result carries (unit, dates, lease type/status, tenants, rent/deposit accounts, eviction flag), so the agent knows exactly what comes back. It does not explicitly differentiate itself from the sibling buildium_get_lease, leaving the singular/plural distinction to be inferred.

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 lists every filter dimension (property, owner, unit number, tenant name, dates, lease type/status), which implies when the tool is useful for bulk/scanning queries. However it never states when NOT to use it or points to get_lease for a single-record lookup, so the boundary against the sibling is left unstated.

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 description reinforces with 'Read-only — this server never posts to a ledger,' which usefully rules out write intent for an agent wary of mutation tools. It also discloses the underlying endpoint (GET /v1/leases/{leaseId}/transactions), though it says nothing about paging behavior or result volume 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?

Three short clauses, front-loaded with the resource and return content, followed by the safety statement and endpoint mapping. No filler sentences; each element carries information.

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

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

With no output schema, the description usefully enumerates the return fields (date, type, total amount, journal lines), covering the biggest gap. It omits paging expectations and result volume, but the schema's limit/offset parameters and defaults partially cover that.

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 all seven parameters (limit, offset, orderby, dates, transaction_types) are already documented in the schema — the baseline is 3. The description adds only a topical hint at the transaction categories returned, not syntax or filtering semantics beyond what the schema states.

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 specific verb+resource ('Read a lease's ledger') and enumerates the transaction content it returns (charges, payments, credits, refunds, deposits, journal lines). This clearly separates it from the sibling buildium_list_leases, which lists leases rather than ledger activity.

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 'read a lease's ledger' and the required lease_id, so an agent can infer this is for per-lease transaction history. However, it names no alternative (e.g. buildium_list_outstanding_balances or buildium_list_bills) and gives no when-not guidance 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 is a safe read. The description adds real value beyond the annotation: it discloses the exclusion of zero/credit-balance leases, enumerates the aging buckets returned, and cites the backing endpoint (GET /v1/leases/outstandingbalances), which signals the data source and likely pagination surface.

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 dense sentences with no filler; the report purpose and its distinguishing exclusion are front-loaded, and the API endpoint is tucked at the end where it does not obstruct the primary meaning.

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 10-parameter filtered-list tool with no output schema, the description does useful work by naming the returned fields (aged buckets, total balance, dates), partially compensating for the missing return schema. Filter semantics and paging are left entirely to the well-covered schema, so nothing critical is absent.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters including enums and paging. The description's mentions of aging buckets, past-due email, and eviction dates loosely map to balance_duration, past_due_email, and eviction_status but add no format or syntax 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 ('Delinquency report: leases that owe money') plus the exact payload it produces (aged buckets, total balance, past-due-email and eviction-pending dates). It is clearly distinguishable from the sibling buildium_list_leases because it is scoped to delinquent leases only.

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 clear context for when this tool is appropriate (delinquency reporting) and an explicit data exclusion ('leases with zero or credit balances are not returned'), which prevents the agent from expecting a full lease roster. It does not, however, name an alternative sibling such as buildium_list_leases for the non-delinquent case.

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=true annotation already establishes this is a safe read, so the description's bar is lower. It usefully enumerates the returned fields and cites the underlying endpoint (GET /v1/rentals/owners), but says nothing about pagination defaults, rate limits, or ordering behavior beyond what the schema's own parameter docs already state.

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

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

Two tight sentences: purpose and return contents first, API mapping second. No filler, nothing redundant with structured fields, and the key differentiating parenthetical is front-loaded.

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

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

For a 10-param, zero-required list tool with no output schema, the description adequately conveys what comes back by naming the returned field groups, and the schema covers all filters. It falls short of 5 only because it omits paging/ordering behavior that an agent consuming a large owner list would want.

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 all ten parameters are already documented in the schema itself; the description adds no parameter-level syntax or filtering semantics beyond the field list. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb ('List') and resource ('rental owners'), disambiguates with a parenthetical ('the landlords you manage for'), and previews returned content (contact details, agreement dates, property ids). An agent can distinguish this from list_tenants or list_vendors 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Usage is only implied by the verb 'List', so the agent must infer that this is the read path for owner entities.

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 establish readOnlyHint=true, so the safety profile is covered, and the description reinforces it by naming the underlying GET endpoint. It adds useful context about the fields returned and the contains-matching semantics of the location filter, though it says nothing about pagination limits or rate behavior beyond what the schema states.

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 sentences: purpose first, filters second, API mapping last. Every clause carries information and nothing is repeated or 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?

With no output schema, the description usefully enumerates the returned fields, compensating for the missing return documentation. For an 11-parameter read-only list tool with full schema coverage, this is nearly complete, missing only details like paging defaults or result caps that a caller might want.

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 is already documented, including limit/offset paging and the orderby syntax. The description's filter list largely restates those parameters, adding only the 'city/state contains' nuance already present in the schema, so the baseline of 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?

Names a specific verb (List) and resource (rental properties/buildings), and immediately clarifies the entity is buildings rather than units, which cleanly separates it from buildium_list_rental_units and buildium_get_rental_property. It also previews the returned fields, so the agent knows the shape of results before calling.

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?

Enumerates the available filter dimensions (location, type, subtype, status, rental owner, property ids), which tells the agent when this tool is applicable. It stops short of naming alternatives or stating exclusions, so it is clear context without explicit 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 readOnlyHint=true, so the safety profile is covered. The description adds value by naming the API endpoint and enumerating returned fields, but says nothing about paging behavior, default limits, or whether the list is scoped to the authenticated account.

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 sentences with the resource and returned fields front-loaded and no filler. The trailing endpoint reference is marginally useful for traceability but is not required by 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 no-required-param read-only list tool with a fully documented schema and no output schema, the description covers enough: it enumerates the fields returned so the agent knows what it gets back and states the filtering dimension. Paging and default-limit behavior are left to 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 all six parameters (limit, offset, orderby, property_ids, updated-from/to) are fully documented in the schema itself. The description only gestures at the property filter and adds no syntax or format detail beyond what the schema provides.

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 ("List rental units") and itemizes the returned fields (unit number, beds/baths, size, market rent, listed/occupied status), which goes beyond a tautology. It does not distinguish itself from sibling buildium_get_rental_unit or buildium_list_rental_properties, so an agent must infer the single-vs-collection split itself.

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?

"Filter by property" implies the primary use case and corresponds to the property_ids parameter, so usage is suggested rather than spelled out. There is no when-not guidance and no mention of sibling alternatives such as get_rental_unit for a single unit.

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 safe-read profile is covered. The description adds the returned field set (category, property, unit, requester, assignee, status, priority, due date) and the underlying endpoint, but says nothing about pagination behavior, result caps, or how filters combine — meaningful context it could have supplied.

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

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

Front-loaded with the core verb and resource, then the returned field set, then the endpoint line. Dense but every clause carries signal, especially the field enumeration given there is no output schema.

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 17-parameter, zero-required list endpoint with no output schema, the description covers scope and returned fields but omits paging defaults, maximum result expectations, sort behavior, and the entity_type/entity_id dependency. Adequate but with clear 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%, with all 17 parameters individually documented (limits, date formats, enum values, entity_type/entity_id coupling), so the schema does the heavy lifting. The description's field list refers to returned fields, not parameters, and adds no filter 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?

States a specific verb and resource ('List all tasks/requests') and enumerates the four concrete subtypes it returns, which maps directly to the type enum. It does not, however, explicitly contrast itself with buildium_list_work_orders, the closest sibling, so differentiation is left to inference.

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 says what the tool returns but never states when to choose it over buildium_list_work_orders or the get_* siblings, nor any prerequisites or exclusions. An agent gets no routing guidance beyond the resource name.

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 genuine context beyond that: the shape of returned records (contact details, emergency contact, address, leases) and the upstream endpoint (GET /v1/leases/tenants). It does not mention pagination or result-size behavior, which the schema covers only via limit/offset.

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 with the core purpose and return content front-loaded. The filter enumeration in the second sentence partially duplicates the schema rather than adding value, which keeps it short of a 5.

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

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

For a 14-parameter, no-required, read-only list tool with no output schema, the description covers what is listed, what records contain, the filterable axes, and the backing endpoint. Pagination and sort behavior are left to the schema, which is acceptable, so the definition is adequate though not exhaustive.

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's match semantics are already documented (contains-value, enum values, date format). The description's filter list largely restates a subset of those parameters and omits limit, offset, orderby, and the last_updated range, so it adds little meaning 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 rental tenants') and enumerates what the records contain (contact details, emergency contact, address, leases). This clearly distinguishes it from buildium_get_tenant (single record) and from other list tools such as buildium_list_applicants or buildium_list_leases.

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 filter enumeration ('Filter by name, email, phone, unit number, property, owner, unit ids or lease term status') implies the browse/lookup use case, and the Buildium endpoint mapping gives context. However, there is no explicit when-to-use, when-not-to-use, or routing to alternatives like buildium_get_tenant or buildium_list_leases when a tenant isn't the right index.

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 and the bar is lower. The description adds the upstream endpoint (GET /v1/vendors) and the returned field set, but says nothing about pagination behavior, result caps, or rate limits — despite the tool having limit/offset parameters.

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 plus an endpoint reference; the core purpose is front-loaded and nothing is padded. The trailing "Buildium: GET /v1/vendors" is a small but non-wasteful implementation anchor.

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 11-parameter, read-only list tool with no output schema, the description covers purpose, filter surface, returned fields and the underlying endpoint. What it lacks — pagination and ordering guidance — is already captured in the schema, so an agent can 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 all 11 parameters are documented in the schema and baseline is 3. The description reinforces the free-text 'contains' filters (name, email, phone, website) and status/insurance windows, but omits limit, offset, orderby and the last_updated range — adding only marginal value over 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 disambiguates the domain term by glossing vendors as "contractors, suppliers". It also enumerates the payload fields (contact details, category, insurance, default expense GL account), so an agent can distinguish it from sibling list tools like list_tenants or list_rental_owners 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 description names the filterable dimensions (name, email, phone, website, status, insurance expiration), which implies when the tool is useful, but it gives no explicit when-to-use/when-not guidance and does not point at any alternative sibling. Adequate but leaves routing to inference.

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

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

The readOnlyHint annotation already declares this a safe read, so the bar is lower. The description adds the upstream API mapping (GET /v1/workorders) and confirms the shape of returned data, which is useful context, but it says nothing about pagination defaults, result caps, or ordering behavior beyond what the schema already encodes.

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, both front-loaded: returned fields first, then filterable dimensions, then endpoint. No filler. Slightly dense but every clause carries information.

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

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

With 22 optional params and no output schema, the description usefully previews the returned fields and all filter families so an agent can plan a query without opening the schema. The main omission is pagination/result-cap behavior, though limit and offset are documented 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% with 22 documented parameters, so the schema carries the semantic burden and baseline is 3. The description groups the filter families into a readable list but adds no syntax, format, or combination rules beyond that grouping.

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 (work orders), enumerates the fields returned (title, status, priority, due date, vendor, amount, line items, linked task/bill ids), and names the underlying endpoint. This clearly distinguishes it from buildium_get_work_order (single fetch) and buildium_list_tasks.

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 enumerates the filter dimensions available (entity, status, priority, task type, unit, vendor, assignee, dates, amount, billed flag, title), implying this is the query tool for work orders. However, it never states when to prefer it over buildium_get_work_order or how it relates to buildium_list_tasks/list_bills, so usage is inferred rather than guided.

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 adds substantive context beyond that by explaining Buildium's PUT replaces the whole record, so the tool reads the current task first and only mutates fields passed. This directly clarifies partial-update semantics and explains why the hint is set. It does not cover auth requirements, failure modes, 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 front-loaded sentences cover the operation and its read-modify-write behavior, with the endpoint appended as a compact implementation note. Every element earns its place, though the raw endpoint string is somewhat developer-oriented padding for an agent-facing description.

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 11-parameter mutation tool with no output schema and only a destructiveHint annotation, the description supplies the critical missing piece: that this is a read-then-write partial update rather than a blind overwrite. Remaining gaps (permission needs, invalid-id behavior, whether 'message' is a durable note) are minor.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, including the status/priority enums. The description restates a subset of field names (status, priority, assignee, due date, title, category, message) but adds no format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Update) and resource (to-do task), then enumerates the mutable fields so the agent knows exactly what can change. The endpoint reference (GET then PUT /v1/tasks/todorequests/{toDoTaskId}) pins it unambiguously against buildium_create_todo_task and buildium_update_work_order.

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

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

The field list implies when the tool applies (changing status, priority, assignee, etc.), and one example ('mark Completed') is given, but there is no explicit when-not guidance and no sibling routing such as 'use buildium_update_work_order for work orders'. Usage is inferable 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?

Adds substantial behavior beyond the single destructiveHint annotation: it explains the read-before-write strategy needed because Buildium's PUT is a full replace, enumerates what is preserved (line items, entry contacts), and flags that passing line_items/entry_contact_ids destroys existing values. This is exactly the kind of destructive-blast-radius detail an agent needs.

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 tight sentences, front-loaded with the core purpose and immediately followed by the destructive/replace semantics. The closing API line ('Buildium: GET then PUT /v1/workorders/{workOrderId}') is compact and reinforces the read-modify-write model rather than 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?

For an 11-parameter mutation tool with no output schema, the definition covers preservation, replacement traps, and where non-editable fields live — the main things an agent must know. It stops short of describing what the call returns or any permission/validation failure modes, which would round it out.

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, and indeed the description's parameter guidance ('Passing line_items REPLACES all existing line items') largely mirrors the schema's own 'Replace ALL line items with this list.' and 'Replace the entry contact user ids.' The only marginal addition is the overall partial-update framing.

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 ('Update a work order's details') and goes further by scoping the operation as a read-then-write against '/v1/workorders/{workOrderId}'. Its siblings (buildium_get_work_order, buildium_create_work_order, buildium_list_work_orders) are clearly distinguished by the update framing and the explicit redirect of status/priority/due-date to the linked task.

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 operational context: PUT replaces the whole record, so the tool does a read-modify-write preserving unpassed fields, and line_items/entry_contact_ids are full replacements. It also signals that status, priority, and due date belong on the linked task, implicitly routing to task tooling, though it never names buildium_update_todo_task explicitly.

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