Arthur Online MCP by usefulapi

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

Beyond the annotations it adds real behavioral context: the note is created once, is not a tenant message, and is never retried automatically — this reinforces the idempotentHint=false and tells the agent not to assume retry safety. It does not describe permissions or the response, keeping it shy of a 5.

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

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

Four short sentences, front-loaded with the WRITE marker and the core action, then the HTTP endpoint, then the caveats. Nothing is padding, though the raw endpoint path is of limited use to 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 3-param mutation with no output schema, it covers purpose, confirmation, and non-retry semantics but leaves the tags parameter entirely unexplained. Adequate overall, with one clear gap an agent would hit when deciding how to populate tags.

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

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

Schema description coverage is only 33% — task_id is documented but content and tags are not. The description mentions adding a 'note' (loosely implying content) but says nothing about the tags array or content limits, so it fails to compensate for the coverage gap.

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

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

The description names a specific verb and resource ('add a note to an existing maintenance task') and prefixes it with 'WRITE:' to signal the operation class. No sibling tool touches task notes, so the agent can distinguish it from the get_/list_ family without inspecting schemas.

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

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

It gives a clear triggering condition ('when the user requests it') and a prerequisite ('Confirm the intended task and note first'), which is actionable pre-call guidance. It stops short of naming an alternative tool or stating when not to use it, but no obvious sibling competes for this job.

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 real context beyond the annotations: it explicitly negates side effects ('No files, tenant invitations or financial changes') and warns that the call 'creates once and is never retried automatically', which explains the non-idempotent semantics rather than merely restating idempotentHint=false. It does not describe the response payload or what a duplicate submission would produce, keeping it just below full marks.

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 write semantics and the action, followed by the endpoint and the side-effect boundary. Nothing is repeated from the schema or annotations, and every clause adds 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 mutation with no output schema, the description covers confirmation, side-effect scope, and retry behavior well. However, with 10 parameters at low schema coverage and no return-value hints (no task id returned?), an agent still lacks the field-level guidance needed to construct a complete call.

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

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

Schema description coverage is only 30% across 10 parameters, so the description needed to carry weight here, yet it mentions only 'unit and task details' generically. Undocumented fields such as task_type, emergency, private, tags, api_notes, due_date/due_time, and assigned_managers get no meaning, format, or default guidance from either source.

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

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

States a specific verb and resource ('create a maintenance task associated with a unit') and even names the endpoint shape POST /v2/units/{unit_id}/tasks, which makes the required unit_id immediately obvious. The 'WRITE:' prefix disambiguates it from the read-oriented siblings (get_task, list_tasks) in the surrounding tool set.

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 trigger ('when the user requests it') and a prerequisite step: 'Confirm the intended unit and task details first', which is genuinely actionable pre-call guidance. It stops short of naming an alternative for cases like appending commentary to an existing task (arthur_add_task_note), so the routing guidance is clear but not exhaustive.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to supplement. It does add that certificate records carry type, expiry date and status, which hints at the shape of the result, but says nothing about what happens on a missing/invalid id or whether certificates can be expired-but-returned.

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 fragments with no waste, but neither is a complete sentence and the endpoint notation is developer-facing rather than agent-facing. Brevity here is trimming rather than economy: the same length spent on a verb+resource statement would be far more useful.

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?

The tool is simple (one param, no nesting, no output schema), so the burden is light. The description partly compensates for the missing output schema by naming returned fields, but it never states that it returns exactly one certificate, leaving a small gap.

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

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

Schema coverage is 100% and the single `id` parameter is documented with its origin ('from the corresponding list tool'). The description adds no parameter meaning beyond the schema, which is the baseline expectation at full coverage.

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 fragment 'Property and unit certificates, type, expiry date and status' plus the endpoint 'GET /v2/certificates/{id}' implies a fetch-by-id operation, but there is no explicit verb and no statement that it returns a single certificate record. Sibling names (arthur_get_property, arthur_list_certificates) make the single-record read inferable, so the purpose is recoverable 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?

No guidance on when to call this instead of arthur_list_certificates, and no prerequisite stated beyond the schema note that the id comes from 'the corresponding list tool'. The agent must infer the list-then-get workflow without the description confirming it.

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 the safety profile with 'never pays or changes an invoice', which is meaningful for an invoicing domain where mutation is plausible. It does not cover error behavior for a missing id or pagination-like concerns, so it stops short of full disclosure.

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 front-loaded sentence carries the capability, the boundary, and the endpoint reference. No filler or repetition of the title.

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

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

With no output schema, the description usefully names what comes back (amounts, balances, payment status). It omits what happens when the id does not exist or belong to the caller, a minor gap for a single-parameter read.

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?

The path template GET /v2/invoices/{id} confirms the single id parameter's role, and schema coverage is 100% with a description telling the agent where to source the id. Little more meaning can be layered onto one integer identifier.

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 ('Read contractor invoices') and an enumeration of the fields surfaced (amounts, outstanding balances, payment status). It is distinguishable from arthur_list_invoices only implicitly via the /{id} path, not by an explicit statement contrasting the two.

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 'never pays or changes an invoice' clause clearly bounds when this tool is appropriate (inspection only, not mutation). It lacks an explicit pointer telling the agent to call arthur_list_invoices first to obtain the id, leaving that routing to the schema.

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 value by enumerating what the record contains (address, type, owner, managing agent), which effectively stands in for the absent output schema, but it says nothing about not-found behavior or permissions.

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 fragments, front-loaded with the payload contents; no filler. The style is telegraphic rather than sentence-based, but nothing is wasted.

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

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

For a one-parameter read-only lookup with a fully documented schema, the description supplies the return-field inventory in lieu of an output schema. Only the sibling differentiation and error semantics are missing.

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

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

Schema coverage is 100% and the single id parameter is already documented as 'Arthur numeric record id, from the corresponding list tool.' The description adds nothing beyond that, 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?

The description lists the resource's contents ('addresses, type, owner and managing agent') and cites the endpoint GET /v2/properties/{id}, which implies a single-record fetch. But it never states the verb or says 'retrieve one property by id', and it does not distinguish itself from arthur_list_properties, which sits right next to it in the sibling set.

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

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

There is no statement of when to use this tool versus arthur_list_properties (list vs. single fetch), and no prerequisites such as needing an id from the list tool. The only hint is the URL template.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description doesn't need to establish safety. It does add value by enumerating the returned content (status, descriptions, due dates, assigned managers, tags), which partially substitutes for the missing output schema. It says nothing about not-found behavior, permissions, or what 'maintenance tasks' means structurally.

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 fragments with no filler, and the field enumeration comes first. It is efficient, though the fragment style means the agent has to reconstruct the action verb from the endpoint.

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 with no output schema, the description should at least convey what comes back, and the field list does that loosely. But it omits how the tool relates to arthur_list_tasks (where the id comes from) and says nothing about failure modes, leaving modest gaps for an otherwise simple getter.

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

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

Schema coverage is 100% and the single id parameter is documented in the schema as 'Arthur numeric record id, from the corresponding list tool.' The description adds no syntax, format, or sourcing detail beyond that, 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?

The description is a noun phrase listing the fields a task carries, followed by the REST endpoint 'GET /v2/tasks/{id}', which implies a single-record fetch. The verb 'get' only appears in the title, and nothing explicitly says this retrieves one task by id versus the many-record sibling arthur_list_tasks. An agent can infer the purpose but must do work to confirm it.

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

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

There is no guidance on when to use this tool instead of arthur_list_tasks or arthur_get_workorder. The only hint is the {id} path parameter in the endpoint string, which implicitly signals single-record retrieval. No prerequisites, no exclusions, no alternative named.

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 that this is a safe read, so the description's remaining burden is light. It adds the returned field families (status, dates, unit, rent) and the underlying endpoint, which is modest but real value; it says nothing about error behavior for a missing id.

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 fragments with no filler, and the resource description is front-loaded ahead of the endpoint reference. The telegraphic style leaves it a bit thin but nothing is wasted.

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

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

Absent an output schema, listing the returned field families partially compensates, and readOnlyHint covers safety. However, for a tool sitting beside both arthur_get_tenant and arthur_list_tenancies, the omission of any disambiguation leaves an agent short of what it needs to pick 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?

With 100% schema coverage and a single required 'id' whose schema text already explains it is an Arthur numeric record id from the corresponding list tool, the baseline of 3 applies. The description adds no parameter 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?

A noun phrase enumerating the resource and its fields ('Tenancies, their status, dates, unit and rent details') plus an HTTP endpoint implies a single-record fetch by id, but no verb is stated. It does not differentiate this from the confusingly similar sibling arthur_get_tenant or from arthur_list_tenancies.

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 guidance, no prerequisites, and no reference to alternatives. An agent must infer that this is the by-id counterpart to arthur_list_tenancies and must guess the distinction from arthur_get_tenant on its own.

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 description's job is to add context — and it does, disclosing that invitation codes are redacted from the response and that linked tenancy data is included. Those are meaningful data-shaping details an agent would not otherwise know.

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 clauses with zero filler, and the payload contents are front-loaded ahead of the endpoint reference. The telegraphic phrasing is slightly clipped but costs nothing in comprehension.

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 needs to sketch the return payload, and it does — contact details, linked tenancy, invitation codes stripped. Nothing else is required for a one-parameter read 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?

Only one parameter, and the schema already documents it at 100% coverage including the 'from the corresponding list tool' provenance note. The description adds nothing beyond the path template, 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 resource (tenant contact details plus linked tenancy) retrieved by id, and the endpoint 'GET /v2/tenants/{id}' pins down the operation. It does not explicitly name arthur_list_tenants as the counterpart, so the single-vs-list distinction is only implied by the path parameter.

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 rather than stated: an agent can infer this is the single-record fetch when an id is known, and the schema note 'from the corresponding list tool' hints at the list-then-get flow. There is no explicit when-not or named alternative, so the guidance is minimal.

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 'never posts money' mostly reinforces the safety profile, though it usefully scopes the tool to financial reads only. The description adds that results carry payment status and dates, which is real content context, but says nothing about behavior for missing/invalid ids.

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 tightly packed sentence plus the route: the read-only guarantee is front-loaded and every clause carries content. No filler.

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

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

For a one-parameter read tool with a fully described schema and readOnly annotations, this is nearly sufficient. It could have noted the not-found/error behavior, but nothing an agent needs to call 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% and the single id parameter is fully documented, including its origin from the list tool. The description adds no semantics beyond the endpoint path, 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 (read) and resource (financial transactions and rent charges), and the endpoint GET /v2/transactions/{id} pins it to single-record retrieval. Slight ambiguity remains because the resource is named in the plural, which could be confused with arthur_list_transactions, but the {id} path disambiguates.

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 through the {id} endpoint notation and the schema note that the id comes from 'the corresponding list tool'. It never explicitly names arthur_list_transactions as the way to find an id or states when to prefer this over it.

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

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

readOnlyHint=true already establishes this is a safe read, so the description's job is to add context. It does add value by enumerating the data the record surfaces (vacancy, availability, unit type, market rent, location), which is meaningful for a tool with no output schema. It stops short of noting what happens for a missing/unknown id or how the vacancy/availability fields relate.

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 short with no wasted prose, but it is a noun-phrase fragment rather than a front-loaded statement of action and scope, and the trailing endpoint string mostly restates what the tool is. Terse without being organized for scanning.

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 field enumeration partially covers what the agent gets back, and readOnlyHint covers safety. However, for a record-fetch tool it remains thin: no behavior on invalid ids, no sense of payload size or relationships to get_property/get_tenancy.

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?

Coverage is 100% on the single parameter, and the schema already explains that the id comes from 'the corresponding list tool.' The description contributes nothing beyond that, 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?

The fragment list plus 'GET /v2/units/{id}' implies a single-unit retrieval, but the description never states the verb explicitly — an agent must infer it from the HTTP path. It does not distinguish this from the sibling arthur_list_units, which is the most likely confusion point.

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 whatsoever: nothing says to call this after arthur_list_units to fetch full details, and no alternative (e.g., arthur_list_units for a collection) is named. The agent is left to infer selection rules from the tool name alone.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value by enumerating what comes back (status, title, costs, dates, linked maintenance task), which matters because there is no output schema, but it says nothing about missing-record behavior, auth, or data freshness.

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 plus an endpoint reference, with no filler. It leads with the returned fields rather than the action, which is slightly less front-loaded than ideal for a retrieval tool, but nothing is wasted.

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

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

For a single-parameter read tool with no output schema, the description gives an adequate picture of the returned object. Remaining gaps (error behavior, field formats for costs/dates) are minor for a straightforward getter.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented as an Arthur numeric record id sourced from the corresponding list tool. The description adds no additional meaning about the id beyond what the schema provides, 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?

Names the resource (contractor work orders) and, via 'GET /v2/workorders/{id}', makes clear this fetches a single record by id, which distinguishes it from the sibling arthur_list_workorders. The verb is only implied by the HTTP path rather than stated directly, but the intent is unambiguous.

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 {id} path parameter implicitly signals 'use this when you already have an id, otherwise use arthur_list_workorders', but no explicit when-to-use or prerequisite guidance is given. 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?

Annotations already declare readOnlyHint=true, so the description's real contribution is the pagination behavior: it discloses that the call returns a single page plus vendor pagination metadata rather than the full set. That is genuine operational context an agent needs, though it doesn't describe the shape of the returned items.

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 with no padding, and the resource identification comes first. The style is telegraphic ('Property and unit certificates, type, expiry date and status') rather than fully grammatical, but nothing is wasted.

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

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

With no output schema, the description should say more about what comes back, but it only says 'returns data plus the vendor pagination'. The pagination caveat is valuable, yet the return payload is left undifferentiated beyond the field list, leaving a gap for a list tool with no output 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 four parameters (page, limit, sort, direction) are already documented in the schema, including defaults and the pageCount guidance. The description adds only the general pagination warning and no per-parameter semantics, 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?

The description names the resource (property and unit certificates) and enumerates the fields returned (type, expiry date, status), which lets an agent distinguish it from the sibling arthur_get_certificate without opening the schema. The listing verb itself is only carried by the tool name/title rather than stated in the description text.

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 note that this is 'one page, not the whole portfolio', which hints at iterative paging. There is no explicit statement of when to use this versus arthur_get_certificate or any of the other list_* siblings, 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`; the description adds useful context by stating it never pays or changes an invoice, naming the HTTP endpoint, and warning that results are one page with vendor pagination. It does not cover auth, rate limits, or detailed return shape, so it stops short of a 5.

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

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

Three tight sentences with the read-only constraint and pagination caveat front-loaded. Every sentence contributes distinct information and there is no repetition or filler.

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

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

For a 9-parameter list tool with no output schema, the description covers the key agent-facing facts: read-only behavior, endpoint, returned data categories, and one-page pagination. The schema documents most parameters, though undocumented enum fields like `status` and `submitted` could use brief filter semantics in the description.

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 78%, so most parameters are already documented in the schema. The description mentions payment status and pagination but adds no specific meaning for filters such as `status`, `submitted`, `paid_date`, `workorder_id`, or sorting behavior. Baseline 3 is appropriate given the high coverage.

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 contractor invoices') and names the content fields returned (amounts, outstanding balances, payment status). It also clarifies that this is a page-level list rather than the whole portfolio, though it does not explicitly distinguish itself from the sibling `arthur_get_invoice`.

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 purpose and the pagination note ('this is one page, not the whole portfolio'), but there is no explicit when-to-use guidance or named alternative. It does not say to use `arthur_get_invoice` for a single invoice or explain which filters to prefer.

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. The description adds genuinely non-obvious behavior: results are one page, not the whole portfolio, and pagination metadata comes from the vendor — an agent knows it must loop. It stops short of describing the response envelope 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?

Three short sentences, front-loaded with the returned fields and the key pagination constraint. The opening noun phrase lacks a verb and reads as a fragment, but 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?

With 12 parameters, 50% schema coverage, and no output schema, the description should carry more weight. It correctly warns about pagination, the biggest pitfall, but leaves most filtering parameters and the response structure unexplained.

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

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

Schema coverage is only 50%: page, limit, sort, and direction are documented in the schema, but _q, city, postcode, unit_status, full_address, and property_type carry no explanation anywhere. The description doesn't compensate for a single one of those filters — notably _q, whose search semantics are entirely undefined.

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 the resource and the fields returned (address, type, owner, managing agent) plus the underlying endpoint, which is more informative than the bare name. It never states the verb explicitly and doesn't contrast itself with arthur_get_property, but the resource scope is unambiguous.

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 mention of arthur_get_property as the single-record alternative, and no explanation of which filters to combine. The only usage-relevant statement is the pagination caveat, which is helpful but incidental.

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 value by disclosing that the response includes vendor pagination metadata and represents a single page rather than the full set. It stops short of stating rate limits or default page size behavior, but the pagination caveat is the key non-obvious trait.

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, waste-free sentences. The field inventory comes first, then the endpoint, then the pagination caveat — reasonably front-loaded, though leading with an action verb would have been sharper.

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 13 parameters and no output schema, the description should say more about what is returned and how filters combine. It correctly warns about single-page results, which is the most important gap-filler, but leaves the '_q' free-text parameter and the response shape unexplained.

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 77% and documents page, limit, sort, direction, tags, status, and dates. The description echoes some of those concepts (status, due dates, tags) but adds no syntax or semantics beyond the schema, so the baseline of 3 is appropriate rather than a lower score.

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

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

The description names the resource ('Maintenance tasks') and its fields plus the underlying endpoint GET /v2/tasks, so an agent can infer this is a read/list operation. However, it never states the verb 'list' explicitly and doesn't distinguish itself from arthur_get_task or arthur_list_workorders, so the boundary relies on the tool 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 only usage-relevant hint is 'this is one page, not the whole portfolio', which tells the agent to paginate but not when to pick this tool over arthur_get_task or arthur_list_workorders. There are no exclusions, prerequisites, or conditions for choosing alternatives.

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

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

readOnlyHint=true already declares the safety profile, so the description's burden is lower. It still earns credit for disclosing pagination behavior that annotations do not cover: results come with vendor pagination metadata and represent a single page, which materially changes how an agent should call it. It stops short of noting rate limits, auth, or default page size, keeping it off a 5.

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

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

Three tight sentences with no filler, and the pagination caveat lands early enough to shape the call. The opening fragment is slightly clipped but not wasteful. Every sentence contributes.

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 list tool with no output schema, the description covers the resource and the pagination contract but leaves the entire filter surface and the returned record shape unaddressed. An agent knows what it gets and that it is one page, but not how to narrow results or what fields come back.

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 79%, so the schema carries most parameter meaning and baseline 3 applies. The description adds nothing about the 14 filters — notably _q, status, and full_address, which have no schema description at all and are left entirely unexplained. It does not compensate for the residual coverage gap.

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

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

The description names the resource and enumerates what each record carries (status, dates, unit and rent details), which is more than a restatement of the title. But it opens with a bare noun phrase and never supplies a verb, and it does nothing to separate this from the very similar sibling arthur_list_tenants or arthur_get_tenancy. An agent can infer it lists tenancies, but must reason about the tenancy-vs-tenant distinction unaided.

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 closing clause 'this is one page, not the whole portfolio' gives real guidance on how to consume results and implies you must page through rather than expect a full dump. However, there is no statement of when to choose this over arthur_get_tenancy (single record) or arthur_list_tenants, and no prerequisites or filter-selection guidance. 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 establish readOnlyHint=true, and the description adds valuable behavioral context beyond that: invitation codes are removed from the data, it is a GET endpoint, and pagination returns only one page. It does not cover auth or rate limits, but the key data-shaping and pagination traits are disclosed.

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 three short sentences with no filler. It front-loads the resource, then the endpoint, then the important pagination caveat.

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 tool with no output schema, the description sufficiently explains the returned data, the removed invitation codes, and the page-level behavior. It is not fully complete regarding all ten filter parameters, but the core calling context is present.

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 70%, so the schema carries most parameter documentation, including page, limit, sort, direction, and several ID filters. The description adds only general pagination context ('one page, not the whole portfolio') and does not clarify the undocumented email, mobile, or full_address filter semantics.

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 resource and operation: tenant contact details with linked tenancy via GET /v2/tenants. It clearly distinguishes a list/collection endpoint from a single-tenant fetch, though it does not explicitly name the sibling get_tenant tool as the alternative.

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 description of what the endpoint returns and by the warning that it returns one page rather than the whole portfolio. However, it does not explicitly say when to use this instead of arthur_get_tenant or arthur_list_tenancies.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior by disclosing the pagination envelope and warning that a call returns one page only, not the whole portfolio. That is exactly the operational detail an agent needs before paging, and it does not contradict the read-only 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 compact clauses with the core scope and the read-only guarantee front-loaded. Dense semicolon chaining is efficient but slightly harder to scan than separate sentences; no filler present.

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?

It covers the return shape (data + vendor pagination) and the one-page constraint, which is valuable given there is no output schema. However, for an 11-parameter tool with several opaque enum/string filters and no per-parameter descriptions, the description leaves too much about filtering semantics unaddressed.

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

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

Schema coverage is 73%, which warrants the baseline 3. The description only gestures at the status and date filters ("payment status and dates") and says nothing about the undocumented or opaque parameters such as statement, transaction_type, or the date_from vs transaction_date_from distinction.

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: "Read financial transactions and rent charges, with payment status and dates", plus the endpoint. It is clear this is a list/read tool, though it never explicitly contrasts with the sibling arthur_get_transaction (single record) so the boundary must be inferred from the name.

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

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

Usage is only implied (read transactions) and the one explicit constraint, "never posts money", is a non-capability statement rather than routing guidance. It gives no direction on when to use this versus arthur_get_transaction for a single record or arthur_list_invoices for invoice-level data.

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 genuinely new behavioral context by warning that the response is a single page plus vendor pagination metadata rather than the full portfolio. That is exactly the trap an agent would fall into. It stops short of describing filter matching behavior or the response envelope.

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

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

Two short sentences with no filler, and the highest-value warning about pagination is placed second where it is still prominent. The telegraphic style costs a little readability but wastes no 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?

With 13 optional parameters, no output schema, and only 54% schema coverage, the description leaves real gaps: no return-shape detail, no explanation of filter combination or defaults, and no routing to arthur_get_unit. It does cover the pagination contract, which is the single most important behavioral fact for this 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 coverage is only 54%, so the description must carry weight for the undocumented params (_q, city, postcode, unit_ref, unit_status, unit_vacant, unit_owner_id). The field list ('vacancy, availability, unit type, market rent and location') reads as returned data rather than as filter semantics, so it does not clarify whether these are exact-match filters, and it says nothing about what _q searches.

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

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

The description names the resource ('Units') and enumerates the data it exposes (vacancy, availability, unit type, market rent, location) plus the endpoint 'GET /v2/units'. However, it is written as a noun-phrase fragment with no verb, and it never explicitly distinguishes itself from the singular sibling arthur_get_unit or the other list tools beyond the resource name.

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

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

There is no statement of when to use this listing versus arthur_get_unit for a single unit, nor which filters to apply for which scenario. The only guidance is about paging ('this is one page, not the whole portfolio'), which is useful but covers only one decision.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that results are paginated and this call returns a single page rather than the full set, but it says nothing about how filters combine, whether unknown filters are ignored or error, or how the vendor pagination object is shaped.

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?

Very short and front-loaded with the resource, then the endpoint, then the pagination caveat. The opening noun-phrase fragment ('Contractor work orders, status, title, costs, dates and linked maintenance task') is slightly ambiguous between query inputs and response fields, but nothing is wasted.

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

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

For a 13-parameter tool with no output schema and under half of schema descriptions filled, the description does too little: it never explains the filter parameters an agent must actually choose, nor does it hint at the record shape beyond a comma list. Only the pagination behavior is adequately addressed.

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

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

Schema description coverage is only 46%: page, limit, sort, direction and the two dates are documented, but _q, ref, contractor, emergency, quote_required, status and title are bare. The description's field list (status, title, costs, dates) reads as the shape of returned records rather than an explanation of what those query parameters match, so it does not compensate for the coverage gap.

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

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

The description names the resource (contractor work orders) and enumerates the fields returned (status, title, costs, dates, linked maintenance task), plus the underlying endpoint GET /v2/workorders. The list-vs-get distinction from sibling arthur_get_workorder is only implied by convention, not 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?

There is no explicit guidance on when to use this tool rather than arthur_get_workorder, arthur_list_tasks, or the other list siblings. The only usage-adjacent statement is the pagination caveat ('this is one page, not the whole portfolio'), which is behavior, not selection guidance.

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