elvanto

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

destructiveHint=true signals this is not a benign read, yet the description never explains what is destructive about it or what side effects (e.g. triggering automated follow-up communications) the enrollment causes. The follow-up example hints at downstream workflow effects, which is useful context, but the annotation's destructive claim is left unexplained.

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

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

Two compact sentences with the core action front-loaded and the API path trailing where it does not obstruct reading. No wasted 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?

There is no output schema, so return values need not be described, but the description omits what happens after enrollment (notifications, admin assignment effects) and any permission requirements. Adequate for invoking the tool, thin on consequences.

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 documents all three parameters, giving a baseline of 3. The description only restates that a step admin can optionally be assigned (mapping to assign_to) and adds no format or constraint detail beyond the schema.

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

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

The description states a specific verb and resource ('Put a person into a people-flow step') and even gives a concrete use case ('start a new guest's follow-up'), so the action is unambiguous. It does not, however, distinguish itself from the near-identical sibling elvanto_add_person_to_group, which an agent could easily confuse.

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 through the example ('start a new guest's follow-up') and the note that an admin can optionally be assigned, giving situational context. But there is no explicit when-to-use vs. when-not guidance and no mention of the add_person_to_group alternative.

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 destructiveHint=true, so the description carries meaningful extra weight. It discloses reversibility ('Undoable by removing them from the group in Elvanto'), which contextualizes the destructive hint, and names the underlying API operation (groups/addPerson), giving the agent a handle for further reference. It still omits auth/permission needs and duplicate-membership behavior.

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

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

Three short sentences with the operation and its option front-loaded and no filler. The trailing 'Elvanto: groups/addPerson' reference is minor but slightly redundant metadata rather than agent-facing guidance.

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

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

For a 3-parameter mutation with no output schema, the description covers the core operation, the optional position, and reversibility. What is missing is only edge-case behavior (duplicate membership, failure modes, permission requirements), which is a minor gap rather than a blocker.

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 three parameters (group_id, person_id, position enum) are already fully documented in the schema. The description restates the position option but adds no syntax or format detail beyond it, 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?

Specific verb+resource (add a person to a group) with the membership level (Leader / Assistant Leader) surfaced up front, so the agent knows exactly what the call produces. It is clearly distinct from siblings like elvanto_add_person_to_flow_step and elvanto_create_person, though it never names an alternative to route against, which keeps it at a 4 rather than 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?

Usage is implied by the wording ('optionally as Leader or Assistant Leader', omit for a regular member per schema), but there is no explicit statement of when to prefer this over related membership/flow tools or any prerequisite (e.g. person and group must already exist). Adequate but with a clear guidance 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?

Annotations declare destructiveHint=true, so the write/mutation nature is already conveyed. The description adds useful context (24-hour GMT times, draft staging for unpublished events) but omits permission requirements, side effects on the calendar, and what happens with repeat fields. Modest added value over 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, front-loaded with the core action and free of filler. The trailing 'Elvanto: calendar/events/create' endpoint reference is minor padding but not disruptive.

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 19-parameter mutation tool with a fully documented schema and a destructiveHint annotation, the definition covers the essentials: action, time format, and draft staging. Given the rich schema, the description is adequate, though auth/permission expectations go unstated.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the enum-constrained repeat/status/all_day fields. The description only restates the GMT time convention and draft status, adding no syntax or semantics 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 ('Create an event on a calendar') and adds scope ('optionally repeating'). An agent can distinguish it from the read-only sibling elvanto_list_calendar_events, 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?

Offers one concrete usage tip ('Use status "draft" to stage it unpublished'), which is genuine guidance, but says nothing about when to prefer this vs other creation tools, prerequisites, or the required organizer/calendar_id setup. Usage is implied rather than framed.

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 carry destructiveHint=true, so the description adds real value by disclosing return values ('new person id and family id') and a key behavioral exclusion ('Does not create a login'). It stops short of stating permission requirements or that a failed create may leave no record, hence not a 5.

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

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

Three short sentences, front-loaded with the core action, then return values, then the login caveat. No filler and no repetition of the title.

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

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

With no output schema, the description usefully states the return payload and a notable side-effect exclusion, which is what an agent needs for this 13-parameter create tool. It could be slightly stronger by naming prerequisites or required permissions, but the essential information is present.

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

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

Schema description coverage is 100% and the schema already documents all 13 parameters, including nested fields semantics and access_permissions refusal. The description adds a use-case example but no parameter syntax or 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?

States a specific verb and resource ('Add a new person to the church database') with a concrete example and an explicit scope note ('Does not create a login'). An agent can distinguish it from elvanto_update_person 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?

Usage is implied by the create semantics and the guest example, and the 'does not create a login' clause rules out one nearby expectation, but there is no explicit when-to-use versus sibling tooling such as update_person or add_person_to_group.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds only the upstream API reference ('groups/getInfo') and the hint that members can be pulled in via fields=["people"]; it says nothing about error behavior when an id is invalid or absent.

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 pairs the core action with the optional members flag, followed by a short API reference. Efficient, though the 'Elvanto: groups/getInfo' trailer is of marginal value to an invoking agent.

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

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

For a simple, read-only, two-parameter lookup with full schema coverage and a readOnlyHint annotation, the description covers what is needed to invoke it. It stops short of describing the returned group shape, which matters slightly since no output schema exists.

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

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

Schema coverage is 100%, so both parameters (id and fields) are already documented with an enum-style field list in the schema. The description adds a usage example for fields=["people"] but no syntax or semantics beyond what the schema provides, making 3 the correct 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?

States a specific verb and resource with scope: 'Fetch one group by id', which implicitly separates it from elvanto_list_groups. It is clear, but never explicitly distinguishes itself from the sibling list/search tools the way a 5 would.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The agent is left to infer that this tool is for retrieving a single known group id rather than browsing, and the more obvious alternative (elvanto_list_groups) is never named.

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

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

readOnlyHint=true already establishes this as a safe, non-mutating read, so the description's burden is lighter. It adds the fact that extra fields are opt-in and enumerates them, but says nothing about behavior on an invalid/unknown id, permissions required, or response shape. Adequate but not enriching.

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, front-loaded with the primary purpose and immediately followed by the optional behavior. The 'Elvanto: people/getInfo' endpoint reference is a compact, useful implementation anchor rather than 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 two-parameter getter with full schema coverage and a readOnly annotation, this covers what an agent needs to call it correctly. The only gap is that no output schema exists and the description does not characterize the returned person object beyond the requested fields.

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 both parameters are fully documented in the schema, including the custom_<field id> convention and the cross-reference to elvanto_list_custom_fields. The description's field list largely restates 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 (Fetch), resource (one person), and access key (by id), with the optional expansion scoped explicitly. 'One person' cleanly separates it from elvanto_list_people and elvanto_search_people without needing to name them.

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

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

Usage is only implied: 'by id' signals that a known person id is the precondition, which implicitly routes the agent away from search/list tools. There is no explicit when-to-use statement and no named alternative (e.g. 'use elvanto_search_people if you only have a name').

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

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

readOnlyHint=true already establishes this as a safe read operation, so the description is not carrying the safety burden. It adds the useful note that detail is opt-in via fields, but says nothing about auth requirements, error behavior for a missing id, or response size — modest added 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?

Front-loaded with the core action and scoped in two compact sentences with no filler. The trailing "Elvanto: services/getInfo." API pointer is marginally useful metadata, but the field enumeration in sentence one and the schema's enum list duplicate each other somewhat.

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 sensibly enumerates the returnable content so an agent knows what it can retrieve, which is the key missing piece. For a read-only fetch by id with fully documented params, this is close to complete; error/empty-result behavior is the only untouched area.

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

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

Schema description coverage is 100%, so both `id` and the `fields` enum are already fully documented in the schema. The description's parenthetical glosses ("plans (the order of service)", roster semantics) largely restate schema text rather than adding new meaning. Baseline 3 applies.

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

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

States a specific verb and resource ("Fetch one service by id") and enumerates the payload it returns (times, plan, roster, songs, files, notes). The singular "one service" clearly contrasts with elvanto_list_services, but the sibling is not named outright, so the differentiation is implied rather than explicit.

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

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

"with optional detail" signals that the `fields` argument expands the response, which is useful implied guidance for when to pass it. However, there is no explicit when-to-use, no when-not-to-use, and no alternative (e.g. elvanto_list_services for discovery) is named, leaving routing 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?

readOnlyHint=true already declares this is a safe read, so the description is not carrying the safety burden. It does add genuine behavioral context by disclosing that 'services' can be passed as a calendar value to fold services into the results, but says nothing about pagination limits or result 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 core scope (date range) front-loaded before the optional filter, plus a compact endpoint reference. Nothing is wasted or padded.

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

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

For a 6-parameter read tool with an output schema absent but every parameter fully documented in the schema and the read-only profile covered by annotations, the description supplies the essential framing. It could mention pagination behavior or that results omit extra fields unless requested, but nothing critical for a correct call is missing.

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

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

Schema description coverage is 100% – dates, page, page_size, fields, and the 'services' calendar value are all documented in the schema. The description's calendar note largely restates the schema's own '"services" for services' wording, so it adds little beyond the structured fields; 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 calendar events') plus scope ('between two dates, optionally for specific calendars'), so an agent immediately knows this is a read of event records rather than calendars or services. The distinction from elvanto_list_calendars and elvanto_create_calendar_event is implicit in the resource name but never called out 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?

It conveys the required shape of a call (a start/end date range, optional calendar filter) which implies usage, but there is no explicit 'when to use this vs alternatives' guidance and no note that calendar IDs must first come from elvanto_list_calendars. No exclusions or prerequisite notes are given.

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

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

The readOnlyHint=true annotation already establishes this as a safe read, so the description carries a lower burden. It contributes the fact that ids are included in the result, but says nothing about pagination, ordering, or what fields besides id come back.

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 padding; the purpose and return content come first. The trailing 'Elvanto: calendar/getAll' is mildly extraneous traceability text 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?

For a zero-argument list tool with no output schema, the description gives only a partial picture of the response (ids, implicitly names). It is adequate to invoke but leaves the returned shape largely unspecified.

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, which is the baseline-4 case; there is no parameter surface for the description to explain. The description's mention of returned ids is the only semantic content relevant to invocation.

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 ('the church's calendars') and adds the useful detail that ids are returned. It is clearly separable from siblings like elvanto_list_calendar_events or elvanto_list_groups, 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?

Usage is only implied: the agent can infer this is the lookup used when calendar ids are needed, since it returns ids. There is no statement of when to prefer this over elvanto_list_calendar_events nor any prerequisites, and the 'Elvanto: calendar/getAll' line is API mapping rather than 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 cover the safety profile (readOnlyHint=true), and the description adds real value on top: it discloses the returned attributes (id, name, type, allowed values) and the underlying API endpoint. It does not discuss pagination or whether the list is exhaustive, so it is not fully 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?

Three short sentences with zero filler; the resource and its returned shape come first, then the actionable usage note, then the API reference. Everything is front-loaded and 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 zero-param reference lookup with no output schema, the description covers what is returned (id, name, type, allowed values) and how to consume it, which is most of what an agent needs. The only unaddressed details are pagination and list completeness.

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 are zero parameters and the schema is trivially complete, so the baseline is 4. The description correctly adds no parameter commentary, since there is nothing to document.

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 a precise, unique resource ('the church's custom person fields') with the returned attributes enumerated. No sibling covers custom fields, so an agent can select it without ambiguity against the many list_* and get_* 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 concrete downstream usage: take the id and use it as 'custom_<id>' in fields / search, which explains why and when an agent should call this. It stops short of naming an explicit alternative or a when-not-to-use condition, but the context 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 only declare readOnlyHint=true, so the description carries the rest. It adds meaningful behavioral context that structured fields lack: results carry ids, and status is decoded (1 = active, 0 = archived), which is the sole guide to return values given there is no output schema. It does not describe the pagination envelope or ordering, so not a full 5.

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

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

Two tight clauses with the resource and scope front-loaded; nothing is redundant. The trailing endpoint reference ('Elvanto: financial/categories/getAll') is low-value for an agent but harmless.

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, read-only, paginated list tool, the description plus annotations plus a fully documented schema cover what an agent needs; the status decoding compensates for the absent output schema. Only ordering/return-shape details are left implicit.

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 and page_size are both documented in the schema), so the schema does the heavy lifting. The description adds nothing about pagination syntax or defaults, 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 verb and resource ('List ... categories') and disambiguates the domain with synonyms ('giving / chart-of-accounts ... (funds)') plus the endpoint path, which cleanly separates it from siblings like elvanto_list_people_categories or elvanto_list_transactions. It does not name any sibling to explicitly contrast against, so it stops 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 'List' verb implies a read/retrieve use case, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool. Usage is left to inference from the verb 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, so the safe-read profile is covered. The description adds real context beyond that: what fields are returned and that members/leaders only appear when fields=["people"] is requested. It does not cover pagination behavior, though the schema documents page/page_size.

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: resource and returned attributes first, then the optional expansion and endpoint reference. No padding or redundancy.

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

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

No output schema exists, so the description carries the return-value burden, and it does state the core return shape (groups with meeting day/time/place/frequency). With annotations covering safety and the schema covering all 5 params, 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%, so the baseline is 3. The description adds a concrete, actionable example (fields=["people"] to include members and leaders) that shows parameter intent beyond the schema's field list, which is a modest but real value-add.

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 small groups / ministries') plus the attributes returned (meeting day, time, place, frequency), and it names the underlying endpoint. It is clearly distinguishable from the sibling elvanto_get_group, which fetches a single group.

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

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

Usage is implied rather than stated: it shows how to expand results with fields=["people"], but gives no explicit when-to-use guidance, prerequisites, or named alternatives (e.g. versus get_group or search tools). Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint=true, and the description adds real value beyond that: it discloses pagination behavior and the response envelope (page, per_page, total), plus the underlying Elvanto endpoint (people/getAll). It stops short of stating default page size or max 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?

Two sentences with zero waste: capability and filters first, pagination behavior second, API reference last. Nothing is repeated or padded.

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

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

With no output schema and full schema description coverage, the description supplies the missing return-shape context via the pagination note, which is the key gap. The only omission is routing guidance relative to elvanto_search_people and elvanto_list_people_categories.

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%, with every parameter documented in the schema (including enum meanings for yes/no and the field list). The description only restates the filter axes at a high level, adding no syntax or format detail 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?

States a specific verb and resource ('List people in the church database') plus the optional filter axes (category, suspended/contact/archived status). It does not differentiate itself from the sibling elvanto_search_people, which an agent could easily confuse with this tool.

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

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

Usage is implied by the filter enumeration, so an agent can infer when the filters apply, but there is no explicit when-to-use or when-not-to-use guidance and no pointer to elvanto_search_people as the alternative for keyword-based lookup.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds that results include ids, but says nothing about pagination, ordering, or result shape, and there is no output schema to fall back on. With annotations carrying the safety profile, 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?

Two short, front-loaded sentences with zero filler: the resource and its identifiers come first, and the endpoint reference is a compact secondary note.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers what is needed to call it correctly. It could mention that it returns all categories without filtering, but the essential context is present.

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

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

There are zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already conveys.

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 (list) and resource (people categories), reinforced by concrete examples (New People, Church Members, Inactive) that make the resource unambiguous. It is clearly distinguishable from sibling list tools like list_people, list_groups, and list_financial_categories.

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 names the underlying Elvanto endpoint (people/categories/getAll), which implies lookup usage, but gives no explicit when-to-use guidance or exclusions relative to alternatives such as list_people or list_custom_fields. Usage is implied rather than stated.

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

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

The annotation supplies readOnlyHint=true, so safety is covered by structured data. The description adds real value beyond it by disclosing what the payload contains ('with their steps and admins'), which matters because there is no output schema to convey the response shape.

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

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

A single sentence, front-loaded with the verb and resource and followed by the disambiguating gloss and example. Every clause earns its place; the 'Elvanto: peopleFlows/getAll' tag is a compact API breadcrumb.

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, the description covers purpose, scope, and a rough sense of the returned data, which is what an agent needs. It stops short of noting pagination, result limits, or ordering, a minor gap given 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?

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline of 4 applies. There is nothing for the description to clarify or compensate for.

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 (people flows), then disambiguates with a plain-language gloss ('the church's follow-up pipelines') and a concrete example. It also distinguishes itself from the sibling list_people_flow_steps by noting it returns flows 'with their steps and admins' rather than steps alone.

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

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

Usage is implied: this is the entry point for enumerating follow-up pipelines, and the example makes the scenario concrete. However, it never states when to prefer this over elvanto_list_people_flow_steps or elvanto_list_people_flow_step_people, and gives no prerequisites or 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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds real behavioral value beyond the annotation: 'Not paginated' (a meaningful negative constraint for a list tool) plus a preview of the returned fields, which annotations do not convey.

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 tightly-packed sentence that front-loads the core action, followed by one short caveat and the API path reference. Every element earns its place; nothing is padded.

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

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

readOnly annotation, full schema coverage, and the description together give an agent enough to call this correctly, including the pagination caveat. It is near-complete for a straightforward read; the lack of an output schema is not a gap since return fields are previewed.

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 step_id, status, and assigned. The description's mention of 'status' and 'assigned admin' loosely maps to two parameters but adds no syntax or format detail beyond the schema; 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?

Clear specific verb (List) and resource (people currently in one people-flow step), with scope explicit ('one step') and return fields named (status, due date, assigned admin). It does not explicitly name a sibling to contrast with (e.g. list_people_flow_steps), so it falls just short of the top band.

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 example ('who still needs a follow-up call') implies a usage context but states no explicit when/when-not conditions and names no alternative tool. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds useful substance beyond that by naming the returned content (descriptions, instructions, due rules, admins), which partially compensates for the missing output schema, but it says nothing about pagination, ordering, or what happens for an unknown flow_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 sentences, front-loaded with the operation and then the returned fields. The trailing API reference ('Elvanto: peopleFlows/steps/getAll') is minor overhead but aids traceability; nothing is padded.

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

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

With no output schema, the description's enumeration of returned fields is what makes the definition usable. For a one-parameter read tool with a readOnly annotation, the main gaps are pagination and error behavior, which are minor.

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

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

Schema description coverage is 100% for the single required parameter, so the schema already defines flow_id as the people flow's id. The description adds no format, sourcing, or validation detail beyond that, making the baseline 3 appropriate here.

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: it lists the steps belonging to a single people flow, keyed by flow_id. This distinguishes it reasonably well from elvanto_list_people_flows (the flows themselves) and elvanto_list_people_flow_step_people (people within a step), though it never names those siblings explicitly.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling tools it could be confused with. The required flow_id is the only implied context; an agent must infer that this is the drill-down from list_people_flows.

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

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

The readOnlyHint annotation already covers the safety profile, so the description's remaining job is added context; it usefully discloses the default time window (upcoming unless changed) but says nothing about pagination behavior or result size. That default-scope note is genuine value, but the disclosure is thin overall.

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, default scope front-loaded, use cases second, API endpoint last. No filler, no repetition of schema content in bulk.

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 is the right place to frame return usage, and it does so via the question/field mapping; annotations cover read-only safety. The only meaningful gap is any note on paging through large result sets, which is left entirely 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 description coverage is 100%, so the baseline is 3. The description's gloss on fields (volunteers = the roster, plans = order of service) largely restates the schema enum descriptions and adds no syntax or interaction detail beyond it.

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

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

States a specific verb+resource ('List services') and clarifies the default scope ('upcoming by default'), so an agent knows exactly what comes back. It does not name or distinguish itself from sibling elvanto_get_service, so it falls short of the 5 bar for 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 triggering questions ('who is serving Sunday?', 'what are we singing?') and ties them to specific fields to request, which is clear when-to-use context. It offers no exclusions or pointer to get_service for a single service, so it stops short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing what the payload contains (sequence, BPM, keys, lyrics, chord chart) and that the chord chart can optionally be transposed, which the annotations do not convey.

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 names the tool's output fields, with the API endpoint appended as a compact reference. No wasted 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?

For a read-only list tool with no output schema, the description adequately previews the returned fields and the transposition capability. It omits pagination specifics, but those are fully covered in the schema, leaving only a minor gap.

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

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

Schema description coverage is 100%, so page, page_size, files, song_id and chord_chart_key are all documented in the schema. The description's mention of transposition echoes chord_chart_key but adds no syntax or format detail 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 (List) and resource (arrangements of one song) and enumerates the returned content (sequence, BPM, keys, lyrics, chord chart). Clearly distinguishable from the sibling elvanto_list_songs, which lists songs rather than their arrangements.

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 the correct workflow by noting song_id comes from elvanto_list_songs, giving the agent context for when this tool applies. It does not state exclusions or explicitly contrast with alternatives, but for a narrow read tool the context 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, so the safety profile is covered. The description adds useful context about what is returned (CCLI number, categories, locations), which matters since there is no output schema, but it omits pagination behavior and the fact that songs/getAll may paginate across the library.

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 covering purpose, search fields, and return contents, followed by a short API mapping. Efficient with no filler, though the 'Elvanto: songs/getAll' reference adds little 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?

For a 6-parameter, all-optional read tool with no output schema, the description adequately covers what the tool does and roughly what it returns. It is close to complete; minor gaps are the absence of pagination notes and sibling differentiation.

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 six parameters (page, files, title, artist, lyrics, page_size) are already documented in the schema. The description restates title/artist/lyrics filtering but adds no format or syntax 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 (list/search) and resource (song library), and enumerates the searchable fields (title, artist, lyrics) plus returned attributes (CCLI number, categories, locations). It is clearly a song-listing tool, though it doesn't explicitly differentiate itself from the sibling elvanto_list_song_arrangements.

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 'List or search the song library' implies the tool's use case for finding songs, but no when-to-use guidance, prerequisites, or named alternatives (e.g., list_song_arrangements) are given. Usage is inferable from the description but not explicitly scoped.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it with a server-level guarantee ('this server never writes financial records'), which is stronger than the per-tool hint. It also discloses the returned fields (donor, date, method, batch, per-fund amounts), though it says nothing about pagination behavior beyond the schema.

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

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

Front-loaded, single-sentence purpose followed by a short safety statement and the upstream API path; no filler or redundancy. Every 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 compensates by listing the return fields, and it covers scope, the optional fund filter, safety, and API provenance for a 5-parameter tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the (fund) mapping for category_id and pagination defaults. The description's 'optionally for one fund' and 'per-fund amounts' largely restate that, so it adds little beyond the schema and 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 and resource ('List giving transactions') plus its scope (between two dates, optionally one fund). An agent can distinguish it from sibling listing tools such as elvanto_list_financial_categories 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?

Clearly conveys the required date-range context and that the fund filter is optional, which tells the agent when to supply category_id. It does not name alternatives or exclusions, but no sibling tool covers transactions, so there is little risk of misrouting.

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 readOnlyHint=true, so the description carries the rest and does add real context: date fields are matched as on-or-after with an explicit UTC format, and the archived/contact/deceased keys are mutually exclusive. That is meaningful operational behavior beyond the annotation. It omits rate limits and any note on result volume/pagination behavior.

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

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

Front-loaded with the two examples before the long key enumeration, then the exclusion rule, then the API endpoint mapping. Dense but every clause carries information an agent needs to build a valid search payload.

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 nested, free-form search tool with no output schema, the description supplies the key vocabulary, date semantics, and mutual-exclusion rule, and pagination is documented in the schema. The remaining gap is that it never indicates which fields come back by default versus needing the 'fields' parameter, which matters 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 coverage is 100% so the baseline is 3, but the 'search' object is a free-form map whose allowed keys the schema cannot express, and the description enumerates all searchable keys plus the custom_<field id> convention and the on-or-after date semantics. That is substantive meaning added on top of the schema.

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

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

States a concrete verb+resource ('Find people matching field values') and immediately grounds it with two literal example payloads, so the agent knows exactly what input shape is expected. It does not, however, contrast itself with the sibling elvanto_list_people or elvanto_get_person, which is the only thing keeping this from a 5.

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

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

The description gives one genuine usage constraint ('Use only one of archived / contact / deceased at a time'), which prevents malformed calls. But it never says when to reach for this tool instead of elvanto_list_people or elvanto_get_person, so routing between siblings is left 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 declare destructiveHint=true, and the description adds the crucial mitigation that this is a partial update where untouched fields are preserved, plus the credential restrictions. That is real behavioral context beyond the annotation, though it does not cover response behavior or failure modes.

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 capability, then the partial-update rule, then the hard limit. Every sentence carries information and nothing is repeated from the schema.

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 mutation tool with no output schema, the description covers scope, partial-update semantics, and prohibited fields, which is enough to invoke it correctly. It leaves out what the response contains and whether special permissions are needed, minor gaps given the absence of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3; the description earns a bump by grouping the 14 parameters into navigable buckets and independently flagging the username/password/login prohibition that the schema only partially mirrors via the access_permissions note.

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 ('Edit an existing person's details') and enumerates the editable domains (name, contact info, category, flags, family, extra fields). This cleanly separates it from elvanto_create_person and elvanto_get_person 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?

Gives clear operating context ('Only the fields you pass change') and explicit exclusions ('Cannot touch username, password or login status'), which tells the agent both how to call it and where its authority ends. It stops short of naming sibling alternatives or stating permission prerequisites, so it is not quite a 5.

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