Aryeo MCP by usefulapi

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds value beyond them by spelling out the external third-party side effect (a notice emailed/messaged to the order's customer) and the fee/slot consequences. It does not address what happens on a repeat cancel of an already-cancelled appointment, which matters given idempotentHint=false.

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, then the notify decision, then the risk, then the endpoint. 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 destructive two-parameter mutation with full schema coverage and no output schema, the description covers purpose, both notify branches and the risk profile. Remaining gaps (auth/permission requirements, behavior on an already-cancelled appointment) are minor but real.

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 both parameters are already documented in the schema, including 'Required: decide explicitly' for notify. The description restates the notify outcome and adds only the third-party framing, so baseline 3 applies.

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

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

States a specific verb and resource in caps ('CANCEL an appointment') and pins the underlying operation ('PUT /appointments/{id}/cancel'). It is not explicitly differentiated from the sibling aryeo_reschedule_appointment, so an agent must infer that one moves the booking and the other kills 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?

Gives real decision context: the notify flag's meaning and the consequences of cancelling (possible fees, slot released). It does not state when to prefer an alternative such as aryeo_reschedule_appointment when the customer wants a different time rather than no booking.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying PUT endpoint and clarifies the 'now vs. given time' behavior, but it never explains what 'destructive' means here (state transition, irreversibility, repeat-call error behavior), which idempotentHint=false would make valuable.

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

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

Two short fragments, front-loaded with the action and the key behavioral nuance (immediate vs. specified time). No wasted words; could arguably use one more clause on side effects rather than trimming further.

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 mutation, the schema and annotations together cover most needs, but with no output schema the description should say what a successful completion returns or what happens on an already-completed task (relevant given idempotentHint=false). It leaves that gap unaddressed.

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

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

Schema coverage is 100%: both task_id (UUID pattern) and completed_at (ISO 8601 with timezone and default) are fully documented in the schema. The description's parenthetical restates the default-now behavior already present in the schema, so it adds no new semantics.

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

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

States a specific verb+resource ("Mark a task completed") and narrows scope with the optional completion time, which clearly separates it from siblings like aryeo_create_task, aryeo_get_task, and aryeo_list_tasks. It doesn't explicitly name those siblings, but the action is unambiguous.

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

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

The description implies usage by naming the operation but gives no when-to-use guidance, no preconditions (e.g. task must not already be completed), and no mention of alternatives or how this relates to similar state-changing siblings. An agent must infer everything about 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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is known. The description adds real value beyond that by disclosing the external side effect ('Aryeo may email the new customer an invitation') and the underlying endpoint, which an agent cannot infer from 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?

Three short sentences: purpose and required inputs first, dedupe guidance second, side effect third, endpoint last. No filler and every sentence 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 create tool with full schema coverage and annotations covering mutability, the description covers what is needed to invoke it correctly, including the duplicate-check workflow. The one gap is that it says nothing about what comes back (e.g., a new customer ID), which matters for follow-up calls when 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 100%, so every one of the 10 parameters is already documented in the schema. The description only reaffirms the three required fields (owner name, email) and adds nothing about optional fields like timezone, phone, or team_name. 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?

Names a specific verb and resource ('Create a customer') and even defines the domain object ('an agent or brokerage that can place orders'), plus the minimum inputs. This is clearly distinguishable from siblings like aryeo_list_customers or aryeo_update_order_notes.

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 precondition and names the alternative: 'Look the email up with aryeo_list_customers first to avoid duplicates.' That is actionable routing guidance, though it does not state when not to use this tool or what to do if a duplicate is found.

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 disclose that this is a non-read-only, non-idempotent, open-world, non-destructive operation, so the description does not need to restate the safety profile. It adds the POST endpoint and optional-field context, but does not cover side effects such as invalid assignee handling, permissions, or what happens on duplicate submission. With annotations covering the core behavioral traits, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It identifies the action, optional fields, and endpoint efficiently. The structure is appropriate for a simple create 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 low-complexity create tool with a fully described schema and annotations covering mutation behavior, the description is largely complete. It does not explain return values, but no output schema exists, and the omission is minor. An agent has enough context to 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 100%, so the schema already documents all four parameters, including formats and constraints. The description mentions optional description, due date, and assignee fields, but adds little beyond what the schema provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Create a task.' It also enumerates the optional attributes that can be supplied, making the tool's purpose immediately clear. However, it does not explicitly distinguish this from sibling tools such as aryeo_complete_task or aryeo_update_order_notes, 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 says what can be created but gives no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must infer that this is the tool for creating a new task rather than completing, listing, or retrieving 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description still adds value by naming the concrete data returned (status, start/end, duration, assigned users and items) and the backing endpoint. It says nothing about error behavior (e.g. invalid/unknown id) or whether unexpanded relations are omitted.

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 fragments, return content front-loaded before the endpoint reference. No filler sentences and nothing repeated from the schema or annotations.

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, and the description compensates by summarizing the returned fields for the single-resource read. With annotations carrying the safety profile and the schema fully documenting both parameters, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the 'include' property already documents allowed relation values and unknown-value behavior, so the schema does the heavy lifting. The description adds no meaning beyond the schema for either appointment_id or include; baseline 3 applies.

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

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

Specific verb (get) plus resource (appointment) and singular scope ('One appointment by id'), with an explicit field list and the underlying endpoint GET /appointments/{id}. This implicitly separates it from aryeo_list_appointments, though the sibling is never named.

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

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

Usage is only implied: fetch a single appointment when you have its id. There is no explicit statement of when to prefer this over aryeo_list_appointments, and no guidance on when expansion via 'include' is worthwhile versus a plain fetch.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description adds real context beyond that: the field inventory returned and the fact that media/visit data is gated behind include. It omits auth requirements, but for a read-only lookup that is a minor 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?

Three short sentences, front-loaded with what the tool returns before the include hint and the endpoint. The telegraphic phrasing ('Add include=... for media and visits') trades a little readability for density but wastes no words.

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

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

With only two parameters at full schema coverage and no output schema, the main missing piece an agent would want is the return shape — and the description supplies a field inventory that compensates. Only the when-to-use-vs-siblings question remains unanswered.

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

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

Schema coverage is 100% and the include property already documents the allowed relations and the unknown-value fallback. The description's include examples (images, videos, orders.appointments) largely duplicate that, so it sits at the baseline rather than adding syntax or selection guidance.

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 ('One listing by id') and enumerates what comes back (address, status, price, lot/building details, agents). The singular-vs-plural contrast with aryeo_list_listings is implicit rather than stated, so it stops short of full sibling differentiation.

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

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

Gives concrete guidance on when to pass include ('Add include=images,videos,orders.appointments for media and visits'), but never says when to use this versus aryeo_list_listings or aryeo_get_listing_stats. Usage is implied by the parameter, not by the tool choice.

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 a safe, read-only, open-world GET. The description adds the endpoint path and the metric categories returned, which is useful, but says nothing about whether stats are date-bounded, aggregated, or empty for listings without a site.

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 tight sentence that front-loads what the tool returns, followed by the endpoint reference. No filler, though the endpoint restatement is somewhat redundant with the tool name.

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

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

There is no output schema, so the description carries the burden of describing return values — it names visits and views but not the response shape, granularity, or time window. For a simple single-param read tool with annotations covering safety, this is adequate but leaves a real 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?

Only one parameter and schema coverage is 100%, so the schema fully documents listing_id including its UUID pattern. The description hints at the id via '{id}' in the endpoint but adds no semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource — viewing statistics of a listing's property website — and adds the concrete metrics (visits, views) plus the underlying endpoint. It is distinguishable from aryeo_get_listing, though that sibling is never 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?

Usage is only implied: it's clear you call this to get website stats for one listing, but there is no statement of when to prefer it over aryeo_get_listing or aryeo_list_listings, no prerequisites, and no 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing what the response contains and that the include parameter expands into line items and visits. It stops short of describing failure behavior for bad ids or the shape of the returned payload.

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

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

Two compact sentences with zero waste: return contents first, expansion hint second, endpoint last. Everything is front-loaded and each clause carries information.

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

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

With no output schema, the description usefully compensates by listing the fields returned and the endpoint. That is enough for an agent to call it confidently; only minor gaps remain around response shape per included relation.

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

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

Schema coverage is 100% and the order_id UUID format plus the allowed include relations are already fully documented in the schema. The description restates the most common include values but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('One order by id') and enumerates the returned fields (customer, address, status, totals, payment and invoice links), plus the underlying endpoint GET /orders/{id}. The phrase 'One order by id' implicitly distinguishes it from aryeo_list_orders, so an agent can choose 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?

Gives clear operational guidance: fetch a single order by id, and add include=items,appointments,listing,customer when line items and visits are needed. It does not explicitly name aryeo_list_orders as the alternative for searching or state when-not to use this tool, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond restating the endpoint path — no note on behavior for a missing/unknown id, no indication of whether the response is a single object or wrapped envelope.

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

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

Two short fragments, front-loaded with the resource, zero waste. It is arguably over-terse rather than verbose, so it does not suffer from padding, but the second fragment is mostly a restatement of the first.

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

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

For a single-parameter read with full schema coverage and a complete safety annotation set, the minimum needed to call it is present. However, with no output schema, the description gives no sense of what a task record contains or what happens on a not-found id, leaving modest 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 100% and the single parameter carries a UUID pattern and description, so the schema fully documents task_id. The description's 'by id' merely confirms the key without adding format or lookup semantics beyond the schema, making the baseline 3 appropriate.

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

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

States a specific resource (one task) and the retrieval key (by id), plus the underlying endpoint GET /tasks/{id}. It is clearly distinguishable from aryeo_list_tasks and aryeo_create_task, though the verb is implied 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?

Usage is only implied by the singular 'one task by id' versus the sibling list tool. There is no explicit when-to-use/when-not guidance, and nothing tells the agent what to do if the id is unknown or whether to prefer list_tasks for discovery.

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, non-destructive, open-world profile. The description adds real value beyond them: default status scope (SCHEDULED only), default sort order, and the include-expansion trick for seeing location and assignees. It does not discuss pagination behavior or result limits beyond what the schema states.

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

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

Two dense sentences plus the endpoint, with the defaults front-loaded before the filter list. Efficient, though the sentence packing several filters plus the include hint is slightly heavy and the trailing 'GET /appointments' is near-redundant for an agent.

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

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

There is no output schema, so the description's note on defaults and ordering compensates partly, and the schema itself is fully documented for pagination and expansion. Return field shape is not described, but for a filtered list endpoint with rich schema 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 coverage is 100%, so a 3 is the baseline, but the description adds meaning on top: it gives a concrete include value example ('order,order.address,users to see where and who') and reinforces the SCHEDULED default for statuses. It doesn't explicate tense/start_after semantics 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 a specific verb and resource ('List appointments (shoots/visits)'), clarifies terminology, and declares defaults (SCHEDULED, newest start first). It does not explicitly contrast with sibling aryeo_get_appointment, but the list-vs-single distinction is clear 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?

Enumerates the available filter dimensions (upcoming/past, status, time window, assigned users), which implies when to use it. It never says when NOT to use it or names alternatives like aryeo_get_appointment for a single record or aryeo_list_available_timeslots for scheduling.

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, open-world read, so the description doesn't need to carry the safety profile. It adds the useful detail that results are day-level availability rather than concrete slots, but says nothing about pagination behavior when using timeframe (noted only in the schema) 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?

A single front-loaded sentence that opens with what is returned and follows with the required input combinations, with no filler. The trailing 'GET /scheduling/available-dates' is marginal value for an agent that already has the endpoint, but costs little.

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

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

With 12 parameters and no output schema, the description covers the two principal calling patterns but omits the optional filters (user_ids, order_id, order_item_ids) and pagination semantics, which the schema and its per-field notes must supply. Adequate for a correct call, but not fully self-contained.

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 already 100%, so the baseline would be 3, but the description adds genuine cross-parameter logic the schema leaves implicit: a date range or timeframe, plus either appointment_id or duration + interval. That conditional pairing is the main thing an agent could get wrong, and it is stated explicitly.

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 ('Days that still have availability') and ties it to the scheduling endpoint, which is clearly distinguishable from sibling tools like aryeo_list_available_timeslots. It doesn't explicitly name that nearest sibling, so the day-vs-timeslot distinction must be inferred from the word 'Days'.

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 frames the use case ('for a proposed or existing appointment'), which implicitly tells the agent when this applies, and the parameter combos hint at the two workflows. However, it never states when to use aryeo_list_available_timeslots instead, nor any prerequisites beyond timezone being required by the schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /scheduling/available-timeslots) and the input-mode constraint, but says nothing about result volume, pagination behavior, or that availability depends on external calendar state.

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

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

Three short sentences, front-loaded with the one-day scope before the parameter modes, ending with the endpoint. 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 10-parameter read tool with annotations present and no output schema, the description covers scope, mode selection, and optional filters adequately. Minor gap: it never characterizes what comes back from a paginated availability call, though the page/per_page schema fields partially fill that in.

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 would be 3; the description goes beyond it by synthesizing the cross-parameter rule (appointment_id OR duration+interval) that the schema only states piecemeal in individual field descriptions. It does not add format or unit detail beyond what the schema provides.

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

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

States a specific verb and resource (bookable timeslots) plus hard scope: exactly ONE day, in a given timezone, for a proposed or existing appointment. The emphasized 'ONE day' implicitly separates it from the sibling aryeo_list_available_dates, so an agent can route correctly 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?

Explicitly names the two mutually exclusive invocation modes: 'Give either appointment_id, or duration + interval (minutes)', and notes user restriction and order tie-in are optional. No exclusions or named alternatives beyond that, which keeps it at 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered without the description. The description adds value by exposing the underlying endpoint (GET /coupons) and listing the payload fields, but says nothing about pagination, default page size, or result limits — which matters for a list 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?

Two compact fragments with zero padding and the resource stated first. The parenthetical is slightly ambiguous about whether those are returned fields or filters, but overall it is efficiently front-loaded.

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

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

With no output schema, the field enumeration (name, discount, active state, redemptions) usefully previews the response shape, and all parameters are covered by the schema. Only a note on pagination/filtering behavior would make it fully complete.

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

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

Schema description coverage is 100%, so all five parameters (page, sort, search, include, per_page) are fully documented in the schema itself. The description's parenthetical describes output fields rather than parameters, so it adds no parameter-level meaning beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('List discount coupons') and even enumerates the fields returned, so an agent knows exactly what this returns. The coupon resource is clearly distinct from sibling list tools (orders, products, customers), 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 guidance on when to select this tool versus other list endpoints, and no mention of filtering behavior (search, include) that would help an agent decide it is the right call. Usage is only inferable from the name and resource.

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 destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path (GET /customers) and the shape of returned data at a high level; it says nothing about pagination defaults, result limits, or whether balances are computed live.

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-load the operation, entity definition, and filterable fields. The trailing 'GET /customers' is marginal but aids cross-referencing with API docs.

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 ten optional parameters and no output schema, the description leaves gaps an agent must close from the schema alone: pagination flow (use next_page), default sort (-created_at), the `include` expansion, and the max page size. Adequate but not complete for a paged list 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 100%, so all ten parameters, including `include`, `sort`, `per_page`, and `customer_team_ids`, are already documented with formats and defaults. The description only echoes five of the filter fields, adding no format or precedence detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List your customers') and even defines the domain entity in parentheses (agents, brokerages, teams who order from you), plus what fields come back (contact details, balances). It doesn't explicitly contrast with aryeo_create_customer, but the list/create distinction 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?

The enumeration of filter fields implies how to narrow results, but there is no explicit when-to-use guidance, no statement of when to prefer `search` over `name`/`email`, and no mention of how to page through results or when to use this versus listing orders. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint ('GET /listings') and which fields come back, but says nothing about pagination behavior, result caps, or ordering; the schema carries the next_page/per_page mechanics instead.

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

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

Two tight sentences: the first defines the resource and payload, the second enumerates filters, and the endpoint is appended. No filler and the core purpose leads.

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

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

With 18 optional params, no output schema, and no annotations gaps, the description does the important extra work of listing returned fields in lieu of an output schema. It falls slightly short by not covering the 'include' expansion option or pagination flow, though the schema documents both.

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

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

Schema description coverage is 100%, so the baseline is 3. The description groups the main filter families (text, address, agent, status, price/size, delivery status), which reinforces intent, but it omits the non-obvious 'include' relation-expansion parameter and the bedrooms/bathrooms range filters.

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 ('property listings of your Aryeo company'), then enumerates the fields returned (address, status, price, bedrooms, delivery status, thumbnails). This clearly separates it from the single-record sibling aryeo_get_listing.

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

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

The filter list ('search text, address, listing agent, status, price/size ranges or delivery status') implies this is the browse/search entry point, but there is no explicit when-not guidance or named alternative such as aryeo_get_listing for a single record or aryeo_get_listing_stats for 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /order-forms) and the shape of the returned fields, which is mild but real added context. It says nothing about result volume, default ordering, or whether all forms or only active ones are returned.

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

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

Two short sentences, front-loaded with the purpose and followed by the returned fields; nothing is padded. The trailing 'GET /order-forms' is marginally redundant but cheap and aids API traceability.

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, and pagination is fully specified in the schema, so an agent can call this correctly. It would be stronger if it noted whether results are filtered by status or tenant, but nothing essential is missing for a simple read-only list.

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 both parameters (page, per_page) carry precise descriptions including defaults and the next_page continuation hint, so the schema fully carries this dimension. The description adds no parameter meaning of its own, making the baseline 3 correct.

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

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

States a specific verb ('List') and resource ('order forms'), and the parenthetical 'the public booking forms customers use' defines the resource for agents unfamiliar with Aryeo terminology. It also names the returned fields (title, URL, scheduling settings), so the agent knows what it gets. It does not explicitly distinguish itself from siblings like aryeo_list_orders or aryeo_list_products, which is the only thing keeping it below 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 call this versus the many other list_* siblings, and no preconditions stated. Usage is only implied by the resource name, which is thin given 23 siblings competing for 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 establish readOnlyHint, destructiveHint=false, and openWorldHint, so safety is covered. The description adds one genuinely useful behavioral fact — results default to newest-first — plus a note on what each order carries (statuses, totals, links), but says nothing about pagination limits or result caps. Modest, correct addition beyond 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?

Two dense, well front-loaded sentences: what it lists and default ordering first, then filterable dimensions. The trailing "GET /orders" is arguably filler, but the rest earns its space.

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

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

With 12 optional params but a fully described schema and no output schema, the description fills the important gap by naming the fields each order returns (payment status, fulfillment status, totals, links) and the default ordering. Pagination behavior is left to the schema, which is acceptable given its coverage.

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

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

Schema description coverage is 100%, so every one of the 12 parameters is already documented in the schema, including enums and UUID formats. The description only summarizes the filter surface at a high level and omits several parameters (page, per_page, sort, include, creator_group_id), so it adds no semantics the schema lacks. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("List the orders of your Aryeo company") and scopes the result set to the caller's company, which distinguishes it from aryeo_get_order and from the other list_* siblings. A reader knows immediately this is a paged, filterable order collection.

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

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

The filter sentence makes the intended use cases concrete: browse newest-first, or narrow by search text, statuses, appointment window, tags, or assigned users. It never names an explicit alternative (e.g. aryeo_get_order for a single order) or states when-not to use it, so it stops short of the top score.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the GET endpoint reference and the id-consumption hint; it says nothing about result ordering, rate limits, or response shape, which would have added real value over 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?

A single front-loaded sentence plus the endpoint, with zero filler. The most important information (what it lists and how the output is consumed) comes first.

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 paginated list tool with full schema coverage and no output schema, the definition is nearly sufficient; the implicit hint that results carry ids covers the key consumer need. A brief note on what fields the categories return 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 100% — page, sort, search, and per_page each have defaults, bounds, and semantics documented in the schema. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the product categories') and ties it to its downstream use with aryeo_list_products. It is clearly distinguishable from the sibling list tools, though it never explains what a category represents beyond serving as a product filter.

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 parenthetical 'use the ids to filter aryeo_list_products' implies the workflow context in which this tool belongs, but there is no explicit when-to-use/when-not guidance and no mention of pagination or search workflow instructions beyond what the schema already says.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds a real behavioral fact beyond them: inactive products are filtered out by default, which changes what the agent sees in results. It omits pagination/return-shape detail, which is minor for a read 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?

Three short sentences, front-loaded with the resource, then the key default behavior, then the endpoint. 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?

For a read-only list tool with zero required params, no output schema and fully documented parameters, the description covers the essentials plus the one non-obvious default. Return shape and pagination are left to the schema, which is acceptable here.

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

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

Schema description coverage is 100%, so every parameter is already self-documenting (page/next_page, sort, type, search, per_page, category_ids). The description only reinforces include_inactive by stating the default-hidden behavior, adding modest value over the schema text.

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

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

Specific verb + resource: 'List your services/products (main products and add-ons)' and it clarifies the domain entity (products, not categories or orders). It does not name a sibling explicitly, but the resource is distinct enough from aryeo_list_product_categories that an agent can pick 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?

The description implies usage (browse the product catalog) and gives one conditional rule — set include_inactive to see hidden products. It never says when to choose this over aryeo_list_product_categories or how it relates to order/listing flows, so selection guidance 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned fields (assignee, due date, completion state) and the backing endpoint, but says nothing about result volume or pagination — notable given there are zero filter parameters, so a call returns the full task 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, front-loaded sentences with no filler: the first carries purpose and payload, the second carries the endpoint. Nothing redundant with the title.

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

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

With no parameters and no output schema, the description does its main job by naming the fields each task carries. The remaining gap is behavioral scale — whether results are paginated or capped — which matters for a zero-filter list on an open-world API.

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 no parameters, so there is nothing for the description to disambiguate beyond confirming the call is unfiltered. That is the baseline-4 case; the description does not mislead about any inputs.

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 tasks") and clarifies what a task is ("to-dos such as editing or delivery steps"), which disambiguates it from appointment/order siblings. The "List" verb plus singular sibling aryeo_get_task makes the collection-vs-single distinction inferable, 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?

Usage is only implied by the verb: use this to browse tasks, use aryeo_get_task for one task, aryeo_complete_task to close one. There is no explicit when-to-use, when-not, or named alternative, so the agent must infer routing from sibling names.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by naming the underlying GET endpoint and the categories of events returned, but it does not mention pagination, response shape, or rate-limit 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?

Two short sentences plus the endpoint reference, with the resource scope front-loaded and the id-source instruction immediately after. There is no wasted language.

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, open-world list tool with full schema coverage and clear annotations, the description supplies enough context to invoke it correctly: what window to request, which id to supply, and what event categories are returned. It is only slightly short of complete because it does not describe pagination or result ordering.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: 'between two moments' clarifies the start/end role, and the pointer to aryeo_list_team_members explains where the required team_member_id comes from. The enum values are also reflected in the described event categories.

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

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

The description states a specific resource and scope: a team member's calendar between two moments, enumerating appointment, block, external, and buffer event types. It is distinguishable from aryeo_list_team_members by pointing there for the id, though it does not explicitly differentiate itself from aryeo_list_appointments.

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 one actionable routing instruction: use aryeo_list_team_members to obtain the team_member_id. Beyond that, it implies when to use the tool (to view a calendar window) but gives no explicit when-not guidance or comparison against similar listing tools such as aryeo_list_appointments.

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, non-destructive, open-world profile, but the description adds real behavioral context: `company_user` is included by default, specific fields are returned, and an unknown `include` value causes Aryeo to reply with the allowed list — useful failure-mode disclosure. No pagination/return-shape detail, keeping it below 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?

Front-loaded with the core purpose, then the two-ID caveat, which is the highest-value information for an agent. Dense but not padded; the only mild cost is that the ID discussion is packed into one long sentence.

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 and does so by naming the fields and the default-expanded relation, plus the endpoint. Pagination behavior is left to the schema's next_page note, so it is nearly but not fully self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the `company_user` default and the ID semantics used by other tools, but adds no syntax or format detail for `search`, `page`, `per_page`, or `include` beyond what the schema already states.

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

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

States a specific verb and resource ('List your company's team members (photographers and staff)') and enumerates the fields returned (role, status, service-provider flag, permissions). The distinction from aryeo_list_team_member_events is drawn explicitly via the two-id explanation, so an agent can tell them apart 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?

Explicitly routes the agent: member `id` for aryeo_list_team_member_events and as task assignee company_team_member_id, while `company_user.id` is the USER id for the user_ids filters of orders, appointments, timeslots and dates. That is strong downstream guidance, though it doesn't state when to prefer this listing over other company-level listings.

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, idempotentHint=false and openWorldHint=true; the description adds the crucial non-obvious fact that notify=true sends a message to a third party (the order's customer), which is real behavioral value. It does not say what happens if the slot is taken or whether the old time is released, leaving some gaps for a destructive, non-idempotent operation.

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, mutation front-loaded, then the risk-bearing side effect, then the prerequisite workflow and endpoint. 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 4-required-param mutation with full schema coverage and rich annotations but no output schema, the description covers effect, side effect, prerequisite and endpoint. It omits failure modes (unavailable slot, invalid appointment id) and response shape, which the missing output schema forces the agent to guess.

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

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

Schema description coverage is 100% and each parameter already carries format examples and the notify true/false meaning, so the description's restatement of notify adds nothing new. Baseline 3 applies since the schema does the heavy lifting.

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

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

Specific verb ('MOVE') plus resource ('an appointment') plus the exact effect (new start and end time), capitalized to signal mutation. It is unambiguously distinguishable from aryeo_cancel_appointment and aryeo_get_appointment 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?

Gives an explicit prerequisite workflow ('Check availability first (aryeo_list_available_timeslots)') and names the alternative tool for that check. It stops short of any exclusion guidance – e.g. when to cancel instead of move – so it is strong but not complete.

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?

Goes well beyond the destructiveHint/idempotentHint annotations by naming exactly what is lost (the entire prior note) and the read-before-write workflow required to avoid data loss. It also discloses visibility semantics (internal team only, never customer-facing), which annotations cannot express.

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, with the destructive replace semantics and visibility scope front-loaded before the mechanics. Every sentence carries distinct information.

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

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

For a two-parameter write with no output schema and both parameters required, the description supplies everything an agent needs: audience, overwrite behavior, clearing semantics, the read-first precondition, and the endpoint. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still adds real meaning: internal_notes is a full replacement rather than an append, and an empty string is a valid clearing operation. It does not restate the 2550-character limit, which the schema already handles.

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 in caps (REPLACE) plus the exact resource and field (internal notes of an order), and immediately disambiguates the audience (team-only, not customer-visible). An agent can distinguish this from aryeo_get_order or other mutators 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?

Gives clear operative guidance: read the order first and send the complete new text, and empty string clears the notes. It implies the aryeo_get_order prerequisite rather than naming it explicitly, and never states when not to use this tool, so it falls short of the top band.

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