Feegow MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds genuinely new behavior — no API-level restore, side effect of patient notification governed by clinic settings. It does not state what happens on a repeat cancel (likely an error, per non-idempotent hint) or any permission requirements.

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

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

Three tight sentences: mutation flag first, irreversibility and side effect second, required input and endpoint last. 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 3-parameter destructive tool with no output schema, it covers irreversibility, the prerequisite reason lookup, and the patient-notification side effect. Minor gaps remain around failure modes on an already-cancelled appointment and the role of the optional notes field.

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

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

Schema coverage is 67% and already documents reason_id's source tool and notes' purpose, so the description's reason-id sentence largely repeats structured data. It adds the 'required' emphasis but says nothing about appointment_id or when to supply notes, 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?

Opens with an explicit WRITE marker and a specific verb+resource: 'cancels an existing appointment', scoping it clearly apart from feegow_create_appointment, feegow_reschedule_appointment, and feegow_update_appointment_status. The endpoint path reinforces exactly which operation is performed.

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 context: irreversible, so book a new appointment instead, and a reason id is required from feegow_list_appointment_reasons. It stops short of naming sibling alternatives explicitly — e.g. that feegow_reschedule_appointment moves a slot rather than killing it, or that feegow_update_appointment_status may be preferable for no-shows.

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 annotations by disclosing external side effects (patient may be notified via SMS/e-mail/WhatsApp per clinic automation), the past-date constraint, and refusal behavior on taken slots or unknown patients. What is missing is what the call returns (no appointment id mentioned) despite no output schema existing.

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

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

Three short sentences, front-loaded with the WRITE marker and the prerequisite, with no filler. Every clause (past dates, prerequisites, notifications, units) carries operational weight.

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

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

Covers preconditions, constraints, side effects and the endpoint for a 17-parameter write tool. The remaining gap is the response: with no output schema and no mention of what comes back (e.g. the created appointment id), an agent cannot chain follow-up calls without guessing.

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

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

With 76% schema coverage the schema already documents most fields, and the description's one added rule ("valor is in CENTS and must be 0 with insurance") largely restates the value_cents property description. It adds no guidance on the eight required ids or on the insurance/insurance_plan_id pairing beyond what the schema 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?

Opens with an explicit verb+resource marker ("WRITE: books a new appointment in the clinic's agenda") and the parenthetical "not in the past" scopes it further. The verb distinguishes it cleanly from feegow_reschedule_appointment, feegow_cancel_appointment and feegow_list_appointments without needing 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?

States a concrete prerequisite ("Check feegow_get_available_schedule first"), names the failure conditions ("a taken slot or unknown patient is refused"), and implicitly routes existing-booking changes to the reschedule/cancel siblings. An agent knows both when and how to invoke this.

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

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

Annotations only declare it is a non-readonly, non-destructive, open-world write; the description adds the genuinely non-obvious behavior — the dedup key (CPF + birth date, or name plus mobile/e-mail/birth date) and that the existing id is returned with nothing created. It also flags the LGPD constraint on health data. Return shape beyond patient_id and error modes are not covered.

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

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

Four short sentences, all load-bearing: write semantics and return first, then the dedup rule, then the no_cpf flag, then the compliance caveat. The trailing 'POST /patient/create' is minor filler but costs nothing.

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 27-parameter write tool with no output schema, the description covers the essentials an agent needs: what is created, what is returned, and when nothing is created. It could say more about what happens to the optional fields on a dedup hit (are they merged or discarded), which is the main remaining ambiguity.

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 earns a bump by explaining how cpf, birth_date, mobile and email interact as identity keys, and by tying no_cpf to the ignore-cpf behavior. It still leaves most of the 27 optional fields (insurance, price table, address) to the schema alone.

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?

Opens with 'WRITE: registers a new patient and returns the patient_id' — a specific verb, resource, and outcome. This cleanly separates it from feegow_update_patient (mutates an existing record) and feegow_get_patient (read), and the dedup note explains why it may not actually create anything.

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 operating context: it is the write path for new patients, set no_cpf=true when there is no CPF, and existing matches are returned instead of duplicated. It does not explicitly say 'use feegow_update_patient to change an existing patient', so the sibling routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful pre-condition framing (call this before creating) and the underlying endpoint, but says nothing about result volume, empty-result behavior, or whether availability reflects real-time capacity on an open-world system.

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

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

One front-loaded sentence carries the search scope, followed by the workflow hint and the endpoint in a compact trailing clause. No filler or repetition.

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

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

With 10 parameters and no output schema, the description leaves the return shape entirely implicit — an agent cannot tell whether slots come back as flat timestamps, per-professional groupings, or enriched with unit names, which matters for deciding whether to chain into create_appointment directly. The input side is adequately covered by the rich schema, so this is the main remaining gap.

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

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

Schema description coverage is 90% and the schema already documents the kind enum, required-when-kind constraints for specialty_id/procedure_id, and the unit_id 0-means-matriz convention. The description's 'optionally for one professional, unit or insurance' is accurate but only restates the optional filters; the age range parameters are never mentioned. 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 — free appointment times — plus the two ways to search (specialty or procedure) and the date window. An agent can immediately distinguish it from feegow_list_appointments (existing bookings) and from the create/reschedule 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?

'Use before feegow_create_appointment' gives an explicit sequencing rule that routes the agent into a two-step flow. It stops short of exclusions — it never says this is not for checking already-booked slots (feegow_list_appointments) — but the positive guidance is clear.

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 safety is covered; the description adds valuable non-obvious behavior: a 5-minute server-side cache, how to bypass it, the underlying endpoint, and an LGPD/health-data sensitivity flag. It stops short of anything about error behavior or partial results, but that is a minor gap against rich added context.

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

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

Two dense sentences with zero filler: fields returned first, then the cache rule, then the endpoint. Every clause carries information an agent can act on.

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

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

With no output schema, the description usefully enumerates expected return fields, and it covers caching, sensitivity, and the endpoint. It is nearly complete for a read tool; only the id-vs-CPF precedence and the two boolean include flags are left to the schema.

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

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

Schema coverage is 80%, so patient_id, cpf, and fresh are already documented in the schema. The description only reinforces the id-or-CPF selector and adds timing context for fresh ('right after an edit'); it says nothing about include_photo_url or include_health_program beyond their existing schema text. Baseline 3 is appropriate.

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

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

Specific verb and resource: retrieves exactly one patient, keyed by id or CPF, and enumerates the returned fields (name, birth date, contacts, address, insurance). This clearly separates it from feegow_list_patients and feegow_create_patient without the agent 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?

Implies single-record retrieval via 'one patient by id or CPF' and gives a concrete conditional rule: set fresh=true right after an edit. It does not explicitly name feegow_list_patients as the alternative for bulk lookup, so the routing guidance 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the underlying endpoint (GET /professional/search), with nothing about auth requirements, rate limits, or error behavior for an unknown id.

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

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

Two short fragments with the purpose front-loaded and zero redundancy. The trailing endpoint reference is marginally useful for API-mapping but borders on filler.

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

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

For a one-parameter read-only lookup with full schema coverage and annotations carrying the safety profile, the description is adequate: it names the returned content (details and specialties). Only the absence of any note on missing/unknown ids or return shape keeps it from being complete.

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

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

Schema description coverage is 100%, and the professional_id description already points to feegow_list_professionals for id discovery. The tool description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('One professional's details and specialties'), clearly singular and thus distinguishable from the plural sibling feegow_list_professionals. It does not explicitly name that sibling, so sibling differentiation is implied by number rather than stated.

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

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

The singular framing implies this is the lookup-by-id path as opposed to the listing tool, but the description never says when to choose one over the other, nor any prerequisite for obtaining the id. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: that this is a GET lookup whose purpose is to supply a required id to two mutation tools, which shapes how an agent sequences calls. It does not describe the returned fields beyond the id, keeping it short of a 5.

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

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

A single compact sentence plus the endpoint: the resource comes first, the cross-tool dependency second, and there is no padding. The parenthetical Portuguese synonym 'motivos' is a small but useful disambiguation for a Brazilian-domain API.

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

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

For a zero-parameter read-only lookup with full annotation coverage and no output schema, the description gives the agent everything needed to decide when to call it and why. The only gap is not hinting at the shape of each returned reason beyond the id.

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. Baseline 4 applies; the schema is empty and the endpoint string adds only orientation.

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 (cancel/reschedule reasons) and its role: supplying ids to feegow_cancel_appointment and feegow_reschedule_appointment. It is clearly distinguishable from siblings like feegow_list_appointment_statuses because the domain (motives for cancellation/rescheduling) is named. It stops short of a leading verb like 'List all...', but the intent is unambiguous.

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

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

Explicitly names the two consuming tools whose required id comes from this list, which tells the agent exactly when to call it (before cancelling or rescheduling). No when-not-to-use guidance is given, but for a zero-param reference list that omission is minor.

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, non-destructive, open-world behavior, so the bar is lower; the description still adds genuine context: pagination semantics tied to the previous reply's next_start, and a health-data warning that responses contain patient ids. It stops short of describing the payload shape or handling of empty ranges.

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

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

Three compact, front-loaded clauses: scope, filtering, pagination, then the health-data caveat. No filler and nothing buried at the end.

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

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

For a 14-parameter, no-output-schema list tool, the description covers filtering, paging, conditional required dates, and the sensitive-data caveat. The response field list is unspecified, but the next_start contract gives enough to iterate 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 coverage is 64% across 14 params, and the description compensates by enumerating the filterable dimensions (professional, patient, unit, location, specialty, channel, procedure, status) and the conditional-nullity of date_from/date_to and the start/next_start pairing, adding meaning beyond the bare schema.

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

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

States the exact resource (appointments), the two access modes (date range or single id), and the full filter axis set, so it is unmistakably the read/list tool among siblings like feegow_create_appointment and feegow_get_available_schedule.

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?

Explains the date requirement shim (dates required unless appointment_id is given), tells the caller to page with next_start, and routes to feegow_list_units, feegow_list_booking_channels and feegow_list_appointment_statuses for id resolution. It does not contrast itself with any alternative read tool, but there is no close sibling that overlaps.

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 the safety profile is covered. The description adds that it is a GET endpoint and that the set of statuses is a fixed enumeration (booked, confirmed, no-show, cancelled...), which is useful, but says nothing about ordering, caching, or whether the list is tenant-configurable.

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

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

Two compact sentences with zero filler. The content is front-loaded: what the tool returns first, then what it's for.

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 read-only lookup with annotations covering safety, the description is nearly sufficient — it names the resource and illustrates the returned values. Without an output schema, a brief note on the return shape (list of id/name pairs) and whether the list is stable would have made 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?

Zero input parameters, so there is nothing for the description to disambiguate; baseline 4 applies. It correctly takes no arguments, and the description doesn't imply required filters that would confuse an agent.

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 (appointment statuses) and what it returns (ids and names), with concrete example values. It doesn't explicitly name the sibling tools it relates to (feegow_update_appointment_status, feegow_list_appointments), but 'used to filter and update appointments' gestures at the relationship.

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?

'used to filter and update appointments' implies the usage context — fetch status ids before filtering or updating — but never says explicitly to call this before updating a status, nor does it state exclusions or name the alternative tools. Usage is inferable rather than instructed.

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 and the description doesn't need to repeat it. The description adds a little beyond that by illustrating the kind of values returned and citing the backing endpoint, but it never says the result is a list or what fields each channel carries.

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 plus an endpoint citation, front-loaded with the useful part. The trailing "(online booking, clinic...)" ellipsis is slightly sloppy and the raw GET path adds marginal value, but there is no filler prose.

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-parameter, non-destructive lookup this is adequate, and the parenthetical sample values help. However, there is no output schema, so the description is the only place an agent could learn the shape of each returned channel (id/name), and it doesn't say it.

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 and the description correctly makes no parameter claims, so there is nothing to mis-document. With no parameters and 100% schema coverage, the baseline of 4 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 identifies the resource precisely ("channels an appointment can be booked through") and gives concrete example values (online booking, clinic...), which distinguishes it from sibling lookups like appointment_reasons or appointment_statuses. It lacks an explicit verb (the verb only appears in the title), so it falls short of the fully self-contained 5.

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

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

Usage is only implied: an agent can infer this is reference data to populate a channel field when creating/booking an appointment, but the description never says so, and it names no alternative or prerequisite. There is no explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds almost nothing beyond that: the "GET /insurance/list" endpoint string restates read-onlyness, and nothing is said about whether results are unit-scoped, filtered, paginated, or cached. "with their plans" is the only real signal, implying nested plan data in the response.

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

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

Two short sentences, front-loaded with the resource and free of filler. It is close to under-specified rather than bloated, but nothing in it is wasted.

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

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

For a simple, no-required-parameter list tool with an output schema absent, the description should at minimum say whether insurances are clinic-wide or per-unit and roughly what the response contains. "with their plans" partially covers the return shape, but scoping and the relationship to unit_id are left 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?

The single unit_id parameter is fully documented in the schema, including the 0 = main clinic convention and a cross-reference to feegow_list_units. With 100% schema coverage the baseline is 3; the description itself contributes no additional parameter meaning.

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

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

"All accepted health insurances with their plans" states the resource and the returned granularity (insurances plus plans) in a single clear phrase. The list operation is implied rather than stated as a verb, and the description does not distinguish this from the sibling feegow_list_professional_insurances, which is the most likely confusion point.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance is given. The sibling lookalike (feegow_list_professional_insurances) is never mentioned, so the agent must infer the distinction from the names alone.

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

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

Annotations already declare readOnly, openWorld, and non-destructive behavior. The description adds the API endpoint (GET /financial/list-invoice) and labels the data as 'Financial data', which suggests sensitivity, but gives no further behavioral context like pagination, rate limits, or return format.

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 front-loaded with the core purpose and returned fields, then lists optional filters. It is concise overall, though the fragment 'Financial data.' is slightly redundant and the structure is a bit choppy.

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 list tool with 6 parameters and no output schema, the description adequately covers the returned fields and optional filters. It omits details like pagination or sorting, but given the simplicity and existing annotations, it is sufficiently complete for an agent to invoke 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 coverage is 67% with some properties lacking descriptions (invoice_id, appointment_id). The description adds that unit, invoice, and appointment are optional filters, but does not explain their semantics beyond that, leaving a gap for the undocumented parameters.

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

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

The description clearly identifies the resource (financial invoices) and scope (date range, receivables vs payables) with specific returned fields. It lacks an explicit verb like 'list' in the description itself, but the title and overall phrasing make the purpose 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?

Usage is implied by the date range and direction parameters, and the optional filters are mentioned. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives—though no direct sibling tool exists for invoices.

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 the safety profile is covered. The description adds value beyond them by naming the underlying endpoint (GET /company/list-local) and the returned field set, which matters since no output schema exists; it does not cover pagination, ordering, or auth requirements.

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

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

Three short sentences: purpose, downstream use, endpoint. The most decision-relevant fact (which ids you get and what they are for) is front-loaded, and there is no filler.

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

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

For a zero-parameter read-only list tool with no output schema, the description supplies the essential return shape, the endpoint, and the downstream dependency. Minor gaps remain: whether results span all units at once and whether there is any paging.

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 the baseline of 4 applies. The description's mention of id/name/unidade_id refers to response fields rather than inputs, so no parameter meaning is needed or missed.

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 ('Rooms/locations registered in each unit') and enumerates the returned fields (id, name, unidade_id). The relational framing ('in each unit') implicitly distinguishes it from feegow_list_units, though it never names 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 location id is needed to create appointments' gives a concrete reason to call this before feegow_create_appointment, establishing clear usage context. It lacks explicit exclusions or a statement of when another listing tool (e.g., list_units) is the better 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds one genuinely useful trait beyond them: the response contains health data governed by LGPD, which signals sensitivity. It says nothing about pagination, result size, or empty-result 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?

Very short and front-loaded, with no filler sentences. But the trailing 'GET /patient/list-dependents.' duplicates information already implied by the tool name and adds little for an agent, while the missing verb makes the core statement harder to parse.

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

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

For a one-parameter read tool with no output schema and annotations covering safety, the definition conveys the essential shape: dependents of one patient, health data. The remaining gaps (identifier format, result contents) are modest relative to this tool's simplicity.

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

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

Schema description coverage is 0%, so the description must carry the burden for patient_id. 'Under one patient' only indirectly implies that patient_id selects the parent patient; it does not state the expected identifier type (internal ID vs. CPF/record number) or the error behavior for unknown IDs.

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

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

The fragment 'Dependents registered under one patient' identifies the resource (patient dependents) and the scoping (one patient), which separates it from feegow_list_patients and feegow_get_patient. However, it omits an explicit verb and reads as a noun phrase; the GET path restates the operation but the agent must infer 'lists'.

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

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

No guidance on when to use this instead of feegow_get_patient (which may also return linked records) or feegow_list_patients. No prerequisites, no mention of what happens when a patient has no dependents.

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 safety profile (readOnly, non-destructive, openWorld), and the description adds genuinely useful behavioral context beyond them: it flags LGPD-sensitive health data, states which fields come back (names, contacts, CPF), and explains the paging contract. It stops short of saying what happens with no filters (full dump) or the default page size, both of which affect how an agent drives 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?

Three short sentences, zero filler, with the filter scope front-loaded before the data-sensitivity and paging notes. Every sentence carries distinct information an agent needs.

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 eight params, no required fields, no output schema and only hint-level annotations, the description covers what the tool returns and how to page, which is the right level of detail. The absent piece is behavior with no filters applied and the next_offset/offset naming mismatch, both of which could trip up an agent on first call.

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

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

Schema description coverage is 100%, so the schema already documents every filter, its pattern and defaults, making 3 the baseline. The description adds little parameter-level meaning beyond naming the same filters, and it introduces mild confusion by telling the agent to pass "next_offset" while the actual parameter is named "offset".

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?

"Registered patients, filtered by ..." names the resource and enumerates the five filter dimensions, so an agent immediately knows this is a filtered patient listing rather than a single lookup. The verb is implicit and it never contrasts itself with feegow_get_patient or feegow_list_patient_dependents, which is the only gap.

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

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

Usage is implied by the filter list plus the note to pass the previous reply's next_offset for paging, and source_id points to feegow_list_patient_sources as a prerequisite lookup. There is no explicit when-to-use-this-vs-get_patient guidance and no statement of whether filters combine or are mutually exclusive, which matters with eight optional params and zero required.

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 underlying endpoint, not whether results are paginated, cached, or tenant-scoped. With annotations carrying the load, this is adequate but thin.

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

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

One short sentence plus the endpoint path; the purpose and the downstream use are front-loaded with no filler. Every clause earns its place.

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

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

For a trivial lookup with no arguments and no output schema, the description covers what the tool returns (sources and their ids) and why an agent would call it. Only the shape of each returned item is unspecified, which is a minor gap at 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?

The tool takes zero parameters and the schema is empty, so there is nothing to disambiguate. Baseline 4 applies; no parameter detail is required.

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: 'patient acquisition sources (origens) and their ids'. The domain alias 'origens' and the returned fields make it distinguishable from sibling lookup lists such as list_booking_channels or list_insurances, though it does not explicitly name those alternatives.

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

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

The phrase 'used when creating a patient' ties the tool to feegow_create_patient and implies the ids are inputs to that call, which is the key routing decision. There is no explicit when-not guidance, but for a zero-parameter reference list the trigger is unambiguous.

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, and the description adds real operational detail: prices are returned in cents with a worked example (R$ 12.00 = 1200) and the underlying endpoint GET /procedures/list is disclosed. It does not mention pagination, result limits, or behavior when no filter is supplied, which keeps it out of the top band.

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

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

Three compact sentences, front-loaded with the returned shape and the cents gotcha, then the selector requirement, then the optional narrowing. No restatement of the title and 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 an 8-parameter, no-required-parameter read tool with no output schema, the description covers return fields, the required-selector expectation, and unit/pricing context. The gap is what happens with zero filters (full scan? error?) and any paging, which matters given all parameters are optional.

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 75% and the schema already documents unit_id=0 for the main clinic, patient_id for patient pricing/insurance, and procedure_type_id cross-reference. The description mainly restates the filter set; its only genuinely additive semantic note is that prices are in cents, which concerns the response rather than an input.

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

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

Names the resource (procedures, with consultations/exams as concrete examples) and the payload it returns: price, duration, online-booking flag. It explicitly routes the agent to feegow_list_procedure_types for the type vocabulary, so it is distinguishable from that sibling without opening a schema.

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

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

"Give a procedure type ... or one procedure id; optionally narrow by name, unit, specialty, professional, patient or price table" tells the agent exactly which inputs are the primary selector and which merely narrow results. It lacks any statement about when not to use it (e.g., bulk listing without filters, or versus other list tools), so it falls short of explicit 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, destructiveHint=false and openWorldHint=true, so the safety profile needs no restating. The description adds the underlying endpoint (GET /procedures/types) and indicates the payload contains type names plus ids. It does not mention whether the list is complete or paginated, which is the main remaining behavioral gap for a lookup tool.

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

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

A single compact sentence plus the endpoint, with the most useful information (what a type is, and that ids are returned) front-loaded. 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 zero-parameter reference lookup with no output schema, the description covers what it returns (type names and ids) and why it exists (feeds feegow_list_procedures). It stops short of describing the response shape or completeness, a minor gap given the tool's simplicity.

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 the baseline is 4. The description correctly implies no input is needed. There is nothing further the description could add on this dimension.

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 procedure types) with concrete examples of what a type is (consultation, exam, surgery, return) and the fact that ids are included. It also names the sibling it feeds, feegow_list_procedures, which separates it from the other list_* tools. Not quite a 5 because it doesn't state scope (all types vs. filtered).

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?

"used by feegow_list_procedures" gives a concrete usage context: call this to obtain the ids that feegow_list_procedures expects. There are no explicit exclusions or when-not conditions, but the dependency is enough for an agent to place it correctly in a workflow.

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, which is redundant, and does not mention pagination, empty-result behavior, or authentication needs. With annotations carrying the load, a 3 is appropriate.

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

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

Two short fragments with the resource front-loaded and zero filler. The endpoint citation is arguably redundant, but the description remains compact and easy to scan.

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

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

For a simple single-parameter read tool with no output schema and complete annotation coverage, the description says enough to call it correctly. A brief note on return shape would be nice but is not essential here.

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

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

There is one required parameter with 100% schema description coverage ('Feegow professional id'). The description does not add meaning beyond the schema, so the baseline 3 applies.

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

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

The description states the resource precisely: health insurances accepted by one professional, which implicitly distinguishes it from the sibling feegow_list_insurances (all insurances). It lacks an explicit verb like 'list', but the scope is unambiguous.

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

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

Usage is only implied through the phrase 'by one professional', suggesting this is the per-professional variant rather than the global insurance list. There is no explicit when-to-use statement, no named alternative, and no prerequisites mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that both active and inactive records are returned and identifies the fields (names and ids), but says nothing about pagination, result caps, or ordering.

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 with the scope front-loaded, plus the backing endpoint path. Nothing is redundant, though the raw 'GET /professional/list' is of marginal use to an agent.

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

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

With no output schema, the description usefully states the returned fields (names and ids). Combined with annotations covering the read-only safety profile and a fully described schema, an agent has enough to call it correctly; only pagination/ordering behavior is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters fully, including the 0=matriz convention for unit_id and cross-references to feegow_list_units and feegow_list_specialties. The description's 'by unit or specialty' merely echoes the schema, landing at the baseline.

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 ('Doctors and other professionals (names and ids)') and adds scope ('active or inactive, optionally by unit or specialty'). It is clear what the tool returns, though it does not explicitly distinguish itself from the sibling feegow_get_professional for single-record lookups.

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 phrase 'optionally by unit or specialty' implies when the filters apply, but there is no explicit when-to-use vs alternatives guidance. It never points to feegow_get_professional for detail, nor states a preference for list vs get.

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 the safety profile is covered. The description adds genuinely useful context beyond that — that monetary values are in REAIS and that the date range applies to created or last-changed — but says nothing about pagination, result caps, or ordering.

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 what the tool returns and followed by the invocation rule. The trailing 'GET /proposal/list' is endpoint trivia that adds little for an agent, but overall there is no bloat.

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

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

For a 4-parameter read tool with no output schema, the description covers filtering and currency but leaves the return shape, pagination, and the failure mode when neither patient_id nor a date pair is given entirely unstated. That last omission is the most consequential gap for correct invocation.

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

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

Schema coverage is 75%, with patient_id carrying no description in the schema at all; the description compensates by clarifying it identifies one patient. It also expresses the disjunctive requirement (patient_id OR both dates) that the schema's zero required parameters does not convey. date_kind is left entirely to the schema enum description.

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

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

Names the resource specifically (treatment/procedure proposals), states the value unit (REAIS), and scopes it to a patient and/or date range. It is clearly distinguishable from siblings like feegow_list_invoices or feegow_list_procedures, though it never explicitly contrasts itself with them.

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

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

'Give patient_id, or both dates' communicates the invocation constraint, which is the most important usage fact here. However, it gives no when-not guidance, no mention of what happens if neither is supplied, and no alternatives for related data (e.g., invoices).

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 genuine value beyond that by disclosing the shape of the result — procedure ids and an online-booking visibility flag — which the agent could not know from the annotations alone. Pagination and auth behavior remain unstated.

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

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

Two compact sentences with zero filler, front-loading the resource and its returned fields before the endpoint path. Nothing is redundant.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so briefly and adequately for a simple list endpoint. The only shortfall is the absence of usage guidance about when this list is the right source versus related procedure lookups.

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 unit_id parameter is already fully documented in the schema (0 = main clinic, omit for all units, cross-reference to feegow_list_units). The description adds nothing about parameters, 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?

The description names a specific resource (medical specialties) and states what the payload contains (default consultation procedure ids, online-booking flag), so the agent knows exactly what it gets. It does not contrast itself with neighboring lookups such as feegow_list_procedures or feegow_list_procedure_types, so the sibling differentiation is missing.

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 statement, no mention of the optional unit_id scoping decision, and no pointer to alternatives. Only the raw endpoint path ('GET /specialties/list') hints at context, leaving selection entirely to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful substance beyond that: the fields returned, the special-case main unit with unidade_id 0, and the underlying endpoint — details an agent could not infer from annotations alone.

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: the returned content first, then the usage implication, with the endpoint tucked at the end. Nothing is redundant, though the raw GET path is marginally less useful to an agent than additional semantics would be.

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, no output schema and full annotation coverage, the description carries the burden of describing return content — which it does by naming the fields. It is nearly complete for this complexity; only the overlap with feegow_list_locations is 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?

The tool takes zero parameters, so per the baseline a 4 applies. The description correctly implies no filtering arguments are needed, consistent with the empty input schema.

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

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

States a specific verb and resource: lists the main unit (matriz, unidade_id 0) plus branches, enumerating returned fields (trade name, CNPJ, address, contacts). It is clear what the tool does, though it does not distinguish itself from the sibling feegow_list_locations, which could plausibly mean the same thing to an agent.

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?

"Use the unit ids to filter other tools" gives explicit downstream usage and explains why a caller would want this list. It stops short of exclusionary guidance — nothing says when to prefer feegow_list_locations over this tool, which is the one real ambiguity.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real value beyond that: the old slot is released, the patient may be notified per clinic settings, and the underlying endpoint is POST /appoints/reschedule. What's missing is any note on failure recovery or what happens to prior notes when a reschedule fails.

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

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

Three short sentences, front-loaded with the WRITE marker and the core mutation, followed by the prerequisite and the side effect. No filler.

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

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

With no output schema and five parameters, the description covers the mutation semantics, the required reason source, and the notification side effect – enough for an agent to invoke it safely. It leaves the notes parameter and the return shape unexplained, a minor gap for a well-annotated 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 80%, so the schema already documents date format, time format, and reason_id provenance. The description only reinforces the reason_id requirement and doesn't explain the optional notes parameter or how required fields interact. 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?

States a specific verb and resource ("moves an existing appointment to a new date and time") and immediately clarifies the distinguishing behavior: "the old slot is released." This clearly separates it from create_appointment and cancel_appointment among the siblings.

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

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

Gives clear usage context by stating it operates on an existing appointment and requires a reason id sourced from feegow_list_appointment_reasons, naming that sibling explicitly. It stops short of stating when-not to use it (e.g. cancel vs reschedule for a cancelled slot), so it is clear context without explicit 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is covered. The description still adds real value by disclosing the side effect (a note is appended to the agenda) and the underlying endpoint. It doesn't discuss reversibility of a status change, but the destructive hint carries that.

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, all front-loaded: operation type first, then the status-id source, then the sibling routing. No filler or restatement of the title.

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

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

No output schema exists, but for a write tool this is sufficient: the mutation, its side effect, the id lookup path and the sibling boundaries are all stated, and annotations cover safety. An agent has everything needed to call it correctly.

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

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

With 50% schema coverage, the two undocumented params are appointment_id and status_id; the description compensates for status_id by pointing to feegow_list_appointment_statuses as the source of valid ids. notes and arrival_time are already documented in the schema, so the remaining gap is only appointment_id, which is self-evident.

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?

Opens with a specific verb and resource ('WRITE: sets an appointment's status') and enumerates concrete status examples (confirmed, waiting, attended, no-show). It explicitly distinguishes itself from the cancel and reschedule siblings, so an agent can route without opening schemas.

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

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

States the use case (changing status/adding an agenda note) and names the alternatives with the condition that selects them: 'To cancel or move an appointment use the cancel/reschedule tools.' It also routes to feegow_list_appointment_statuses for valid ids, closing the main usage gap.

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?

Beyond the annotations (destructiveHint, idempotentHint, openWorldHint) it discloses that this is a PATCH-style overwrite rather than a full replace, that CPF can be set once but never changed because the vendor rejects it, that health data falls under LGPD, and that reads are cached for 5 minutes. These are exactly the non-obvious behaviors an agent needs before mutating a patient record.

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

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

Four short segments, front-loaded with the WRITE marker and the most dangerous constraint (CPF) plus the verification hint. Every sentence carries operational information; nothing is restated 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?

For an 18-parameter mutation with no output schema, it covers the risky parts (CPF rule, partial overwrite, cache staleness, LGPD sensitivity). Minor gaps remain around error behavior and side effects of fields like price_table_id on billing, which would matter for a destructive write.

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 94%, so parameter meanings are largely carried by the schema and the baseline is 3. The description still adds genuine value the schema lacks: the CPF set-once rule and the partial-update overwrite semantics, which change how the agent should construct its arguments.

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?

Opens with 'WRITE: changes a patient's registration data', a specific verb plus resource, and the CPF-immutability detail plus the pointer to feegow_get_patient makes clear this is a partial update of an existing patient rather than a create. An agent can separate it from feegow_create_patient and feegow_get_patient 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?

It states the operating mode (only passed fields are sent and they overwrite stored values) and routes the agent to feegow_get_patient with fresh=true to observe the change, which is concrete usage guidance. It does not explicitly name feegow_create_patient as the alternative for new records, so it falls short of full when/when-not coverage.

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