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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the write nature is already covered. The description adds real value by disclosing tenant visibility differences between 'note' and 'message', a trait annotations cannot express. However, it omits the write-approval prerequisite tied to the 'confirm' parameter.

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 action front-loaded and the enum semantics immediately after. 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 write tool with no output schema and low schema coverage, the definition covers the visibility model but omits the 'confirm' approval requirement for writes and any indication of what is returned. 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 only 25%, so the schema under-documents three of four params. The description compensates by explaining the 'kind' enum meanings, which the schema leaves bare, but says nothing about 'confirm' or 'communicationId' beyond their names.

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

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

States a specific verb+resource ("add a message to a maintenance report/conversation") and clarifies the two message kinds. An agent can distinguish it from update_communication or list_communications, though the boundary with update_communication is never made explicit.

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 kind semantics imply when to use 'note' vs 'message', but there is no guidance on when to call this tool versus update_communication, get_communication, or create_maintenance_report. 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=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral rule — the property defaults to being owned by the first applicant unless ownerApplicantId is supplied — which the annotations cannot convey. It does not mention failure modes or the confirm requirement, keeping it 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 short sentences, zero filler, front-loaded with the core action and then the two details an agent actually needs (field naming and ownership default). Nothing repeats structured data unnecessarily.

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 tool with no output schema, the description covers the action, the tricky nested parameter, and the ownership default. It omits the confirm/write-approval expectation (present only in the schema) and any duplicate-address or validation behavior, but the essentials for a correct call are 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 only 29%, so the description must compensate, and it does so for the most ambiguous parameter: `fields` is explained as using Lendlord field names with a concrete example and a pointer to list_property_fields, and ownerApplicantId's effect is described. Remaining gaps (city, postcode, address) are self-evident strings, so this is close to sufficient.

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 property") that is immediately distinguishable from siblings update_property and delete_property. It does not explicitly name those alternatives, but the create/update/delete split is self-evident from the verb.

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: the cross-reference to list_property_fields tells the agent where to get valid field names, and the ownerApplicantId note implies a multi-applicant context. There is no explicit when-to-use/when-not guidance relative to update_property or the confirm-gated write flow.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered, but the description adds nothing beyond that. For a write tool with no output schema it never explains the session-approval/confirm behavior, what happens on duplicate tenants, or that a payment schedule may be generated as a side effect.

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?

Purpose is front-loaded in the first sentence and the dense field list is kept to one clause rather than padded with prose. Slightly hard to scan given the run-on enumeration, but every token 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?

Given a nested free-form object and no output schema, the description covers the highest-risk surface (the `fields` payload) thoroughly. The remaining gap is the write-confirmation workflow, which is at least documented in the schema's `confirm` parameter.

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 25%, and the riskiest parameter is `fields`, a free-form object with additionalProperties and no per-key documentation in the schema. The description compensates well by enumerating the accepted keys and the full enumeration sets for rentReviewFrequency, generatePaymentScheduleFor, depositScheme and the Yes/No flags, plus the date format.

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+scope ('Add a tenant to a property'), which is unambiguous against siblings like add_property or update_tenant. It does not explicitly name an alternative, but the name and opening sentence alone are enough to route correctly.

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 at all: nothing about when to prefer add_tenant over update_tenant, nothing about prerequisites (an existing propertyId), and no mention that this is a write that may require the confirm flag. The agent must infer usage entirely from the name.

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

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

Annotations only declare the generic profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds the non-obvious behavior that a transaction holds exactly one attachment and re-attaching overwrites it, plus the accepted file-type set and the server-side location constraint for filePath. This is meaningful behavior beyond the structured fields, and nothing here contradicts the 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?

Five dense sentences, front-loaded with purpose and sibling disambiguation, then replacement semantics, then source-parameter rules, then a discovery pointer. No filler or repetition.

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

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

With 7 parameters, no output schema and low schema coverage, the description covers sourcing, replacement behavior, accepted formats and target discovery well. It omits what the response returns and says nothing about mimeType, a minor gap for a write tool of this complexity.

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 14%, so the description carries most of the burden: it clarifies that filePath is on the server's machine, that url and base64 are alternate sources, that base64 must pair with fileName, and that exactly one source must be supplied. mimeType and transactionId are left implicit, so it falls just short of full compensation.

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 ('Attach an invoice, receipt or other file to a bank/manual transaction') and names the sibling it is not ('use this instead of upload_document, which only links files to properties and tenants'). An agent can distinguish it from upload_document, link_document and remove_transaction_receipt 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?

Explicit routing: use this rather than upload_document, and it names list_transactions (with search/amount/hasReceipt hints) as the way to locate the target. It also states the replacement condition ('a transaction holds ONE attachment: attaching again replaces it') and the exactly-one-of source rule, so both when-to-use and how-to-call are covered.

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

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

The annotations already declare a read-only, open-world operation. The description adds useful behavioral context: it covers both upcoming and overdue items across the entire portfolio and specifies soonest-first ordering. It does not state permissions or result-shape limitations, but the annotation coverage lowers the burden.

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 definition is a single front-loaded sentence with no wasted words. The parenthetical category examples and sort order are immediately useful and do not distract from the core purpose.

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 overview tool with no output schema, the description sufficiently states what is returned: expiry items across compliance categories, sorted soonest first. It does not specify returned fields such as property identifiers or exact dates, but the core return content is clear enough to call the tool correctly.

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

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

Schema description coverage is 100%, so the single withinDays parameter is already fully documented in the schema. The description adds no extra parameter meaning beyond what the schema provides, which meets the baseline for fully covered schemas.

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 exact resource and scope: upcoming and overdue expiry dates across the portfolio, with concrete compliance categories and sort order. It does not explicitly differentiate from any sibling tool, but the sibling list contains no obvious competing compliance overview tool.

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 compliance and expiry context, but the description gives no explicit when-to-use or when-not-to-use guidance, and it does not name any alternative sibling tool.

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 this as a non-read-only, non-destructive open-world write. The description adds a genuine behavioral fact beyond them: the report is not shared with tenants unless shareWithTenants is true, which affects who sees the record. It stops short of describing the confirm/approval requirement or any permission model.

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 purpose is front-loaded, but roughly 250 characters are spent duplicating 34 enum values that already live in the input schema. That block does not earn its place and buries the one genuinely useful sentence about tenant sharing at the end.

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

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

For a 7-parameter mutation with no output schema and 43% schema description coverage, the definition covers the type taxonomy and sharing semantics but omits the confirm/approval flow, required-vs-optional framing for the 4 undocumented parameters, and any failure or permission context.

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 43% (below 50%), so the description must compensate. It does add real value for shareWithTenants (whose schema entry has only a default, no description) and implies propertyId. But its dominant content is a verbatim re-listing of the maintenanceType enum, which is already fully defined in the schema and therefore adds no meaning.

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: 'Log a maintenance issue on a property.' An agent can distinguish it from create_task or add_property by the resource. It does not, however, name or contrast any sibling explicitly.

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

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

There is no when-to-use guidance at all. With create_task, update_property, and add_communication_message among siblings, the agent gets no help deciding whether a maintenance issue belongs here or in a generic task tool, and no prerequisites (e.g. property must exist) are stated.

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

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

Annotations declare a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety profile is partly covered. However, the description omits the confirm-gating workflow required by the schema and says nothing about permissions, session approval, or side effects, which is a meaningful gap for a mutation tool.

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

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

A single efficient sentence with no filler, front-loading the core action and its two distinguishing attributes. It is appropriately short, though the brevity contributes to the missing guidance elsewhere.

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

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

For a 5-parameter mutation tool with 20% schema coverage, no output schema, and a required write-confirmation flow, the description is inadequate. It should explain the confirm requirement and clarify the subject/description fields to let an agent invoke the tool correctly.

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

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

Schema description coverage is only 20% (only 'confirm' is documented in the schema), so the description must carry the load. It explains dueDate and propertyId implicitly, but leaves subject, description, and the critical confirm flag unexplained, leaving three of five parameters semantically unclear.

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+resource ('Add a custom task') and states two key attributes (due date required, optional property link). It clearly distinguishes the create operation from siblings like update_task and list_tasks, though it does not explicitly reference them.

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

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

The description gives no guidance on when to use this tool versus update_task or create_maintenance_report, and it omits a crucial precondition: the 'confirm' parameter must be set true once the user approves writes. No alternative routing or exclusions are 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds value by emphasizing 'Permanently' (irreversibility) and offering the non-destructive archiving path, though it doesn't discuss auth or recovery.

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 sentence, front-loaded with the destructive action and immediately followed by the safer alternative in a parenthetical. Zero waste.

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 destructive single-entity delete with annotations covering the safety profile and no output schema, the description conveys irreversibility and the alternative path. It omits the confirm-gate context, which the schema partially carries, so it's near-complete rather than exhaustive.

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

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

Schema coverage is 50%: confirm is documented in the schema, communicationId is not. The description's 'maintenance report/conversation' wording clarifies what the id refers to, partially compensating, but adds no format or constraint detail. Baseline 3 is appropriate.

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

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

Specific verb (delete) + resource (maintenance report/conversation), with 'Permanently' clarifying the operation's nature. It also names the sibling alternative update_communication, so the agent can distinguish it from other communication tools without opening 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?

Explicitly routes the agent to update_communication with archived:true when history should be kept, which is a genuine when-to-use alternative. It stops short of stating prerequisites (e.g. that confirm must be true) or exclusions, so it's clear context rather than a full decision rule.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: removal detaches the document from a specific property/tenant and only destroys it when no other link exists. It still omits irreversibility and the session-confirmation gate, which lives only 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?

A single sentence with the decisive detail (conditional deletion) placed inline rather than padded out. No filler or redundant restatement 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?

For a destructive mutation with no output schema, the description covers the core semantics but leaves open whether the action is reversible, what happens to a document with multiple links, and that a confirm value is needed. Adequate but with visible 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 coverage is 50%: entityId and confirm are documented in the schema, but documentId and entityType carry no schema description. The description's reference to 'the property/tenant it is linked to' adds context for the entity parameters, but it does nothing to clarify documentId or the entityType default.

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

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

States a specific verb (Remove) and resource (document), and adds the meaningful nuance that removal only becomes a true delete when the link was the document's only one. It implicitly separates itself from link_document and delete_property/delete_tenant, though it never names a sibling explicitly.

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

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

There is no guidance on when to use this versus link_document (to unlink) or the other delete_* tools, and no mention that a `confirm` flag is required before the write is accepted. The agent must infer timing and prerequisites entirely from 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered by structured data. The word 'Permanently' usefully signals irreversibility, which is additive, but the description omits the confirm-approval gating and any cascade/side-effect disclosure that matter for a destructive tool.

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

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

A single front-loaded sentence with no filler, and the destructive nature is stated immediately. It is arguably too terse for a destructive operation, 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 destructive, irreversible tool with no output schema and half its parameters undocumented, the description should explain the confirm gate and any consequences of deletion. Given the annotations, safety is partly covered, but the operational context an agent needs before invoking this 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 only 50% (propertyId is undocumented), and the description mentions neither parameter. It does not compensate for the gap by explaining the identifier's format or the confirm-approval workflow.

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 ('delete') and resource ('property') with a scope qualifier ('from the portfolio'), which distinguishes it from delete_document, delete_tenant, and delete_communication by resource. It does not explicitly name or contrast a sibling, but the resource 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?

No when-to-use or when-not-to-use guidance, no prerequisites, and no alternative (e.g., update_property for modifying rather than removing). An agent gets no routing help beyond the resource name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so safety is covered by structured data. The description reinforces irreversibility with 'Permanently', which is useful, but it omits what a delete cascades to, whether the confirm flag is mandatory, and whether the operation is recoverable.

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 single front-loaded sentence contains no filler, but for a destructive two-parameter tool it is under-specified rather than genuinely concise. It reads as terse rather than optimized.

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

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

No output schema exists and the description does not mention the required `confirm` approval flag, cascade effects, or failure modes. For a high-stakes destructive operation with an undocumented required parameter, this leaves real gaps an agent could trip on.

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

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

Schema description coverage is 50%: `confirm` is documented in the schema, but `tenantId` has no description anywhere. The description says nothing about either parameter, so it fails to compensate for the coverage gap; only the presence of `confirm` in the schema prevents a 1.

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 (delete) plus resource (tenant) and adds the crucial qualifier 'permanently', so an agent knows exactly what operation this performs relative to add_tenant/update_tenant. It does not name or distinguish itself from any sibling explicitly, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no prerequisites, and names no alternative (e.g., update_tenant for reversible changes). 'Permanently' hints at irreversibility but there is no explicit condition or exclusion for selecting this tool.

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 this is a non-destructive write (readOnlyHint=false, destructiveHint=false), and the description adds real behavioral value beyond them: attachments are materialized as separate documents with a specific naming pattern '<date> - <subject> - <file>'. That side-effect disclosure is exactly the kind of thing annotations cannot convey. It stops short of stating permission/approval requirements or failure 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?

Three tight sentences: action and target first, then the input-mode alternative, then the attachment side effect. No filler and nothing buried.

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

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

For a mutation tool with 11 parameters and no output schema, the description covers the essential call-shape decisions (entity target, input mode, attachment handling), while the schema covers confirm and entityType. Missing context on required approval/session state and what happens on partial failure keeps it below full marks.

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 27% across 11 parameters, so the description has to carry weight — and it does: it establishes the mutually exclusive input modes (raw emlBase64 vs. discrete subject/from/to/date/text/html fields), which the schema does not express, plus the attachment naming rule. It leaves entityType, entityId, confirm, and the attachment object shape unaddressed, keeping it short of a 5.

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

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

The description gives a specific verb and resource ('Store an email (and its attachments) as documents on a property or tenant'), which is clearly distinguishable from generic siblings like upload_document. However, it never differentiates itself from the close siblings add_communication_message, update_communication, or upload_document, which an agent will likely weigh against 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 when-to-use/when-not-to-use guidance and no mention of alternatives, even though the sibling list contains several plausible substitutes (upload_document, add_communication_message). The only conditional guidance given ('Pass either emlBase64 ... or subject/from/to...') is about parameter form, not tool selection.

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 this a read-only, open-world call, so the safety profile is covered. The description adds the meaningful behavioral detail that results are ranked against free text rather than exact-matched, but says nothing about result shape, behavior on zero matches, or how scoring/truncation works.

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, no filler; the input surface is front-loaded and the workflow hint is placed last as an action cue. 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?

No output schema exists, so the description is the only guide, and it adequately conveys input types and intent for a 2-parameter read tool. A brief note on what a ranked result contains (or what an empty result means) would make it 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 0%, so the description carries the burden and does it well for 'text', enumerating concrete input classes (email subject/body, address, postcode, tenant name/email, policy or certificate number). 'limit' is left undocumented, though its default and bounds are visible 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 ('Rank properties') plus the free-text inputs it accepts, which cleanly separates it from list_properties and get_property. An agent can tell this is a fuzzy-relevance lookup rather than an enumeration or exact fetch.

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?

Explicitly says 'Use before file_email to pick the property,' anchoring the tool in a concrete workflow and naming the downstream sibling. It does not state when to skip it (e.g. when an exact property id is already known), so it falls just short of full when/when-not coverage.

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 openWorldHint=true, so the safety profile is covered. The description adds useful scope disclosure (what is and is not returned), but says nothing about auth requirements, whether the payload is cached or live, or how plan-limit values are represented.

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

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

A single sentence, front-loaded with the resource name, packing the return scope and the sibling exclusion with no 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?

With no output schema, the description must carry the burden of describing what comes back, and it does so by enumerating the five content areas. It stops short of describing the shape or nesting of those areas, but for a parameterless read of a bounded object this is close to 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly avoids inventing parameter semantics and instead spends its words on scope, which is the only meaningful input question here (implicitly, no filtering arguments exist).

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 (the Lendlord account) and enumerates exactly what it covers: user, team role, currency/country settings, applicants, and plan usage limits. It also differentiates from siblings by explicitly excluding property data and pointing to list_properties, so an agent can place it 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 gives one routing rule — property data lives elsewhere, use list_properties — but offers no positive guidance on when account data is the right call versus tools like compliance_overview or get_profit_and_loss, which are also account-scoped aggregates.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the bar is lower. The description adds one useful behavioral detail — that messages are embedded in the result — but says nothing about permissions, empty/missing results, or the openWorldHint=true implication.

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

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

A single short sentence with no filler and the core resource front-loaded. It is efficient, though arguably too terse to be fully 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?

With no output schema, 0% schema coverage, and 2 parameters including an enum discriminator, the description should explain the id and the type choice. It leaves both undocumented, so an agent lacks what it needs to call this correctly in ambiguous cases.

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 0%, so the description must compensate, yet it never mentions communicationId or the type discriminator. The phrase 'maintenance report or conversation' loosely echoes the type enum but gives no guidance on which value to pass or what the default means.

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 retrieval target ('One maintenance report or conversation') and clarifies the payload includes its messages, which distinguishes it from list_communications by implying a single item. It does not explicitly name the sibling it contrasts with, so it falls 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?

There is no guidance on when to use this versus list_communications or get_tenant, nor any precondition such as needing a valid communicationId. The agent must infer the single-vs-list distinction purely from the word 'One'.

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 and openWorldHint=true already declare that this is a safe, potentially external-facing read. The description adds that the payload includes a monthly per-property breakdown and a category list, which is genuinely useful return-shape information, but says nothing about time range, defaults, or aggregation 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?

A single front-loaded sentence with no filler. It is efficient, though slightly telegraphic — "with the category list used for transactions" is a compressed clause that could read more clearly.

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 input schema, no output schema, and only safety annotations, the description is the sole source of behavioral detail. It covers what is returned but omits the reporting period, whether all properties are included, and the structure of the response, leaving real gaps for an agent.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric this is the baseline 4. Schema coverage is also 100%.

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: retrieves P&L figures per property, broken down by month, plus the transaction category list. It is clear what the tool returns, though it doesn't explicitly differentiate itself from siblings like get_rent_collection or list_transactions that also touch financial 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?

There is no statement of when to use this tool versus the other financial/data siblings, and no indication of prerequisites or scope (e.g. all properties, current period). The agent must infer usage from the purpose sentence alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description uniquely adds that the response bundles every stored field plus related tenants and documents — useful breadth context — but says nothing about pagination, size limits, or what happens if the property does not exist.

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

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

A single front-loaded sentence that states the return scope with zero filler. Nothing is padded or repeated.

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

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

No output schema exists, but the description compensates by enumerating what the response contains (all fields, tenants, linked documents). Missing only edge-case behavior and pagination notes, which is a minor gap for a read-only 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 description coverage is 100% and the sole parameter documents itself as 'Property id from list_properties'. The description adds no parameter-level 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?

The description is a noun phrase rather than an explicit verb, but 'Every stored field for one property' plus tenants and linked documents makes the resource and scope unambiguous. It distinguishes this aggregate fetch from siblings like list_properties or list_property_fields, though it never names those alternatives.

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

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

There is no when-to-use guidance and no mention of alternative tools such as find_property, list_properties, or list_property_fields. The agent must infer that this is the single-record detail lookup from the description alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context about the returned data shape (per tenant, due dates, matched transactions), but discloses nothing about auth, limits, or pagination.

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

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

A single, well-formed sentence with the scope (between two dates) placed at the end. No filler, though it is quite terse.

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

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

For a simple two-parameter read tool this is close to adequate, and no output schema exists so return-value description isn't strictly required. However, it leaves the date format and range semantics undocumented in both schema and 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 0%, so the description must carry the parameter burden. It only implies that 'from' and 'to' bound a date range and never explains the expected ISO date format or whether the range is inclusive.

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

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

States a clear verb (get) and resource (rent collection) and specifies the returned content: expected rent payments per tenant with due dates and matched transactions. No sibling overlaps this concept, so no explicit differentiation is needed.

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

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

The description gives no indication of when to use this tool versus alternatives such as get_profit_and_loss or list_transactions, nor any prerequisites or conditions. Usage is only inferable from the phrase 'between two dates'.

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 and openWorldHint, so safety is covered. The description adds genuine scope context by noting the response bundles linked documents, which the annotations do not convey; it says nothing about pagination, auth, or volume of linked 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?

A single front-loaded sentence that states resource and output scope with no filler. A fragment rather than a full sentence, but every word carries information.

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

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

With no output schema, the description does double duty and partially delivers by sketching the return shape (fields + linked documents). It remains vague about what 'linked documents' contains and what happens when the tenant is absent.

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

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

Schema description coverage is 0% and the description only implies that the single tenantId selects one tenant. It adds no format, source, or validity detail for the identifier, so it does not compensate for the missing schema documentation.

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 (one tenant) and its output scope — all stored fields plus linked documents — which distinguishes it from list_tenants and get_property. The retrieval verb is implied rather than stated, but the resource and result shape are 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 statement of when to use this rather than list_tenants (plural) or get_property for related data, and no prerequisites. The only implicit signal is 'one tenant', which implies a single-entity lookup.

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 openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses that a receipt, if present, exposes its name and a temporary download link, which is useful for the agent to anticipate.

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 no waste; the core purpose is front-loaded and the receipt detail follows as a secondary note.

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

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

With no output schema, the description carries the return-value burden. It notes the transaction comes with 'all its fields' and describes the receipt sub-field, which is reasonably complete, though 'all its fields' is vague and leaves the exact return shape undefined.

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 there is a single required transactionId already documented in the schema. The description adds no further meaning about the parameter, 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 description clearly states it returns a single bank/manual transaction with all its fields, and the receipt handling is specific. The implicit verb (get) and the singular 'One ... transaction' distinguish it from list_transactions, though it does not explicitly name siblings like update_transaction or attach_transaction_receipt.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The schema hints that the id comes 'from list_transactions,' but the description itself offers nothing about when to reach for this tool versus list_transactions or the update/receipt siblings.

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 value beyond the annotations: encryption is handled automatically, GET is read-only while other methods mutate data, and non-GET calls require write confirmation. This usefully refines the coarse destructiveHint=true into a per-method rule. It does not cover rate limits, error shapes, or how raw responses are returned, keeping it out of the top band.

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. The capability, the fallback trigger, and the safety rule are all front-loaded in that order, which matches how an agent decides whether to call it.

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 open-world passthrough with no output schema and 40% parameter coverage, the description supplies the essentials: what it reaches, that encryption is automatic, and that writes need confirmation. The remaining gap is that it outsources the endpoint list to docs/api.md and says nothing about failure behavior.

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

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

Schema coverage is only 40% across five parameters. The description clarifies method semantics (GET vs. others) and ties into the confirm parameter via 'write confirmation', but it never explains the required /api/ path pattern, the query map, or the body format beyond 'encryption handled'. Partial compensation for a genuine 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?

States a specific verb and resource ('Call any Lendlord /api endpoint directly') and frames itself as the fallback for features lacking a dedicated tool, which distinguishes it from the long list of purpose-built siblings. An agent can immediately tell this is the escape hatch rather than a domain operation.

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 clear condition for use ('features without a dedicated tool') and points to docs/api.md for the endpoint catalogue. It stops short of naming which siblings to prefer first, and defers endpoint discovery to an external file, so it is clear context but not fully self-contained 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?

Adds real value beyond annotations: discloses that Lendlord creates a separate copy with its own id under the original name — a non-obvious side effect. Annotations only cover readOnly/destructive/openWorld. However, it doesn't mention the confirm-gated write approval requirement from the schema or any auth/permission expectations.

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

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

Two sentences, front-loaded with the action and target, then the key side effect. 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?

Covers purpose, targets, and the important copy-on-link behavior. Missing the confirm-gated write requirement (which the schema hints at but the description ignores) and any permission/error context, but as a non-destructive, no-output-schema operation it is nearly 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 coverage is only 25%, so most parameters (documentId, entityId, entityType) are undocumented in the schema. The description clarifies entityType options by implication ('property or tenant') but doesn't explain documentId/entityId meaning or the confirm flag's role. Partial compensation only.

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 (attach) + resource (existing document) + target (property or tenant). Distinguishes from siblings like upload_document (new file), send_document (delivery), and rename/delete_document (other lifecycle ops).

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

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

Implies usage by describing the attach operation, but doesn't state when to use this vs upload_document or send_document, nor that the document must already exist in the account. No exclusions or prerequisites called out.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds non-obvious behavior the schema does not: upstream paging happens in 100-item pages, the effective ceiling is 1000, and the response carries hasMore/nextSkip continuation state. That is real behavioral disclosure (no output schema exists), though error/rate-limit behavior is unstated.

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

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

Two sentences, no filler. The first front-loads what the tool returns and in what order; the second carries the pagination mechanics. Every clause conveys actionable 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 must cover return behavior, and it does supply the paging model and continuation fields that an agent needs to loop correctly. It is slightly incomplete in that the shape of individual communication records and the hasMore/nextSkip field names' location (top-level vs nested) are not spelled out, 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 coverage is 50% (type and propertyId documented, skip and limit not). The description compensates well: it defines limit's ceiling ('max 1000'), explains how skip is derived from the response ('skip = nextSkip'), and its example of maintenance reports clarifies the intended type value. Only propertyId filtering is left entirely to the schema.

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

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

States a specific verb (list) and resource (communications), and goes further by defining what counts as a communication: 'Maintenance reports and other tenant/landlord communications', plus the sort order (newest first). It does not name the related single-item or mutation siblings (get_communication, log_communication, update_communication), so differentiation is inferred from the noun rather than stated.

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

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

The description gives concrete continuation instructions ('continue with skip = nextSkip while hasMore is true'), which tells the agent how to iterate but not when to choose this tool over get_communication, list_documents, or log_communication. No explicit when-to-use vs when-not context is provided beyond the resource scope.

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 openWorldHint=true, so the safety profile is covered. The description adds useful context that results pair documents with their linked entities, but says nothing about pagination, result limits, or whether unlinked documents are included — gaps that matter given there is no output schema.

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

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

Two short sentences with zero filler; the resource and its linkage are front-loaded and the optional filters follow. Nothing could be cut without losing 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 two-parameter, zero-required list tool with no output schema, the description conveys the entity scope and the link-inclusive result shape, which is most of what an agent needs. Remaining gaps around result volume and pagination keep it from a 5.

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

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

Schema description coverage is 100%, so both filters are already fully documented in the schema. The description restates them ('linked entity id or name text') without adding format, matching behavior, or multi-value semantics, 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 clear verb-implied resource ('Documents stored in Lendlord') and adds scope (linked entities, optional filters). It implicitly separates itself from the write-side siblings (upload_document, rename_document, delete_document, send_document) by being a read/list tool, but it never names an alternative outright.

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

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

There is no explicit when-to-use or when-not-to-use guidance; the closest thing is the filter sentence, which is really parameter documentation. An agent gets no signal about how this differs from other read tools such as get_property or list_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 and openWorldHint=true, so the safety profile is covered. The description adds that results include key figures, but says nothing about pagination, result limits, or auth, so it adds only modest context beyond the 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 core listing behavior front-loaded and the filter noted second. No filler, though the parenthetical field list could be trimmed since it mirrors the return data.

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

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

With no output schema, the description does list the fields returned, which helps. But it omits pagination/result-size behavior and never mentions the status filter, so an agent is left guessing about result scope.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the search behavior ('matched against address/postcode') but adds nothing for the status parameter, so the baseline 3 applies.

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

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

States a clear verb (list) and resource (properties) and even enumerates the returned key figures (address, postcode, value, rent, mortgage). It reads as a portfolio-wide listing, but it does not differentiate itself from siblings like find_property or get_property, which an agent must otherwise infer.

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

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

The description implies usage via 'Optionally filter by free text matched against address/postcode,' giving the agent a sense of when to use the search parameter. However, it gives no explicit when-to-use versus find_property/get_property, and never mentions the status filter or any exclusion.

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 as a safe read, so the bar is lower. The description usefully adds that the payload is reference data (valid field names and slot keys) rather than records, but says nothing about ordering, pagination, or whether the set is static or account-dependent.

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 sentence, no filler, and it front-loads the most important fact — that this returns accepted field names — before the consumer tools. Nothing could be cut without losing 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 must convey what comes back, and it does: field names plus document slot keys, mapped to the tools that consume them. Minor gap in not describing the shape (e.g., a flat list of strings) or whether add_property and update_property share the same set.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The sentence instead spends its budget explaining the meaning of the returned values, which is the right trade-off.

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 precisely — the field names accepted by add_property/update_property and the document slot keys for upload_document — so an agent knows exactly what it returns. It is clear, though it does not explicitly name a sibling it is distinct from; the distinction is inferable only because no other sibling is a field/slot reference tool.

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?

By tying the output to add_property, update_property, and upload_document, it effectively signals when to call it: before composing those calls. It gives clear context but states no exclusions or prerequisites (e.g., whether the lists differ per account).

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 openWorldHint=true, so the safety profile is covered. The description usefully adds that results default to active items and that the payload mixes two entity types (tasks and alerts), which is real context beyond the annotations, but it says nothing about pagination, ordering, or result volume.

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 entity types front-loaded and the (important) default stated last. No filler, though it is terse enough that a bit more structure around parameters would have been worth the 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 zero-required-parameter read-only list tool with no output schema, the description covers what is returned and the default scope, which is most of what an agent needs. It omits return shape and result ordering, but annotations cover safety and the tool is simple enough that this 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 0%, so the description has to carry parameter meaning. It explains the 'active' default and gives concrete examples of task and alert categories, which helps disambiguate the category enum, but it never addresses the status values completed/deleted/all or clarifies how category=all interacts with the default status.

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 the resource clearly (tasks, including custom and Lendlord-generated ones like MISSING_DUE_DATES, plus alerts like Payment Overdue), which lets an agent distinguish it from mutation siblings such as create_task and update_task. It stops short of explicitly naming an alternative list tool or stating its scope relative to siblings, so it lands at clear-but-undifferentiated.

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

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

There is no explicit when-to-use or when-not-to-use guidance. 'Defaults to active ones' hints at the default filtering behavior but doesn't tell the agent when to reach for this tool versus, say, filtering elsewhere. Usage is only implied.

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 and openWorldHint, so the safety profile is covered. The description adds genuine non-annotation context: each tenant maps to exactly one property, and propertyMissing signals a link to a deleted property, which helps an agent interpret results. It omits return shape and pagination, keeping it from 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 clauses, front-loaded with resource and scope before the data-model nuance and the fix path. Every sentence carries information, though the data-model clause is dense and slightly crowds out usage guidance.

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-optional-parameter list tool with no output schema and read-only annotations, the description covers scope, the filter, the property linkage, and the propertyMissing anomaly. It stops short of describing the returned list shape, but nothing essential for a correct call 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 0%, so the description must carry the meaning of the sole parameter, and 'optionally for one property' clearly explains that propertyId scopes the listing. Format details are absent, but the semantic role of the parameter is well conveyed.

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 the resource (tenants) and its scope (actual and prospect) plus the optional per-property filter, so an agent knows this returns a tenant collection rather than a single record like get_tenant. It never states the verb 'list' outright, leaning on the name/title for that, so it falls just short of a self-contained 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?

It implies the propertyId filter is optional and routes link-fixing to update_tenant { propertyDetailsId }, which is useful. However it gives no explicit when-to-use guidance relative to siblings like get_tenant or list_properties, leaving the core selection decision to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds real context beyond that — transactions may be bank-imported or manual, and a transaction's `file` is its attached receipt — but says nothing about result limits, ordering, or pagination for what is potentially a long list.

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 date-range scope front-loaded and no filler. The second sentence about the `file`/receipt relationship earns its place because there is no output schema to explain that field.

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 partially compensates by explaining the `file` field and the receipt linkage, and it covers the required date range. However, it leaves 37% of parameters undocumented and does not sketch the returned transaction shape (fields, ordering, volume), so an agent still lacks a full picture of what comes 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 coverage is 63%, above the low-coverage threshold, so the schema carries most of the parameter meaning. The description only alludes generically to 'optional filters' and the date range, and does not clarify the semantics of amount (exact vs range), search scope, status values, or propertyId beyond what the schema already says.

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 the resource precisely (bank/manual transactions) and the core scoping mechanism (a required two-date range plus optional filters). It implicitly separates itself from get_transaction and update_transaction by being the list operation, though it never names those siblings directly.

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 retrieval scenario — use the optional filters 'to find the one you want (e.g. the payment an invoice belongs to)' — which tells the agent this is the lookup tool for locating a specific transaction. It also routes to attach_transaction_receipt for the receipt case, but offers no explicit when-not or exclusion guidance.

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

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

Annotations only say this is a non-destructive write; the description supplies the non-obvious implementation behavior an agent cannot infer: the record is really a back-dated maintenance report, defaults to type 'Other', is created closed, and is deliberately not shared with tenants. It also names the read paths (list_communications/get_communication) where the record surfaces with the original date.

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 what it does, then the storage mechanism, then the read path and the file_email companion. Dense and mostly waste-free, though the '(issue #3)' tracker reference and the long parenthetical add noise an agent does not need.

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 10 parameters, so the description has to cover the write's side effects and visibility, which it does (not shared with tenants, appears in list_communications with the original date). Minor gaps remain around the confirm/approval flow and tenant linking, which are only gestured at in the schema.

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

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

With only 40% schema description coverage across 10 parameters, the description carries real load and does explain the mapping semantics (date, counterparties and summary get embedded into the report description; maintenanceType defaults to 'Other'; status is closed). However it says nothing about confirm, tenantIds, propertyId, subject or channel, so the documentation gap is only partly closed. Minimum-viable, not compensating fully.

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 precise verb+resource ('Record a past email thread, call or letter against a property') and immediately distinguishes itself from the surrounding communication tools by explaining that Lendlord has no generic communication log. An agent can tell this apart from add_communication_message, create_maintenance_report and file_email without opening a schema.

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

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

Gives an explicit companion recommendation ('Use file_email as well to keep the full message and attachments'), which tells the agent this tool is not a substitute for document filing. It stops short of stating when NOT to use it (e.g. vs. add_communication_message for live tenant threads), so it is clear context without full exclusions.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is already known. The description usefully adds that the transaction itself is unchanged, but does not mention permissions, the confirm-flag workflow, or what happens if no receipt exists. It does not contradict 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 short sentences, front-loaded with the action and scope-clarifying second sentence. 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 mutation tool it covers the core action and scope, but omits the confirm-approval semantics that are essential to correct invocation, plus failure behavior. Ancillary detail is minor since there is no output schema and few params.

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 50%: transactionId has no description and confirm does ('Set true once the user has approved writes for this session'). The description adds no parameter detail, so it neither helps nor compensates – baseline 3 for moderate 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 (Remove) and resource (the file/receipt attached to a transaction), and the second sentence clarifies scope: only the file is removed, not the transaction. This clearly distinguishes it from delete_document, attach_transaction_receipt, and update_transaction.

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 name and purpose, but there is no explicit when-to-use guidance or reference to the sibling attach_transaction_receipt. The confirm parameter hints at a write-approval workflow, but the description never explains 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 establish readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that – it does not disclose the confirm-based write approval requirement, reversibility, or whether existing names are overwritten. For a mutation tool it is thin.

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

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

A single front-loaded clause with zero waste, but at six words it reads as under-specification rather than disciplined conciseness given the tool's mutation semantics.

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

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

A write tool with no output schema and a confirm-gated flow needs more than one clause. Nothing tells the agent that writes require session approval, what happens on failure, or what the call returns, so an agent cannot call it confidently without inferring from the schema alone.

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%: `confirm` is documented but `documentId` and `name` are bare strings. The phrase 'display name' does add a little meaning to `name` (contrasting with a filename), but there is no format hint for `documentId` and no elaboration on confirm 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 (change/rename) and resource (a document's display name), which cleanly separates it from siblings like upload_document, delete_document, link_document and send_document. It is clear what the tool does, though it makes no explicit sibling comparison.

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

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

No guidance on when to use this versus other document-mutating siblings, and no mention of prerequisites. Critically, nothing in the description hints that a write-approval flow (the `confirm` flag) gates this operation.

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=false, openWorldHint=true, and destructiveHint=false. The description adds meaningful context beyond that: a real email is sent with the document attached, and replies route to the account email unless replyTo is provided. It still omits the session approval/confirm requirement mentioned 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?

Three short sentences, front-loaded with the action and followed by the reply-routing detail and the real-email warning. There is no filler, and every sentence adds usable 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 7-parameter write tool with no output schema and very low schema description coverage, the description covers the core send behavior and reply routing but is incomplete. The confirm flag and several optional parameters remain unexplained, which is a meaningful gap for safe invocation.

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 14%, and the description compensates for just a few parameters: it implies documentId and to, and explicitly explains replyTo. It does not explain cc, message, subject, or the confirm flag, leaving critical call parameters undocumented for a 7-parameter write tool.

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 ('Email') and resource ('a stored document') and adds recipient and attachment behavior. It is clear, but it does not distinguish this from sibling tools such as file_email or list_documents.

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 warning 'This sends a real email' gives useful context that this is an externally visible action, and it conditions reply behavior on replyTo. However, it gives no explicit when-to-use guidance, prerequisites, or alternatives to sibling tools.

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 destructiveHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing behavioral beyond that: it never mentions the 'confirm' approval gate, permission requirements, reversibility, or partial-update semantics for a multi-field mutation.

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

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

A single front-loaded sentence listing the mutable fields with no filler. Efficient, though the inline parenthetical enum is slightly compressed versus a structured field list.

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 8-parameter mutation tool with 13% schema coverage and no output schema, the description covers the editable field set but is silent on the required identifier, the confirm gate, and the result of the write. Adequate as a minimum-viable definition 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 only 13% (just 'confirm'), so the description must compensate; it enumerates six of the eight fields and gives the status enum values inline. However it omits the required communicationId and the maintenanceType enum values, and gives no format hints for summary/description, so compensation is partial.

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 (Change) and resource (maintenance report/conversation) plus the mutable fields, so the agent knows exactly what this does. It does not differentiate itself from the sibling update_task, delete_communication, or get_communication, leaving the agent to infer scope from the field list 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?

No when-to-use guidance, no prerequisites, and no mention of the sibling delete_communication/get_communication alternatives. An agent must guess from the field list whether this is the right tool for a given editing request.

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=false and destructiveHint=false, so the write/safety profile is carried structurally. The description does add real value beyond that: partial-update semantics, null-clears-a-field behavior, and field-specific rejection of invalid values. It still says nothing about the confirm/authorization requirement or that changes are not undoable, which for a mutating tool is a notable gap.

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 action and partial-update rule, then layers the value-format rules in compact parenthetical examples. Dense but every clause carries usable information; the only cost is that the format rules run together without visual grouping, which makes it slightly harder to scan.

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 tool with a nested free-form fields object and no output schema, the description covers input semantics thoroughly enough to call it correctly. It does not mention what is returned or confirm that a read-back/get_property is the way to verify the write, but that omission is minor since no output schema exists.

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% (just confirm), so the description must compensate, and it largely does: field-name sourcing, date formats (YYYY-MM-DD and DD/MM/YYYY), money formats ('150000', '£150,000', '150k'), area units with sq ft conversion, and the fraction convention for percentages including the '1 or less is already a fraction' rule. Only the confirm parameter's session-approval flow is left to the schema.

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

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

States a specific verb (change) and resource (fields on a property) and immediately pins down the scope with partial-update semantics: 'Only the fields you pass change; set a field to null to clear it.' That scope statement cleanly separates it from add_property and delete_property without needing to name them.

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 operating context and routes the agent to a sibling for field discovery ('Field names from list_property_fields'), which is genuinely helpful. However it never states when to prefer this over add_property/delete_property or any preconditions for the confirm gate beyond what the schema says, so it falls short of explicit when/when-not guidance.

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

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

Annotations already declare readOnly=false, openWorld=true and destructive=false; the description adds value beyond them by explaining that removal is by key, that replace is performed as an add-plus-remove combination, and where keys originate. It does not discuss reversibility of removals or note that writes require the confirm flag, leaving a minor tension with destructiveHint=false for an operation that drops images.

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 sentences, front-loaded with the supported operations, then the sibling differentiation, then the parameter guidance. Every sentence contributes and there is 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?

There is no output schema, so the description needn't explain return values, and it covers the core operations and key semantics well. It is slightly short of complete for a write tool with low schema coverage because it omits the confirm requirement and the file-object 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 low (25%), so the description carries extra burden. It adds real meaning for files (image files) and removeImageKeys (keys sourced from get_property.fields.images), but says nothing about propertyId, the confirm parameter, or the url/base64/fileName shape of file objects, so it only partially compensates for the 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 states a specific resource (a property's Photos gallery) and three concrete operations (add, remove by key, replace via add+remove). It also names the sibling it is not (upload_document) and where image keys come from (get_property under fields.images), so an agent can distinguish it without opening 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 explicitly routes the agent between this tool and upload_document based on destination (Photos vs Documents) and tells the caller what to provide (one or more files and/or removeImageKeys). The when-to-use-vs-alternative condition is stated outright rather than inferred.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write nature is known. The description adds the genuinely useful semantic that status='active' means reopen and that 'deleted' is reachable through this single tool, which the enum list alone does not explain. However, there is tension with destructiveHint=false that is never resolved (soft-delete vs. real deletion), and no note about reversibility or the confirm prerequisite.

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

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

A single well-formed sentence with the action and the status values front-loaded and no filler. Its brevity is appropriate in form, though it borders on under-specification for a six-parameter mutation tool.

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

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

For a write tool with six parameters, 17% schema coverage and no output schema, the description is too thin. It never says which fields are editable, that deletion is permanent or recoverable, or that `confirm` is required when writing.

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

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

Schema description coverage is only 17% (just `confirm`), so the description must compensate. It does clarify the meaning of the one enum valueset (completed / active=reopen / deleted), which is real added meaning, but leaves taskId, dueDate, subject, description and the confirm flag entirely unexplained.

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 (edit/change) on a specific resource (task), and enumerates the status transitions including the 'active (reopen)' semantics. It is distinguishable from create_task and list_tasks, though it does not name those siblings to differentiate scope explicitly.

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

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

No guidance on when to use this tool versus alternatives, and no exclusions. Critically, it does not mention the `confirm` gate that the schema says must be set before writes are approved, so an agent gets no workflow guidance beyond the bare action.

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 declare readOnlyHint=false and destructiveHint=false; the description adds the important nuance that only passed fields mutate and that passing null clears a field, which is behavior an agent could not infer from the schema. It still omits permission/auth requirements and the meaning of the confirm gate, so it is not fully transparent.

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

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

Three short, front-loaded sentences with no filler; the partial-update rule and the relocation payload are both actionable. The parenthetical cross-reference to add_tenant is slightly compressed but 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?

No output schema, nested objects, and a free-form fields map, so the description carries real weight. It covers mutation semantics and the one non-obvious operation (moving properties), leaving only the confirm gate and return/response behavior unaddressed.

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

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

Schema description coverage is only 33%, so the description must compensate. It does explain 'fields' thoroughly (partial semantics, null clearing, and the propertyDetailsId move idiom), but says nothing about tenantId or confirm, and the free-form field vocabulary is only externalised by reference to add_tenant. Partial compensation warrants a baseline-plus 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?

States a specific verb and resource ('Change fields on a tenant') and extends scope to relocation ('Move a tenant to another property'). It points at sibling add_tenant for the field vocabulary, which helps an agent separate the two, though it does not fully state the relationship (add vs. mutate) outright.

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 usage semantics: partial update, null clears, and the exact payload for relocating a tenant to another property. It does not state when not to use it (e.g. vs. delete_tenant/add_tenant for other operations), so it stops short of full when/when-not guidance.

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

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

Annotations already declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful context beyond that: only supplied fields are modified (safe partial update) and the existing receipt is preserved rather than replaced, which reassures the agent about mutation side effects.

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 action and immediately followed by the two behavioral constraints that matter most. 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?

For a 4-parameter mutation with no output schema, the description covers the key behavioral unknowns (partial update, receipt retention). The approval gate is left to the schema field description, which is adequate; nothing essential is missing.

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

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

Schema description coverage is 100%, so every parameter including the confirm approval gate and the empty-string unlink convention is already documented in the schema. The description paraphrases the link/unlink behavior but adds no syntax or format detail the schema lacks; 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 ('Change') and resource ('the property or category linked to a bank/manual transaction'), naming exactly which fields are mutable. The scope qualifier 'bank/manual transaction' plus the receipt sentence distinguishes it from siblings like attach_transaction_receipt and remove_transaction_receipt.

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 clearly implies when to use it ('Only the fields you pass change' = patch-style edits) and explicitly rules out a neighboring use case ('this does not upload or remove a receipt'), routing the agent to the receipt siblings. It does not, however, name an alternative tool or state prerequisites such as the approval/confirm requirement.

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

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

Annotations only cover read/write and open-world hints; the description adds meaningful behavior beyond them, including quota consumption and the fact that unrecognized keys silently create custom documents. It also flags that filePath reads from the server's machine, a security-relevant detail. It omits any mention of the write-confirmation flow implied by the confirm parameter.

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 dense sentences with no filler, and the alternative-tool routing is front-loaded right after the core action. Slightly information-heavy but every sentence carries operational value.

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

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

With no output schema and only 2 required parameters, the description supplies the sourcing constraints, slot semantics, and quota behavior an agent needs. The remaining gap is the confirm/approval workflow, which is left entirely to the schema field.

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 40%, but the description compensates well: it specifies the exactly-one-of constraint among filePath, url, and base64+fileName, and explains the key slot semantics via list_property_fields with concrete examples and custom-key fallback. It does not clarify confirm, entityType, or mimeType, leaving some 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?

States a specific verb (Upload) and resource (a file/document) with its linking target (property or tenant). It also explicitly distinguishes itself from the sibling attach_transaction_receipt, so an agent can route correctly without opening either 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?

Names an explicit alternative (attach_transaction_receipt) and the condition that selects it (attaching to a bank transaction/payment). It gives clear positive context but does not address other plausible siblings like link_document or send_document, so routing guidance is good but not exhaustive.

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