buildium

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

Annotations provide only destructiveHint=true, so the description carries most of the behavioral burden. It confirms the write via the POST /v1/tasks/todorequests endpoint, but says nothing about permission requirements, what the caller gets back, or any side effects of assignment.

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, with the core purpose front-loaded before the endpoint reference. The trailing API path adds little an agent needs but wastes very little space.

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 creation tool with no output schema and minimal annotations, the description covers the what but omits return shape, permission scope, and validation behavior (e.g., unit/property coupling). 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%, so every parameter is already documented and the baseline is 3. The description adds only the optionality groupings (property/unit/category/due date as optional) but does not explain the required vs optional split or the unit-must-belong-to-property constraint already in 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 ('Create an internal to-do task') and qualifies it as staff-assigned with optional property/unit/category ties. The 'internal' framing distinguishes it from buildium_create_work_order, which is the main adjacent 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?

The description implies a context (internal staff task) but never states when to choose this over buildium_create_work_order or how to route between them. No exclusions or prerequisites are given, so usage must be inferred from the sibling list.

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 annotation only supplies destructiveHint=true, which the description is consistent with ('Create'). Beyond that, the description adds the required-parameter constraint (vendor_id, entry_allowed) and the API endpoint, but says nothing about permissions, idempotency, side effects, or what happens if both task and task_id are supplied. Useful 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?

It is a single dense paragraph that front-loads the purpose, then the task linkage options, then required fields, then optional line items, then the endpoint. Every clause carries information, though the run of parenthetical field lists is dense and could be slightly tighter.

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 create tool with nested objects, no output schema, and only a destructiveHint annotation, the description covers the key decision points (task vs task_id, required fields, line items). It omits several scalar params (entry_notes, vendor_notes, work_details, chargeable_to, invoice_number, entry_contact_ids) and any return-value note, but schema coverage is 100% so those gaps 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by framing task_id and task as mutually alternative linkage mechanisms and by summarizing what the nested task object carries (title, priority, status, assigned staff, optional due date/property/unit) and that line items are optional with an optional GL account.

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 opens with a specific verb+resource ('Create a work order for a vendor') and immediately clarifies scope via the vendor requirement. It is trivially distinguishable from siblings like buildium_update_work_order, buildium_get_work_order, and buildium_create_todo_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?

It gives clear selection guidance for the main branching decision — 'Attach it to an existing task (task_id) or create a new task with it (task)' — which is exactly the ambiguity an agent would hit. It stops short of naming alternative tools or stating when not to use this tool, 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context by disclosing the shape of the payload (tenants, cosigners, account details, move-out data) and mapping to the underlying GET /v1/leases/{leaseId} endpoint, which helps the agent anticipate the response. It omits auth/rate-limit details, but none are strictly required here.

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 operation and its payload, followed by the endpoint mapping. No filler and nothing repeated from 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?

There is no output schema, so the description usefully compensates by naming the included sub-resources. For a single-parameter read tool this is nearly sufficient; only error/not-found behavior is left 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?

Schema description coverage is 100% for the single lease_id parameter (integer, >0), so the schema already carries the semantics. The description only restates 'by id' and adds no format or constraint detail beyond it, 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 lease by id') and scopes it as a single-record retrieval, which separates it from buildium_list_leases without needing to open either schema. It also enumerates the included sub-resources (tenants, cosigners, account details, move-out data).

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 word 'one' implicitly contrasts with the sibling buildium_list_leases, so the intended usage is inferable. However, no alternative is named explicitly and there are no stated preconditions or exclusions (e.g. what to do if the id is unknown).

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 that this is a safe, non-mutating read, so the description's burden is lower. It adds the underlying REST endpoint (GET /v1/rentals/{propertyId}), which is mildly useful for tracing, but discloses nothing about error behavior (e.g., 404 on unknown id) 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, front-loaded sentences with zero filler: the action comes first and the endpoint mapping is a compact trailing clause. Nothing needs trimming.

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 readOnlyHint coverage this is close to adequate, but no output schema exists, so the description should ideally say something about what is returned or what the caller can expect on failure. It leaves the agent to guess at the response 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 description coverage is 100% and the single property_id parameter is already documented in the schema, so the schema carries the parameter semantics. The description only restates 'by id' and adds no format, range, or sourcing 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?

The description states a specific verb (Fetch) and resource (one rental property) scoped by id, and the word 'one' implicitly separates it from the sibling buildium_list_rental_properties. It does not explicitly name the sibling, so it falls just short of full sibling differentiation.

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 id' tells the agent this is a point lookup rather than a search or list, which is sufficient for such a simple tool. However, there is no explicit when-to-use guidance, no mention of the list sibling as the alternative, and no note about what happens when the id is invalid.

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 underlying REST endpoint, which is useful reference context but not behavioral disclosure; it says nothing about what happens when the id is not found or what the response contains. With annotations carrying the safety signal, a 3 is appropriate.

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 action and resource front-loaded and the API mapping relegated to a supporting clause. 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 single-parameter read tool with readOnlyHint provided and no output schema, the description gives enough to call it correctly. Only minor gaps remain, such as not-found/error behavior, which is not essential here.

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 there is a single parameter, so the schema already documents unit_id fully. The description's 'by id' merely echoes this, adding no format 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 ('Fetch') and resource ('one rental unit') scoped by id, so an agent can tell it apart from buildium_list_rental_units by the singular 'one' framing. It does not explicitly name the list sibling, but the distinction is 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?

'Fetch one rental unit by id' implies you use it when you already have a unit id, but there is no explicit when-to-use or when-not-to-use guidance and no reference to the list sibling for discovery scenarios. 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?

The readOnlyHint annotation already establishes this is a non-destructive read, so the description doesn't need to restate safety. It adds only the upstream endpoint mapping (GET /v1/leases/tenants/{tenantId}), with no mention of not-found behavior, id scoping (tenant vs lease tenant), or return shape.

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 with zero filler, and the core purpose is front-loaded before the API detail. 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?

Adequate for a simple get-by-id call with full annotation and schema coverage, but with no output schema the description could say what a tenant record contains or how it differs from a lease. Enough to call it correctly, not enough to be 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% and there is a single parameter, so the schema fully documents tenant_id. The description's 'by id' adds no syntax, format, or constraint detail beyond it; 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?

Specific verb plus resource ('Fetch one rental tenant by id'), and the word 'one' contrasts with the sibling buildium_list_tenants without naming it explicitly. The sibling set contains a near-identical list tool, so an explicit pointer would have earned a 5, but the singular/plural distinction is 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 implied: call this when you already have a tenant id and want a single record, rather than the list endpoint. There is no explicit when-to-use, when-not-to-use, or named alternative, so it stays at minimum-viable.

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 Buildium endpoint mapping (GET /v1/workorders/{workOrderId}), which is metadata rather than useful behavioral context; it says nothing about failure behavior (e.g., unknown id) or return shape.

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

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

Two tightly scoped sentences with the action front-loaded and 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 single-parameter read tool with annotations covering the safety profile and no output schema to explain, this is just about adequate. It omits any note on error/not-found behavior or what the fetched work order contains, leaving minor 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% and the sole parameter is fully documented in the schema, so the baseline is 3. 'By id' in the description adds nothing beyond what the schema already 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 and resource ('Fetch one work order by id'), which clearly distinguishes it from the sibling list_work_orders and the create/update work order tools. It does not name a sibling explicitly, so it falls just short of 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 when-to-use guidance, no prerequisites, and no explicit routing to alternatives such as buildium_list_work_orders. The single-item scope is only implied by the name and 'by id'.

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 the underlying endpoint (GET /v1/applicants), which is minor context, but says nothing about pagination defaults, result caps, or auth. Adequate but not rich beyond annotations.

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

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

Two tight sentences with the purpose front-loaded and the endpoint reference tucked at the end. No filler; 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?

For a 13-param, zero-required list tool with no output schema, the description signals the return shape ('contact details, status and their applications') and the endpoint. Schema handles parameter detail fully. Slight gap in paging/limit behavior, but overall 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 100% and each of the 13 parameters is already documented there. The description's filter list ('status, unit, name, email, submission date or entity') restates schema fields without adding format or syntax detail, 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 (rental applicants) plus the payload contents (contact details, status, applications). This is clearly distinguishable from sibling list tools such as buildium_list_tenants and buildium_list_associations.

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, implying how the tool is used, but gives no when-to-use/when-not guidance or alternatives (e.g. a 'get applicant' sibling). 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/associations) and enumerates the returned fields, but says nothing about pagination behavior, filtering defaults, or result size beyond what the schema documents.

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 with zero filler. The core purpose and returned attributes are front-loaded, with the API reference as a trailing 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?

With no output schema, the description usefully enumerates the returned fields, which is the main missing piece for a listing tool. Combined with a fully documented nine-parameter schema and readOnlyHint, an agent has enough to call it correctly, though pagination/output shape remains only implied.

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 nine parameters documented including paging (limit/offset), date formats, and sort syntax. The description adds no parameter-level meaning beyond the schema, so the baseline of 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 a precise resource (community/HOA associations), plus the fields returned (address, manager, reserve, fiscal year, operating bank account). No sibling tool covers associations, so differentiation is implicit rather than stated, which keeps this just 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?

The description says nothing about when to use this tool versus alternatives such as buildium_list_rental_properties, nor any prerequisites or exclusions. The listing context is inferable from the verb 'List', but no explicit guidance is offered.

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 it ('Read-only') without contradicting. It adds genuinely useful context beyond the annotation by naming the underlying endpoint (Buildium: GET /v1/bills) and enumerating what the response contains, though it says nothing about paging defaults 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 short sentences, front-loaded with the resource and scope, then the endpoint reference. Every clause earns its place 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 an 11-param read-only list tool with no output schema, the description covers purpose, scope, read-only nature, and the returned field set, which compensates for the absent output schema. It is slightly thin on pagination/filtering behavior, but the schema carries those details.

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 params (limit, offset, orderby, entity_id/vendor_id/entity_type, paid_status/dates, reference_number, approval_statuses) are already fully documented in the schema. The description adds no parameter-level syntax or format 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 ('List') and resource ('vendor bills (accounts payable)'), and enumerates the fields returned (dates, memo, vendor, work order, reference number, approval status, lines). An agent can distinguish it from the other list_* siblings by resource alone 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 read/list framing plus the filter parameters, but there is no explicit when-to-use statement, no when-not-to-use, and no routing to alternatives such as buildium_list_lease_transactions or buildium_list_outstanding_balances for related AP questions.

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 this is a safe read. The description adds the underlying Buildium endpoint and the shape of returned records, but says nothing about result size, paging behavior, or rate limits beyond what the schema states. Reasonable 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 tight sentences: scope, use case, endpoint. The resource scope is front-loaded and no sentence is 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 annotations covering safety and the schema covering paging/sorting, the description is nearly complete; listing return fields compensates for the absent output schema. Minor gap: no explicit note on default page size or how to fetch all accounts.

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 limit, offset, orderby and account_types are already fully documented. The description names account attributes but adds no syntax or filtering semantics for the parameters themselves; 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?

Specific verb (List) + resource (chart of accounts / GL accounts), and it enumerates the returned fields (number, name, type/subtype, sub-accounts, flags), which no sibling provides. An agent can distinguish it from buildium_list_bills or buildium_list_lease_transactions immediately.

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 downstream use case ('finding the gl_account_id for work order line items'), which tells the agent when this tool is the right call. It stops short of naming alternatives or stating when-not to use it, 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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that the description discloses the returned payload's composition, including the eviction flag and rent/deposit account details, which is genuinely additive since no output schema exists. It does not mention rate limits or pagination semantics, but limit/offset are already documented in 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?

Two sentences: the first front-loads what is returned, the second lists the filter surface and the endpoint. No filler, no restating of the tool name, and the most decision-relevant content leads.

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 15-parameter, all-optional list tool with no output schema, the description covers both the input facets and the returned record shape well enough to call it correctly. It stops short of describing result ordering or the response envelope, which the absent output schema would otherwise have carried.

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, ranges and formats. The description restates the filter facets and repeats the lease-status enum values already present in the schema, adding no format or syntax detail beyond it. 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?

The description gives a specific verb+resource ('List leases') and immediately enumerates the record shape it returns (unit, dates, lease type/status, current tenants, rent/deposit account details, eviction flag). This clearly separates it from the singular sibling buildium_get_lease and from the adjacent list_tenants / list_rental_units tools.

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

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

It states the filtering dimensions an agent would use to reach for this tool (property, owner, unit number, tenant name, dates, lease type or status) and even names the allowed status values, which gives clear usage context. It does not, however, name an alternative or state when *not* to use it (e.g. that get_lease should be used for a single lease id).

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 safety profile, yet the description reinforces it with 'this server never posts to a ledger' and adds genuinely useful context by naming the returned fields (date, type, total amount, journal lines). It stops short of describing paging behavior or result shape in detail.

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 plus an endpoint reference; the returned-content summary comes first and the read-only guarantee and API path follow. No filler and nothing redundant.

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 sketches the return contents, and pagination/sorting are covered by the schema. It lacks any note on default page size behavior at the description level or how journal lines are nested, leaving a small gap for a list tool of this size.

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, lease_id, transaction_types, date range) are already documented in the schema. The description only loosely gestures at 'date, type' without adding format or syntax beyond what the schema supplies, 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 ('Read a lease's ledger') and enumerates the transaction kinds returned, which clearly separates it from siblings like buildium_get_lease (lease detail) or buildium_list_leases (lease roster). The Buildium endpoint mapping further pins down the exact scope.

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 and the read-only note, but the description never says when to prefer this over buildium_get_lease or buildium_list_outstanding_balances, nor does it state prerequisites such as needing a valid lease id. Adequate but no 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?

readOnlyHint=true already declares the safety profile, and the description adds substantive context beyond annotations: the aging-bucket structure, the implicit exclusion of zero/credit balances, and the presence of eviction/past-due-email state in results. It does not mention pagination defaults or result caps, but those live in 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?

Front-loads the core purpose and the return contents in a single dense sentence, then appends the upstream API path. No filler, though the API-path sentence offers little to an agent that cannot call Buildium directly.

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 10 optional parameters, no output schema, and no nested objects, the description does the important work of sketching what the report returns and what is excluded. A reader knows what to expect back without an output schema; only pagination behavior is left unstated and is covered by 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 coverage is 100%, so all 10 parameters including the four enums (balance_duration, past_due_email, eviction_status, lease_statuses) are already documented in the schema. The description's aged-bucket mention loosely reinforces balance_duration but adds no syntax or format meaning beyond what the schema supplies. 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+resource ('Delinquency report: leases that owe money') and enumerates the returned dimensions (aged buckets, total balance, past-due-email and eviction-pending dates). This clearly distinguishes it from the sibling buildium_list_leases and buildium_list_lease_transactions.

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 an explicit negative scoping rule — 'Leases with zero or credit balances are not returned' — which tells the agent this is a filtered subset view rather than a full lease list. No explicit named alternative is given (e.g., 'use list_leases for all leases'), so it falls short of the 5 bar.

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, non-mutating read, so the description needn't restate safety. It adds concrete value by naming the returned shape (contact details, agreement dates, owned property ids), but says nothing about pagination defaults, result volume, or auth requirements beyond what the schema implies.

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

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

Two tightly written sentences with zero filler; the resource definition and return contents are front-loaded and the API endpoint trails as a compact reference.

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 list endpoint with no output schema and fully documented parameters, the description covers purpose, scope, and the salient returned fields, which is nearly all an agent needs. It stops short of noting that all parameters are optional and that results are paged, which would have completed the picture.

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 one of the ten filters (limit, offset, status, orderby, date ranges, phone, owner_name, property_ids) is already documented with format and defaults. The description adds no filter-specific syntax or 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 specific verb and resource ('List rental owners') and immediately disambiguates the domain term with a parenthetical ('the landlords you manage for'). It also names the returned fields, so an agent can distinguish it from buildium_list_tenants or buildium_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 guidance on when to use this tool versus siblings, nor any mention of the filtering scenarios its ten optional parameters enable. The only routing signal is the resource noun itself, which the agent must infer.

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 confirms the read nature via 'GET /v1/rentals'. It adds the endpoint mapping but nothing about throttling, auth scope, result caps, or paging behavior; the safety profile is already carried by 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?

Three short sentences, front-loaded with the resource and returned fields, then filters, then endpoint. Efficient, though the filter sentence and the endpoint note are largely duplicating structured data rather than adding 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 names the returned shape (address, unit count, type/subtype, manager), which compensates for the missing return definition. An 11-parameter tool with all-optional filters is covered adequately, though paging/sorting behavior is left entirely 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 every parameter is already documented in the schema with enums, ranges, and formats. The description only restates a subset of filters in prose (and omits orderby, limit/offset, last_updated_from/to), adding no syntax or 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+resource ('List rental properties (buildings)') and even enumerates the fields returned, which distinguishes it from a single-property getter. The '(buildings)' gloss implicitly separates it from rental-unit tools, but no sibling is named outright, so it stops short of the top score.

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, owner or property ids), which implies the browse/filter use case. However, it never states when to prefer this over buildium_get_rental_property or buildium_list_rental_units, nor any 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 that this is a safe read-only operation. The description adds useful context by naming the returned fields and the Buildium endpoint, but it does not disclose behavioral details such as pagination defaults or rate-limit behavior beyond what the schema already 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 tight sentences, with the core purpose front-loaded and the endpoint appended with no wasted wording.

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 list tool with read-only annotations and a fully described schema, the description is largely complete: it identifies the resource, returned fields, filtering, and endpoint. It could do slightly more to distinguish the list operation from its singular sibling, but no critical information for calling it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description's 'Filter by property' is a mild restatement of the property_ids filter, adding no syntax or meaning beyond the structured field.

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 gives a specific verb (List) and resource (rental units), plus a concrete list of returned fields. It does not explicitly differentiate itself from the singular sibling buildium_get_rental_unit or from buildium_list_rental_properties, so it stops just 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?

The only usage hint is 'Filter by property,' which is closer to a parameter note than guidance about when to select this tool. There is no mention of when to use it versus alternatives like buildium_get_rental_unit or buildium_list_rental_properties.

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 description only needs to add extra context. It discloses the underlying endpoint (GET /v1/tasks) but says nothing about result volume, pagination defaults, or permission scoping 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?

One compact sentence front-loads the resource and its subtypes, followed by a short endpoint reference. Efficient, though the Buildium endpoint notation is marginally redundant for an agent that already has 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 17-parameter but zero-required, read-only list tool with a fully documented schema and no output schema, the description covers purpose and scope adequately. It would be stronger if it hinted at default paging behavior, but nothing essential to invoking it is missing.

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

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

Schema description coverage is 100%, so all 17 parameters are already documented with types, bounds and enums. The description's field list (category, property, unit, requester, assignee, status, priority, due date) loosely maps to filterable params but adds no syntax or semantics 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?

Specific verb (List) plus resource (tasks/requests), with an explicit enumeration of the four subtypes it covers (contact, resident, rental owner, to-do) and the fields returned. An agent can distinguish it from buildium_list_work_orders or buildium_list_tenants 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 states what the tool does but gives no guidance on when to choose it over siblings such as buildium_list_work_orders, nor any prerequisite or exclusion. Usage is only implied by 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?

readOnlyHint=true already tells the agent this is a non-destructive read, so the description only needs to add behavioral detail. It does reveal the data categories returned (contact details, emergency contact, address, leases), which is useful given no output schema exists, but it says nothing about pagination behavior, result volume, 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 tight sentences: the first front-loads what is returned, the second front-loads the filter dimensions, and the endpoint is appended last. No filler and no redundancy.

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, zero-required list tool with no output schema, the definition covers the resource, the filter surface, and the returned data categories, and annotations carry the safety profile. It leaves the return envelope (paging, total counts) unstated, which the absent output schema would otherwise have covered.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented in the schema with matching semantics. The description's filter list merely restates a subset of those parameters (omitting limit/offset/orderby and date-range filters) and adds no syntax or interpretation 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+resource ('List rental tenants') and enumerates the returned data (contact details, emergency contact, address, leases), plus the backing endpoint. It is clearly distinguishable from machinelike siblings, though it never explicitly contrasts itself with buildium_get_tenant, the singular counterpart an agent might otherwise pick.

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 filterable fields ('Filter by name, email, phone, unit number, property, owner, unit ids or lease term status') but gives no when-to-use context, no prerequisites, and no alternative-tool routing. An agent still has to infer that this is the bulk/collection counterpart to buildium_get_tenant.

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 the returned field inventory and the underlying Buildium endpoint (GET /v1/vendors), which is useful context, but says nothing about pagination behavior, default ordering, or result caps beyond what the schema documents.

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 tight sentences, front-loaded with the verb and resource, then filters, then endpoint. Nothing is padded, though the trailing API-path sentence is only marginally valuable to an agent that already has the tool contract.

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, zero-required read tool with full schema coverage and a readOnly annotation, the description covers the resource and the returnable fields adequately. It leaves pagination defaults and sort ordering entirely to the schema, which is acceptable but not fully 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%, so the schema already explains every parameter including the enum values and date formats. The description restates a subset of filterable fields (omitting last_updated_from/to, orderby, limit, offset) without adding syntax or semantics 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 vendors') and clarifies scope with synonyms '(contractors, suppliers)' plus the fields returned (contact details, category, insurance, default expense GL account). No sibling in the list covers vendors, so an agent can route here unambiguously.

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 filter dimensions ('name, email, phone, website, status or insurance expiration'), which implies when the tool is useful, but never states when to use it versus alternatives or any exclusions. 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?

The readOnlyHint annotation already declares this as a safe read operation. The description adds useful context beyond that by naming the returned fields (title, status, priority, due date, vendor, amount, line items, linked task and bill ids) and the available filter dimensions, plus the underlying endpoint. It does not mention pagination behavior or rate limits, but with annotations covering safety, this is a strong addition.

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 sentences plus an endpoint reference, front-loading the core purpose before enumerating returned fields and filters. It is efficient with no filler, though the endpoint line is somewhat meta and could be omitted without losing agent-relevant 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?

Given a rich schema with 100% description coverage, readOnly annotations, and no output schema, the description is largely complete: it explains what the tool does, what it returns, and what can be filtered. The main gap is the absence of pagination guidance, though the schema's limit and offset parameters mitigate this.

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 22 parameters are fully documented in the schema itself. The description lists many of the filterable fields, which adds marginal grouping value, but it omits several parameters (orderby, limit, offset, task_ids, task_category_id, unit_agreement_id) and provides no syntax beyond what the schema already gives. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('List work orders') and enumerates returned fields and filter dimensions, making the tool's function clear. However, it does not distinguish itself from siblings like buildium_get_work_order or buildium_list_tasks, so an agent must infer the distinction from the name alone.

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

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

The description lists filter capabilities but provides no explicit guidance on when to use this tool versus alternatives such as get_work_order or list_tasks. It does not state prerequisites, exclusions, or the conditions under which a filtered list is preferable to a single-record fetch.

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, so the description carries most of the burden and it does so well: it discloses that Buildium's PUT replaces the whole record, that the tool therefore reads the task first and merges, and names the actual endpoints (GET then PUT /v1/tasks/todorequests/{toDoTaskId}). It omits permissions/auth requirements and error behavior.

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 action and affected fields, then a single high-value sentence on the read-then-PUT semantics, then the concrete endpoint path. No filler; every sentence earns its place.

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

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

For an 11-param mutation tool with no output schema and only a destructiveHint annotation, the description covers purpose, merge semantics, and endpoint. It is nearly complete, though it does not describe the return payload or failure modes, which an agent might want for a write operation.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining that all fields except todo_task_id are optional and that unspecified fields are preserved by the read-modify-write behavior, which is the key semantic an agent needs when choosing which optional params to send.

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 ('Update a to-do task') and enumerates exactly which fields can be changed (status, priority, assignee, due date, title, category, plus an optional message). This is unambiguous against siblings like 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 description makes clear this operates on an existing task identified by todo_task_id and that only passed fields are modified, which tells the agent how to invoke it. It does not, however, name an alternative or state when not to use it (e.g. vs. create or vs. update_work_order), so it stops short of full routing guidance.

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

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

With only destructiveHint=true from annotations, the description carries real behavioral weight: it discloses the GET-then-PUT patch strategy, that unspecified fields (including entry contacts) are preserved, and that passing line_items destroys/replaces all existing line items. That is exactly the destructive-action warning the annotation hints at but cannot spell out.

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

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

Front-loads the core caveat (PUT is a full replace / this is a patch), then the destructive line_items warning, then the task-routing note, then the API call. No filler sentences.

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 and the annotations are minimal, so the description must cover behavior; it does, including the preservation guarantee and the one destructive field. Nothing an agent needs to call this safely 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 the baseline is 3, but the description adds genuine meaning beyond the schema by explaining that line_items REPLACES the full set and that entry_contact_ids replaces entry contacts, which the schema only labels generically.

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) and immediately clarifies the non-obvious scope: it is a read-then-PUT patch, not a blind overwrite. This distinguishes it from the create/get/list work order siblings.

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

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

Gives clear conditions: pass only fields you want changed, and status/priority/due date must go through the linked task, which implicitly routes the agent to buildium_update_todo_task. It does not name that alternative tool explicitly, so it stops short of a 5.

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