erphome.pl

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the description adds: the status vocabulary ('external', 'blocked'), the source=feed name convention, and the default and maximum range constraints. It stops short of describing ordering, timezone, or pagination 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?

The payload is front-loaded (what ranges mean, then what populates them, then defaults and limits) and every clause carries information. It is dense—one long sentence with parentheticals—but not padded.

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

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

An output schema exists so return structure need not be documented, yet the description still explains the status/source semantics an agent needs to interpret results. Defaults and hard limits are covered; only minor gaps like timezone and endpoint inclusivity remain.

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 33% (only apartment_id is documented), so from/to rely on the description. It usefully supplies the default window and the 366-day maximum span for those parameters, but adds nothing on formatting, inclusivity of endpoints, or how the range interacts with apartment_id.

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 specific resource returned (occupied check-in/check-out date ranges) and immediately scopes it: direct reservations, imported iCal nights, and owner-blocked dates. The 'no guest data' qualifier distinguishes it from list_reservations/list_blocks without needing to open 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?

The default window (today through +365 days) and the 366-day range cap imply usage for availability/calendar queries, but no sibling is named and no explicit when-to-use-vs-alternative guidance is given (e.g., versus list_blocks or list_reservations with filters).

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, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds meaningful semantic scope beyond that: it clarifies this returns configuration objects rather than a computed price, which prevents misinterpreting the output. Auth/rate-limit behavior is not addressed, 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?

Two sentences, front-loaded with what the tool returns and immediately followed by the boundary. Every clause earns its place, and there is no filler or repetition of the title.

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

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

With an output schema present, return values need not be explained, and the description covers the key ambiguity (config vs. computed quote) plus the alternative source for base rates. It is essentially complete for a one-parameter read tool; only minor pagination/ordering behavior is unstated.

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

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

Schema description coverage is 100% and the single parameter already documents 'Restrict to one apartment. Must belong to this account.' The description adds no syntax or format detail for apartment_id, so the baseline 3 applies for a schema that does the heavy lifting.

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

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

The description names a specific resource (seasonal overrides, minimum-stay rules, extra fees) and explicitly frames it as 'the pricing configuration, not a computed quote'. It distinguishes itself from sibling content by pointing at list_apartments for the base nightly rate, so an agent can pick it apart from any quote-style 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?

It gives clear context for what this tool yields and explicitly redirects to list_apartments when the agent wants the base nightly rate, which is real routing guidance. It stops short of stating when the tool should not be used at all (e.g. no exclusions around accounts or missing pricing).

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context of its own (no error behavior for missing ids, no permission notes), so it contributes nothing beyond the structured data.

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 zero filler and the key scope ('single', 'by id') front-loaded. It is efficient, though its brevity borders on under-specification rather than maximal usefulness.

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?

An output schema exists, the input schema is fully described, and annotations cover the safety profile, so the agent has what it needs to invoke the tool correctly. The description itself is minimal but the surrounding structured data fills the 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?

Only one parameter exists and the schema already documents it at 100% coverage, including the helpful note that the id comes from list_reservations. The description adds no format or semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (Get) and resource (a single reservation) scoped to one item by id, which is clear and unambiguous. It does not, however, distinguish itself from the sibling list_reservations or explain the singular-vs-list boundary, so it falls short of the 5 tier.

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

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

There is no explicit when-to-use guidance, no mention of list_reservations as the alternative when the id is unknown, and no prerequisites stated. Usage is only weakly implied by the phrase 'by id'.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the safety burden is light. The description adds genuinely new behavioral context: the numbers include only confirmed reservations and are stated to match the panel's Statystyki page, which tells the agent what the figures represent and that they are UI-congruent. It could still note whether results are cached or rate limited.

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

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

Two dense sentences, front-loaded with the metric and granularity, followed by the required-parameter rationale. Every clause carries information; 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?

With an output schema present, return values need no explanation, and the description covers granularity, scope, filtering, and the mandatory-parameter rationale. Only minor details (time basis for 'monthly', any auth context) are absent, which is acceptable for a read-only stat tool.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description goes beyond the schema by explaining why apartment_id is mandatory — occupancy/revenue from apartments with differing nightly rates can't be meaningfully aggregated. That rationale is not present in the schema and materially helps the caller.

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 ('Monthly occupancy and revenue'), the granularity ('monthly'), the scope ('one apartment'), and the filter ('confirmed reservations only'). It is unambiguous what is returned, though it never explicitly contrasts itself with siblings like get_availability or get_pricing.

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: it makes clear apartment_id is required and warns that rates can't be summed across apartments, steering the agent to call it per-apartment. However, there is no explicit 'use this instead of X' routing against the other stats-adjacent siblings such as get_pricing or get_availability.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured context — that this is a prerequisite lookup whose output feeds apartment_id parameters elsewhere — but says nothing about ordering or pagination of the result set.

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

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

Two short sentences, no filler, with the purpose front-loaded and the calling dependency immediately after. 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?

An output schema exists, so return values need not be explained, and the description covers the key integration fact (it supplies apartment_id values). It stops just short of noting anything about result ordering or scale, which is a minor omission for a no-arg list tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the schema is empty and complete for its purpose. The baseline of 4 applies, with no gap the description could have filled.

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

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

States a specific verb and resource (list the account's apartments) and explicitly names the payload of interest (their ids). This clearly separates it from siblings like list_blocks, list_reservations, and list_reviews, which list different resource types.

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 calling rule: 'Call this before any tool that takes apartment_id,' then differentiates the dependents — get_stats requires it, the rest treat it as an optional filter. That is exactly the when/when-not/alternative guidance an agent needs.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful domain context about the nature of the records (owner-created blocks, no guest or price fields), but says nothing about pagination, default scope when apartment_id is omitted, 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 short clauses, zero filler, and the defining scope (what the records are) is front-loaded ahead of the exclusion. Every word 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 an output schema present, return-value documentation is unnecessary, and the annotations cover behavior. The one remaining gap is the default behavior when the optional apartment_id is not supplied (all apartments vs. none), which the agent must infer.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented in the schema ('Restrict to one apartment. Must belong to this account.'), so the baseline is 3. The description adds nothing about apartment_id semantics or what happens when it is omitted.

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 resource ('owner-created blocked date ranges') and gives concrete examples (maintenance, personal use), making the verb 'list' from the title unambiguous. It also distinguishes the resource from reservations, which separates it from the sibling list_reservations, though it does not name that sibling explicitly.

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

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

The negative framing 'Not reservations — no guest, no price' implicitly tells the agent when this tool is the right one (owner blocks vs. guest bookings), but there is no explicit when-to-use statement, no mention of alternatives like get_availability, and no prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description does add real behavioral content — that the result includes automatic mail, not just manual messages — but says nothing about ordering, pagination, or volume, so it clears the lower annotated bar without going far beyond it.

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 core purpose and followed by two clarifying clauses. Nothing is wasted and nothing is 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?

With an output schema present, return values need not be described, and the single required parameter is well documented by the schema. The description correctly adds the one thing schema cannot convey — that automatic mail is included in the thread — leaving only minor gaps around ordering or result size.

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

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

Schema description coverage is 100% for the single parameter, so the schema already explains reservation_id and its origin ('from list_reservations'). The description contributes no additional parameter meaning; 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 resource (message history) scoped to one reservation, and sharpens it with 'everything sent to the guest, automatic mail included' and 'the same thread the panel shows.' An agent can distinguish this from get_reservation, though no sibling is named 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, no conditions, and no named alternative. The closest thing is the identity claim 'the same thread the panel shows,' which describes what it is rather than when an agent should reach for it over get_reservation or list_reservations.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds non-annotation behavior: result ordering (newest first), cursor pagination, and the fact that date filtering is on stay dates rather than creation time. It does not say whether all statuses are returned by default, which is the main remaining behavioral 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?

Two tightly written sentences with the core scope, ordering, and pagination front-loaded, followed by the one filter caveat that most needs emphasis. No filler or restated title content.

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

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

An output schema exists and pagination.next_after is referenced, so return-value explanation is not needed. The description covers ordering, pagination, and the date-filter semantics; the notable omission is whether unfiltered calls return all statuses (including cancelled), which matters for a reservation listing tool.

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

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

Schema description coverage is 83%, so the schema already documents most parameters and the baseline would be 3. The description adds genuine meaning beyond the schema by contrasting the stay-date window against creation-date filtering and tying 'cursor-paginated' to the after/limit pair, though status and apartment_id go unmentioned.

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

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

States a specific verb+resource (list reservations) with scope ('across the account's apartments') plus ordering ('newest first') and pagination style ('cursor-paginated'). It is clearly distinguishable from get_reservation (singular fetch) and list_reservation_messages, though it does not name 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?

The description clarifies the semantics of the from/to window ('filter by stay date ... not by when the reservation was created'), which is a real disambiguation for callers. However, it never states when to prefer this tool over get_reservation, get_stats, or how to handle the default no-filter case, so usage guidance is implied rather than explicit.

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 cover the read-only, idempotent, non-destructive safety profile, so the bar is lower. The description still adds real behavioral context beyond annotations: the default result set includes unapproved reviews, which is a non-obvious filtering behavior an agent must know to interpret results correctly.

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 default-behavior fact is front-loaded and the alternative-mode hint follows, which is the right order for an agent scanning the definition.

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?

An output schema exists, so return values need not be explained. The description covers the key ambiguity (approved vs unapproved) for a 2-parameter tool, though it stays silent on the apartment_id account-ownership constraint that the schema handles instead.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema's terse 'Only published (moderator-approved) reviews' by framing the flag against the published-on-booking-page semantics and stating the default, which is the kind of nuance the schema does not convey.

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 identifies the resource (guest reviews) and clearly describes the scope of what is returned, including the default inclusion of unapproved reviews. It does not restate the verb, but combined with the name list_reviews the agent can tell what it does and how it differs from other list_* siblings.

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

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

It gives concrete guidance for when to set approved_only: use it to match what is actually published on the booking page. It does not state prerequisites (e.g. that apartment_id must belong to this account) or exclusions, but the selecting condition is explicit.

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, idempotent, non-destructive, closed-world. The description adds non-obvious auth behavior ("works with any valid token regardless of scope") and a workflow hint (call first to confirm connection), which is genuine value 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, front-loaded with the core action and followed by the auth/workflow caveat. Every clause earns its place.

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

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

For a no-param identity check with rich annotations and an output schema, the description supplies the connection-confirmation guidance and hints at the returned identity fields. Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. There are no inputs whose semantics the description needs to clarify, and it does not waste words inventing any.

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 ("Identify the account behind this token") that is immediately distinguishable from every sibling (get_stats, list_*, get_reservation). No ambiguity about what the tool does.

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?

Provides clear context: "call it first to confirm the connection and see which account you're talking to." It names the recommended timing (first) but offers no explicit when-not guidance or alternatives — though no sibling could substitute, so the gap is minor.

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