Elvanto MCP by usefulapi

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

Annotations provide destructiveHint=true, which signals a mutating operation. The description adds that a step admin can optionally be assigned, but does not clarify what side effects occur (e.g. notifications, replacement if the person is already in the step) or permission requirements. It adds little beyond the annotations.

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

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

One compact sentence plus the API reference. It is front-loaded with the core action and includes the example parenthetically. The API path is somewhat redundant but not distracting.

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

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

For a mutation tool with only destructiveHint and no output schema, the description is minimally adequate. It covers the core operation and optional admin assignment, but omits behavioral details like idempotency, error cases (invalid step_id, duplicate membership), or permissions, leaving gaps that could matter to an agent.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema. The description mentions 'optionally assigning a step admin', which corresponds to the assign_to parameter, but adds no syntax or format details beyond the schema. 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 ('Put a person into') and resource ('people-flow step'), with a concrete example ('start a new guest's follow-up'). It's clear what the tool does, though it doesn't explicitly contrast with the sibling elvanto_add_person_to_group, so it falls short of the 5-level 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?

The example ('e.g. start a new guest's follow-up') implies the usage context, but there are no explicit when/when-not statements or named alternatives. An agent gets a hint but no routing guidance.

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

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

Annotations only declare destructiveHint=true. The description adds meaningful context beyond that: it discloses the reversibility path ('Undoable by removing them from the group') and the backing endpoint (groups/addPerson), which helps the agent understand the mutation's impact.

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 concise sentences with the core action front-loaded, plus a compact endpoint reference. No padding, though the 'Elvanto: groups/addPerson' clause is metadata of marginal value 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?

For a simple 3-parameter mutation with full schema coverage and destructiveHint set, the description covers purpose, optional role, and reversibility. An agent has what it needs to call it correctly without 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 coverage is 100%, so the schema already documents group_id, person_id, and the position enum. The description restates the position options but adds no syntax or format beyond what the schema provides. 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 a specific verb and resource ('Add a person to a group') and names the optional role distinction. It does not explicitly contrast with siblings like elvanto_add_person_to_flow_step, but the resource is unambiguous enough to distinguish 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?

It clarifies that the position parameter is optional (omit for a regular member) and mentions undo, but gives no explicit when-to-use vs alternatives or prerequisites. 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 destructiveHint annotation already tells the agent this is a mutating write, lowering the bar. The description adds useful context with "Times are 24-hour GMT" and the draft/unpublished staging semantics. It stays silent on side effects an agent would care about, such as whether invites are dispatched or what permissions/API scope are needed.

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 with the purpose front-loaded, followed by format and staging guidance. The trailing "Elvanto: calendar/events/create" API path is minor redundancy but the text is otherwise dense and waste-free.

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 with no output schema and only a destructiveHint annotation, the description is thin: it never flags the required set, the repeat_frequency dependency for daily/monthly/yearly repeats, or what a successful call returns. The 100% schema coverage compensates for most of the per-parameter gap, leaving this merely adequate.

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 19 parameters are documented in the schema itself, making 3 the baseline. The description only restates the GMT time format and the repeating option, adding essentially nothing beyond what the 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?

States a specific verb and resource ("Create an event on a calendar") and adds the repeat capability, so an agent immediately knows this is the write counterpart to elvanto_list_calendar_events. It does not explicitly name the sibling, but the create/list split is unambiguous from the verb 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?

Gives one concrete usage hint — use status "draft" to stage an event unpublished — which is genuine operational guidance. Beyond that there is no when-to-use vs. alternatives framing, no prerequisites (e.g. needing a calendar_id from elvanto_list_calendars), and no exclusions.

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

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

Annotations only supply destructiveHint=true, which says little about a create operation, so the description carries useful extra weight: it discloses that the call returns a new person id and family id and that no login is created — a non-obvious side effect. It still omits permission requirements, duplicate-person handling, and failure behavior, so it is not fully transparent.

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

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

Three short sentences, all front-loaded: purpose, return shape, and a key negative behavior. No filler, no repetition of schema content.

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

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

For a 13-parameter mutation tool with no output schema, the description covers purpose, return values, and the no-login caveat well, and the schema fully documents parameters. It could still say more about authorization, duplicate detection, and family_id interactions, which are the main residual gaps.

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

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

Schema description coverage is 100%, so the schema already explains all 13 parameters, including the fields object with its *_replace / *_remove variants and the access_permissions refusal. The description adds no parameter-level guidance of its own, so the 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+resource ('Add a new person to the church database'), gives a concrete use case (first-time guest), and disambiguates from siblings like elvanto_update_person and elvanto_add_person_to_group. It also names the underlying API endpoint (people/create), which pins the semantics precisely.

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 'first-time guest' example implies a usage context, but there is no explicit when-to-use vs. when-not, and no mention of the natural alternatives (update_person for existing people, add_person_to_group / add_person_to_flow_step for post-creation placement). Preconditions such as required permissions or duplicate handling are left implicit.

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 by structured data. The description adds useful context that members can be pulled in via fields=["people"], but says nothing about the shape of the response or whether unfound ids error out. With annotations carrying the safety burden, 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 sentences with the core operation front-loaded and the optional-fields hint immediately after. No padding or redundant restatement of the tool name.

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

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

For a simple read-only single-resource fetch with full schema coverage and readOnlyHint set, the description is nearly sufficient. The only gap is that there is no output schema, so a one-line hint about the returned group shape would close the loop, though the low complexity makes this 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%, so both parameters are already documented in the schema, making 3 the baseline. The description's note that fields=["people"] returns members largely restates the schema's 'people (members and their position)' entry, adding little new meaning.

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

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

States a specific verb and resource ('Fetch one group by id') and the singular scope distinguishes it implicitly from the list_groups sibling. It does not name an alternative tool explicitly, but an agent can identify the operation unambiguously.

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: use it when you need a single group rather than a list. There is no explicit when-to-use guidance, no mention of prerequisites such as needing a valid group id, and no exclusion rules pointing at sibling tools.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is lighter. It adds the useful detail that extra fields are opt-in, but says nothing about behavior when the id is invalid, permission requirements, or return 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?

One tight sentence with the primary action and optional fields front-loaded, followed by a short API-path note. No wasted words, though the endpoint reference is marginal value 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 2-param read tool with annotations covering safety, the definition is mostly adequate, but with no output schema the description gives no hint of the returned person shape or which fields come back when 'fields' is omitted.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema, and the description's short field examples add no meaning beyond the schema's much longer list. Baseline 3 applies when the schema does the work.

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) and resource (one person) scoped by id, which inherently separates it from the list/search siblings. The added API reference (people/getInfo) reinforces intent, so an agent can select it without inspecting 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?

The id-scoped phrasing implies you use this when you already have a person id, but no alternative is named (e.g. elvanto_search_people or elvanto_list_people for discovery). Usage is inferable rather than stated, so it lands at minimum-viable.

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 the safety profile, so the bar is lower. The description adds that detail is 'optional' (i.e., unspecified fields are omitted, changing the response shape), which is useful behavioral context, but it says nothing about permissions, error behavior, or rate limits.

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 action and resource, followed by the field list and the API endpoint. No redundant or filler text.

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 lookup with a fully documented schema and no output schema, the description conveys enough: it names the id-based lookup, the optional field set, and the response contents. Only the absence of guidance on when to prefer this over sibling list/search tools keeps it below complete.

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

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

Schema description coverage is 100%, so the schema already documents id and every enum value of fields, including the glosses for plans and volunteers. The description's restatement of those fields adds marginal value 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 (Fetch) and resource (one service by id) and enumerates the payload it returns: times, plan, volunteers, songs, files, notes. The singular 'by id' scope clearly distinguishes it from the sibling elvanto_list_services.

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

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

Usage is only implied: fetch a single service when you already have its id. There is no explicit when-to-use or when-not-to-use guidance and no routing to siblings such as elvanto_list_services for browse-style lookups.

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 carried by structured data. The description adds useful context about the services pseudo-calendar and the date-bounded scope, but says nothing about paging behavior, result caps, or auth requirements despite page/page_size existing. Adequate, not rich.

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

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

A single sentence front-loads the core action and date scope, with the calendar option and services tip attached; the endpoint reference is short metadata. No filler or redundant restatement of the parameter list.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers the essential calling contract. It could still note paging defaults or how to obtain calendar ids (likely via list_calendars), which would make it self-sufficient for an agent planning a multi-step 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 date format, paging bounds, and the fields/calendar params. The description only reinforces the calendar filtering idea and the calendar-id alternative, which the schema already states. Baseline 3 is correct 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 ("List calendar events") plus scope ("between two dates, optionally for specific calendars"). This clearly separates it from elvanto_create_calendar_event and elvanto_list_calendars without needing to open either schema, and the Elvanto endpoint reference pins the underlying API call.

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 real usage context: a required date range and the option to narrow by calendar, including the non-obvious trick of passing "services" as a calendar. It stops short of naming when NOT to use it or pointing to a sibling (e.g. list_calendars to discover calendar ids), 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 readOnlyHint=true, so the safety profile is covered. The description adds that ids are returned, which is mildly useful, but says nothing about pagination, filtering, or result ordering for a list operation.

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

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

Two short sentences, front-loaded with the purpose. The trailing 'Elvanto: calendar/getAll' is API-mapping metadata that adds little for an agent but costs almost no space.

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

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

For a simple, zero-parameter read tool with no output schema, the description covers what the tool does and what it returns (calendars with ids). It is nearly complete, missing only a hint about result shape or volume.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-param tool is 4. Nothing in the description conflicts with the empty 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 (list the church's calendars) and adds the useful detail that ids are returned. It does not explicitly differentiate from nearby siblings like elvanto_list_calendar_events, though the resource noun makes the distinction inferable.

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 or when-not-to-use guidance. The description never states, for example, that this is the tool to call first to obtain calendar ids for filtering elvanto_list_calendar_events.

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 meaningful behavior beyond that by disclosing the shape of the result (id, name, type, allowed values) and the ID-mangling convention, which matters because there is no output schema.

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

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

Three short sentences with no filler: what it lists, what it returns, how to use the result, and the API endpoint. The most actionable content (the id convention) is front-loaded.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers purpose, return fields, and downstream usage. An agent has everything needed to call it and interpret the result.

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's mention of custom_<id> is about downstream usage rather than an input, but it is consistent with the empty schema and leaves no ambiguity about inputs.

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

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

States a specific verb and resource ('List the church's custom person fields') and even enumerates the returned attributes (id, name, type, allowed values). This clearly separates it from siblings like elvanto_list_people or elvanto_list_people_categories, which list different entities.

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?

Tells the agent exactly how the output is consumed: 'Use the id as custom_<id> in fields / search.' That is a concrete when/why-this-tool cue. It stops short of naming an alternative tool or an exclusion condition, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description still adds real behavioral value by disclosing the shape of the returned data (records carry ids) and decoding the status field (1 = active, 0 = archived), which no other structured field provides.

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 clauses with zero filler; the core purpose leads and the status-code decoding plus endpoint follow immediately.

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 small, read-only, zero-required-parameter list tool with full schema coverage and annotations, this covers purpose, returned identifiers, status semantics and the upstream endpoint. It lacks only pagination guidance, which the schema already supplies.

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% - both page and page_size are fully documented in the schema, including defaults. The description adds nothing about pagination, 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 (giving / chart-of-accounts categories, i.e. funds) and even pins the upstream endpoint (financial/categories/getAll). This is clearly distinguishable from siblings like elvanto_list_transactions or elvanto_list_people_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?

Usage is implied by the name and the resource described - an agent can infer this returns all category/fund records. However, the description offers no explicit when-to-use, no mention of a filtered alternative, and no prerequisites (e.g. auth scope) for calling it.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds substantive context by disclosing what the response contains (meeting day, time, place, frequency) and how to enrich it, plus the underlying endpoint groups/getAll. It omits pagination behavior, but that is documented in the schema.

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

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

Two compact clauses, tightly front-loaded with the resource and its returned data, with the expansion tip and endpoint reference appended without waste.

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

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

With no output schema, the description correctly compensates by summarizing the fields returned and how to expand them, which is the key missing structured information. A brief note on default result size/pagination would complete it, but nothing essential is absent for a read-only list tool.

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

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

Schema description coverage is 100%, so all five parameters (page, page_size, suspended, category_id, fields) are already fully documented. The description adds only a mild usage note about fields=["people"], not syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List small groups / ministries') and enumerates the returned attributes (meeting day, time, place, frequency), which is more than a restatement of the name. It does not explicitly distinguish itself from the sibling elvanto_get_group, though the list-vs-get distinction is inferable.

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 actionable hint — add fields=["people"] to include members and leaders — but gives no when-to-use/when-not guidance relative to elvanto_get_group or elvanto_list_people. Usage is implied by the domain 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, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: it is paginated and the response carries page, per_page, total, and it maps to the underlying Elvanto endpoint people/getAll. No contradictions with the read-only annotation.

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: capability and filters first, then pagination semantics, then the upstream API mapping. Almost every clause carries information an agent can act on, with no padding.

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 correctly compensates by disclosing the pagination envelope (page, per_page, total), which is the main thing an agent needs to iterate. It stops short of describing what a person record contains, though the fields parameter and its cross-references offset that 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% and each parameter carries a detailed description (including defaults, enum meanings, and a cross-reference to elvanto_list_custom_fields for custom fields), so the schema does the heavy lifting. The description only restates the filter categories at a high level, adding nothing beyond the schema — the baseline 3 when coverage is complete.

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 filter dimensions it supports, so the agent knows it enumerates rather than fetches a single person. It does not differentiate itself from the close sibling elvanto_search_people, leaving the boundary between "list" and "search" to inference.

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 naming the filters (category, suspended/contact/archived), which suggests bulk enumeration of a category of people. There is no explicit when-to-use or when-not-to-use guidance, and no mention of when to prefer elvanto_search_people or elvanto_get_person instead.

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 tells the agent this is a safe read, so the description's main added value is the API endpoint reference and the example category values. It does not mention pagination, result limits, or whether the category list is workspace-scoped, but with annotations carrying the safety profile this is adequate.

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 what the tool returns and followed by the endpoint reference. Nothing is wasted or 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?

For a no-param, read-only list tool with annotations covering safety, the description supplies the return shape (categories with ids) and the underlying endpoint. Only the absence of any adjacent-tool routing keeps it short of fully complete.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description confirms the call needs no filtering input, matching the empty 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 (list people categories) and even gives concrete examples (New People, Church Members, Inactive), so the agent knows exactly what comes back. It does not differentiate itself from nearby siblings like elvanto_list_people or elvanto_list_custom_fields, but the purpose itself 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?

There is no when-to-use guidance at all: no named alternatives, no condition under which an agent would pick this over elvanto_list_people or elvanto_list_groups. The examples hint at scope but do not route the agent.

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 and the description isn't obliged to restate it. It does add non-obvious behavioral value by disclosing that each flow is returned with its steps and admins, telling the agent the response is an aggregated/expanded listing rather than a flat list of names. It says nothing about pagination or whether all flows are returned in one call.

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 operation and resource, using parentheticals to define the domain term and enumerate the return shape without padding. The trailing 'Elvanto: peopleFlows/getAll' mapping is a compact, useful trace to the underlying API call.

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 purpose, domain definition, and return content, and annotations carry the safety profile. The only residual gap is operational detail (pagination, ordering, or result-size limits), which an agent managing large churches might need.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there is no parameter semantics for the description to add or omit. Nothing in the text conflicts with the empty 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 gives a specific verb (List) and resource (people flows), then defines the domain term with a concrete example ('the church's follow-up pipelines (e.g. First Time Guest Follow Up)'), so an agent unfamiliar with Elvanto terminology still knows what entity this returns. It also distinguishes itself from adjacent siblings like elvanto_list_people_flow_steps and elvanto_list_people_flow_step_people by stating this returns flows with their steps and admins.

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?

Listing is the obviously implied usage, and the mention of steps/admins hints at when this beats the more granular flow-step tools, but the description never states it explicitly or names alternatives. With three closely related people-flow siblings in the toolset, an explicit 'use this to enumerate flows; use X for steps within a flow' would have removed 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 readOnlyHint=true, so the safety profile is covered, but the description adds genuinely non-derivable behavior: 'Not paginated' tells the agent it gets one complete set rather than a page it must iterate. It also names the upstream endpoint (peopleFlows/steps/people), useful for tracing. It does not state ordering or result-size limits, so 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 fragments with the core purpose front-loaded and nothing padded. The trailing 'Elvanto: peopleFlows/steps/people' is borderline redundant with the name, keeping it just shy of a 5.

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

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

With no output schema, the description usefully compensates by naming the fields returned (status, due date, assigned admin) and by flagging non-pagination. All three parameters are schema-documented. Only minor gaps remain, such as result ordering, for a simple read/list tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains step_id, status enum values and the assigned/unassigned convention. The description's mention of 'status' and 'assigned admin' roughly mirrors those params without adding format or default detail, so it does not exceed the schema.

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

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

States a specific verb and resource ('List the people currently in one people-flow step') and immediately enumerates what is returned (status, due date, assigned admin). This clearly separates it from the sibling elvanto_list_people_flow_steps, which lists the steps themselves rather than the people inside one.

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

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

Gives a concrete use scenario ('e.g. who still needs a follow-up call'), which tells the agent when this tool is the right reach. It stops short of naming alternatives or exclusions (e.g. 'use elvanto_list_people_flow_steps to find step_id first'), so it is clear context rather than full routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lowered. The description adds useful context about what each step record carries (descriptions, due rules, admins), but says nothing about pagination, ordering, or auth requirements beyond the read-only hint.

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

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

Two tight sentences, front-loaded with the action and scope. The endpoint string ('peopleFlows/steps/getAll') is compact and useful for API mapping without 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?

With no output schema, the description compensates by naming the returned fields, which is the key missing piece for an agent. For a single-parameter read tool this is nearly complete, lacking only return-shape details like pagination or ordering.

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

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

Schema coverage is 100% with a single well-documented flow_id parameter, so the schema does the heavy lifting. The description only implies that 'one people flow' scopes the lookup; it adds no format or semantics beyond what the schema already states. 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 (steps of one people flow) and enumerates the returned content (descriptions, instructions, due rules, admins). It is distinguishable from siblings like elvanto_list_people_flows and elvanto_list_people_flow_step_people by scope, though it does not explicitly name those 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?

Usage is implied: you fetch the steps belonging to a single flow identified by flow_id. There is no explicit when-to-use, when-not, or pointer to an alternative tool for a different granularity of flow data, so guidance remains at the minimum-viable level.

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, and the schema documents the past-services and pagination behavior. The description reinforces the 'upcoming by default' default and hints that field expansion increases payload scope, but adds nothing on auth, rate limits, or result shape. Some added context, not rich.

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

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

Two short sentences, front-loaded with the core behavior and default scope, with the field-expansion guidance second. The trailing 'Elvanto: services/getAll' is a minor API mapping note that earns its place but is not description-critical.

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 8 optional parameters and full schema documentation, the description covers default scope, field expansion, and intent. Pagination and return shape are handled by the schema and the absence of an output schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so every parameter including the fields enum values (volunteers = roster, plans = order of service, songs) is already documented in the schema. The description's restatement is helpful framing but adds no syntax or format detail beyond it; 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 services') plus the default scope ('upcoming by default'), which is real information an agent needs. It does not name or contrast with the obvious sibling elvanto_get_service, so it stops short of full sibling differentiation.

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

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

Gives concrete usage framing: add volunteers/plans/songs 'to answer "who is serving Sunday?" or "what are we singing?"', which tells the agent when to expand fields. It offers no when-not guidance, such as when to call elvanto_get_service for a single service instead.

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 establishes the safety profile. The description adds useful behavioral context by specifying what is returned (sequence, BPM, keys, lyrics, chord chart) and noting that chord charts can optionally be transposed, though it does not discuss pagination behavior beyond what the schema already provides.

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

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

The description is a single efficient sentence that front-loads the core purpose and returned data, followed by a brief endpoint reference. No unnecessary text is included.

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 helpfully lists the main returned fields so the agent understands the return content. All parameters are documented in the schema, and the read-only nature is covered by annotations, making this complete enough 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 description coverage is 100%, so the schema already documents all five parameters. The description adds only marginal meaning, such as noting optional chord chart transposition and the source of song_id, both of which are already present in the schema descriptions. 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?

The description states a specific verb and resource: listing arrangements of a single song. It also enumerates the key returned fields (sequence, BPM, keys, lyrics, chord chart), distinguishing this clearly from sibling list tools such as elvanto_list_songs.

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

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

The description implies the tool is used when arrangements for one song are needed, and it points to elvanto_list_songs as the source of the required song_id. It does not explicitly state when not to use this tool or name competing alternatives, but the context is clear for this nested-resource list operation.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds that results carry CCLI number, categories and locations, which is useful output context, but it says nothing about pagination limits, result caps, or required auth beyond what the annotations and schema already cover.

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 capability front-loaded and the API mapping ("Elvanto: songs/getAll") trailing. Nothing is wasted, though the endpoint string is marginally less useful to an agent than a scoping or pagination hint 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?

For a read-only, fully documented 6-parameter list tool with no output schema, the description covers purpose, filter dimensions, and the shape of returned data. Only pagination behavior (defaults, caps, how to page through results) is left unaddressed, which is a minor gap.

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

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

Schema description coverage is 100%, so title, artist, lyrics, page, page_size and files are all documented in the schema itself. The description restates title/artist/lyrics filtering but adds no matching semantics, defaults, or format details beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("List or search the song library") and names the retrievable fields (CCLI number, categories, locations), so an agent knows exactly what it returns. It does not explicitly distinguish itself from elvanto_list_song_arrangements, which is a closely related sibling, 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?

"List or search ... by title, artist or lyrics" implies when the tool is appropriate (any song-library lookup with optional filters), but there is no explicit when-not guidance or reference to alternatives such as elvanto_list_song_arrangements. Usage is inferable but not 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 description restates the read-only posture already carried by readOnlyHint=true, adding only the server-wide guarantee that no financial records are written. Genuinely useful additions are the upstream endpoint mapping (financial/transactions/getAll) and the field list, but pagination behavior for page/page_size is left entirely to 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 with purpose, then the read-only assurance and API mapping as compact fragments. Roughly three clauses, none wasted, though the return-field enumeration slightly lengthens the first sentence.

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

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

With no output schema, naming donor, date, method, batch and per-fund amounts usefully previews the return payload, and the annotations plus endpoint mapping round out the picture. Pagination semantics exist only in the schema, which is acceptable but keeps this from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description maps start/end to 'between two dates' and category_id to 'optionally for one fund', but adds no format or semantics beyond what the schema already documents for page and page_size.

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 (giving transactions), plus the scope (between two dates, optionally one fund) and the fields returned. It does not explicitly name a sibling alternative such as elvanto_list_financial_categories, but the transaction-vs-fund distinction is inferable from the wording.

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 date range requirement and the optional fund filter imply when the tool applies, but there is no explicit when-to-use/when-not guidance or comparison to sibling list tools. The agent must infer that this is the reporting-style read path.

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?

Read-only safety is already covered by readOnlyHint=true. The description earns credit by adding behavior the annotation does not: UTC date format with on-or-after matching semantics, the mutually exclusive archived/contact/deceased constraint, and the underlying API path (people/search). Pagination behavior itself is left to 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?

The content is front-loaded with the core action and example before the key list, and nothing is wasted on filler. The long comma-separated key enumeration makes the second sentence dense and run-on, slightly reducing scanability.

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 search with a free-form nested search object and no output schema, the definition supplies the examples, key vocabulary, date semantics, and exclusion rule an agent needs to call it correctly. The only material omission is the relationship to elvanto_list_people and elvanto_get_person for disambiguation.

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?

Although schema coverage is nominally 100%, the required `search` object is free-form (additionalProperties with no key enumeration), so the schema alone does not tell an agent which keys are legal. The description supplies the entire searchable-key vocabulary, date formatting, and the custom_<field id> pattern, which is genuinely additive rather than redundant.

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 opens with a clear verb+resource ("Find people matching field values") and immediately grounds it with concrete example payloads, so an agent knows exactly what the tool returns. It stops short of naming a sibling such as elvanto_list_people to disambiguate when a plain listing should be used instead.

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

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

It gives one real operational rule not found in the schema ("Use only one of archived / contact / deceased at a time") plus match-semantics for dates. However, it never states when this search should be preferred over elvanto_list_people or elvanto_get_person, leaving sibling selection 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 only declare destructiveHint=true, so the description usefully adds that "Only the fields you pass change" (PATCH-style partial update semantics) and that username, password and login status are off-limits. It does not cover permissions, rate limits, or the return shape, but it adds real behavioral context beyond the destructive flag.

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 edit semantics front-loaded and zero filler. The prohibitions are stated as a single tight clause rather than a sprawling list.

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

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

For a 14-parameter mutation tool with a nested fields object and no output schema, the description covers the essential behavioral facts: partial-update semantics, the forbidden username/password fields, and the Elvanto endpoint. Return values are not described, but with no output schema that is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters including the nested fields object. The description only loosely groups them ("name, contact info, category, flags, family"), adding grouping value but no syntax or format detail beyond the schema — the correct baseline 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 ("Edit") and resource ("an existing person's details") and enumerates the editable field groups — name, contact info, category, flags, family, extra fields. The word "existing" cleanly separates it from the sibling create_person, so an agent can route without opening the schema.

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

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

Gives clear context for when to use it (editing an existing person) and states a scope limit (cannot touch username/password/login status), but it never names an alternative sibling such as create_person for new people or get_person for reads. The usage context is clear but the when-not-vs-sibling routing is left implicit.

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