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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false): it discloses that no duplicate check occurs, that writes require an account allowed to edit the tree, that writes run one at a time, and that locked/rate-limited writes return a retry delay. It also states the return payload (handle, Gramps ID, page) despite having 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?

Front-loaded with purpose and prerequisites, then prerequisites/alternatives in descending order of importance, with zero filler sentences. It is dense and long — arguably two or three clauses could be tightened — but nearly every clause carries operational 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?

Covers the full lifecycle an agent needs for a 9-parameter mutation tool with no output schema: prerequisite lookup, how to attach related notes/media, the required follow-up attach step, duplicate behavior, permissions, rate limiting, and failure semantics. Nothing material is left to inference.

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 still adds genuine meaning by explaining that a transcript belongs in noteHandles as a Transcript-type note and the scan in mediaHandles, including the deferred create_media attachTo path. It doesn't restate the region, date or attribute grammar in detail, deferring to the schema and input-guide, which is reasonable.

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 a citation') and immediately defines the concept: one specific spot in an existing source, with date, confidence, notes and media. It explicitly distinguishes itself from update_citation, create_records, and create_source, so an agent can route correctly without opening other schemas.

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

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

Gives explicit when-to-use, prerequisites ('The source must already exist'), post-conditions ('The citation supports nothing until it is attached'), and named alternatives for adjacent cases (update_citation for changes, create_records for multi-record transactions). It even routes to get_reference for argument formats.

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 a non-idempotent, non-destructive write, and the description goes well beyond them by disclosing the return payload (handle, Gramps ID, type), validation-before-save on bad type/date, sequential writes, edit-permission requirements, and rate-limit retry behavior. However, a large share of the text is domain modelling advice about eventRefs roles and date ranges rather than behavior of this call, so the behavioral disclosure, while above the annotated baseline, is diluted.

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 purpose is front-loaded, but the paragraph is long and mixes creation mechanics with genealogy modelling rules about Primary roles, birth/death pairing, and shared citations. Useful content, yet the agent must wade through domain lore to reach the operational facts about return values and rate limits.

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

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

With ten parameters, no output schema, and one required field, the description covers the return shape, failure modes, and attachment workflow adequately. The only gap is that the formats of every argument are deferred to get_reference(topic: "input-guide") rather than summarized inline.

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 exceeds it by explaining that a range like 1890-1900 means a single occurrence within that span versus 'from 1890 to 1900' for a duration, and that placeHandle requires an existing place. It also clarifies that citation/note/media/tag payloads belong to the shared event while participant-specific data belongs on eventRefs, which the schema alone does not convey.

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

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

Opens with a specific verb and resource — 'Create a standalone event' — and immediately enumerates the payload it carries (date, place, description, citations, notes, media). The word 'standalone' plus the later 'The event is linked to nobody yet' cleanly separates it from create_records and update_event.

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?

Explicit routing is given throughout: attach via update_person or update_family with eventRefs/linkMode add, find the place with search or create_place, modify with update_event, and use create_records for several interlinked new records. It even states the precondition exception (data that must be created atomically) that selects the alternative tool.

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

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

Beyond the annotations it discloses the atomicity rule (a missing member makes Gramps Web refuse the family and save nothing), the no-duplicate-check behaviour, write serialization, the edit-permission requirement, and rate-limit/lock failures with the wait before retrying. It also describes the return value and the follow-up update_family calls with linkMode add when refs were omitted.

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

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

Front-loaded with the core creation model and every sentence carries information, but it is delivered as one dense block with long compound sentences, which makes it harder to scan than a short set of grouped points. No filler sentences are present.

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

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

For an 11-parameter, all-optional mutation tool with no output schema, it covers prerequisites, atomicity, permissions, concurrency, duplicate policy, relationship-type conventions, return shape, and a pointer to get_reference for argument formats. An agent has what it needs to call it correctly and to recover from a refusal.

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 100%, the description adds real semantics the schema does not: relationshipType stays Unknown unless a source records the marriage, the Family role in eventRefs is what makes the family appear among the event's participants, childRefs order is preserved so children should be listed by birth, and citations/notes/tags belong to the family and not its members. The plain handle-list parameters are left to the schema, which 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?

Opens with a specific verb and resource plus the shape of the record: "Create a family: a couple (father and mother, each optional) with their relationship type, children and family events." It also distinguishes itself from siblings by naming create_records and update_family and the conditions that select 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 gives explicit routing rules: look at the parents' families first because duplicates are not checked, use update_family to change an existing family, use create_records for several new interlinked records, and add children via childRefs rather than parentFamilyHandles. Each alternative comes with the condition that selects 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?

Beyond the annotations (readOnly=false, idempotent=true, destructive=false) the description discloses the upload directory restriction and lookup order, content-based format detection, MD5 dedup semantics (returns the existing record with action existing and applies only attachTo), pre-upload validation of dates and attachTo, serialized writes, edit permission requirement, and rate-limit retry delay. That is substantially more than the structured fields provide.

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 dense paragraph, front-loaded with what the tool does and the upload constraint, with each sentence carrying real content. It is long, but the length is justified by the number of non-obvious behaviors; minor tightening would help readability.

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 9-parameter write tool with no output schema, the description covers return values (handle, Gramps ID, action existing), idempotency, failure modes, permissions, and cross-tool routing. Nothing an agent needs to call it correctly appears to be 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 goes further by explaining the relative-filePath lookup across upload dirs, the distinction between citationHandles (provenance of the file) and attachTo (where it is shown), and the duplicate-record region override behavior. Region semantics are also restated, though much of that already lives in 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?

Opens with a specific verb and resource ("Upload a photo, document scan or PDF ... as a new media record") and names the attach targets (people, families, events, places, sources, citations). An agent can distinguish it immediately from create_records and create_note, which it explicitly rules out.

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

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

Explicitly states this is the only tool that uploads a file, that create_records takes no media and a transcription belongs in create_note, and routes follow-up work to update_media and read_media. When-to-use and when-not-to-use are both covered.

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

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

Beyond the annotations, it discloses that the note is created unattached, that an unknown type is rejected before anything is saved, that writes are serialized one at a time, that a Gramps Web account with edit permission on the tree is required, and that locked/rate-limited writes return a retry delay. It also states the return payload (handle, Gramps ID, type) despite 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?

Purpose and return value are front-loaded, then linking workflow, then alternatives and write constraints. Every sentence carries information, though the multi-clause final sentence about locking and rate limits is dense and could be split.

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, yet the description names what is returned and how to use the returned handle. Combined with the attachment workflow, type validation, and concurrency/permission constraints, an agent has everything needed to call it correctly and follow up.

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 description adds real semantics on top: the noteType value to use for cited-record transcripts, the validation behavior for unknown types, and the fact that the note is not auto-linked to anything. It does not elaborate on format, isPrivate or tagHandles beyond the schema, keeping it short of a 5.

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 a free-text note') plus the content kinds it covers (research notes, transcriptions, comments) and the type parameter. It is clearly separable from update_note (change) and create_records (multi-record transactions), both of which are named.

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

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

Explicitly routes: use update_note to change an existing note, use create_records when several new records link to each other in one transaction, and use type Transcript for the transcript of a cited record. It also states the non-obvious follow-up (attach the returned handle to noteHandles on the owning object via its update tool with linkMode add).

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

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

Beyond the annotations (write, non-idempotent, non-destructive), the description discloses the duplicate-detection algorithm in detail — name-form folding across scripts and genders, two-year birth window, parent-child fallback, the "refused" action with candidate duplicates, and post-create namesake listing. It also discloses serialized writes, the edit-permission requirement, and rate-limit/lock backoff behavior. Slightly short of 5 only because the return payload is only summarized as "handle, Gramps ID and name, with next steps" without shape detail.

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 purpose and duplicate-check summary are front-loaded, but the body is one very long undivided paragraph mixing duplicate policy, name semantics, event linkage, family linkage, batch alternative, write constraints and a format pointer. With 16 parameters some length is justified, yet the lack of sentence-level structure or bullet-like grouping makes it harder to scan than it needs to 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 16-parameter create tool with no output schema, the description covers return values (handle, Gramps ID, name, next steps), the duplicate refusal path and its recovery, cross-tool prerequisites for events and families, and points to get_reference for argument grammars. Nothing an agent needs in order to call it correctly appears to be 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, but the description adds real meaning the schema does not: primaryName as usually the birth name with married names going to alternateNames, the rule that the first Primary-role Birth and Death become the person's vital events while other roles (Witness) are mere links, and the warning that familyHandles/parentFamilyHandles are one-directional. The worked name example further anchors the composite name object.

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

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

Opens with a specific verb and resource ("Create one person") and enumerates the aspects it accepts, then explicitly distinguishes itself from update_person, create_records, create_event and create_family. An agent can tell exactly what this tool does and what it does not do 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 explicit routing rules: add to an existing person with update_person, override the duplicate refusal with notDuplicateOf, create events first with create_event and pass eventRefs, and use create_records for several interlinked new records in one transaction. It also states the when-not case (a refused call stops creation) and the alternative for family linkage (create_family/update_family with fatherHandle/motherHandle/childRefs).

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 the generic mutation profile; the description adds the specific behaviours an agent cannot infer: no duplicate check, unknown type or unreadable date rejected before anything is saved, writes serialized one at a time, edit permission required, and locked/rate-limited writes returning a wait delay. It also describes the returned handle/Gramps ID and the follow-on placeHandle linkage to create_event/update_event.

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: purpose first, then usage, then behavioral constraints, then a routing pointer to get_reference for argument formats. It is long, but proportionate to a 14-parameter mutation tool; a few clauses (naming precedence, date-span rules) echo the schema and could have been left to it.

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 write tool with no output schema, the description covers purpose, prerequisites (account with edit rights), failure modes (validation rejection, lock/rate limit with retry delay), return payload, and next steps. Nothing an agent needs in order to call it safely 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 baseline is 3; the description still earns above baseline by stating cross-parameter relationships (name/nameLang/nameDate form the primary name, alternateNames is for historical or other-language names, an undated primary name hides dated alternates) and the ordering constraint on enclosedBy. Most individual format detail, however, is already in the schema, so the added value is relational rather than comprehensive.

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 a new place") and enumerates the substance being created: names, type, coordinates, enclosing places. It distinguishes itself from update_place and create_records by name, so the agent can separate the three create/update paths without opening a schema.

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

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

Explicit when-to-use rules: search first because no duplicate check exists, use update_place to modify, use create_records for several mutually-linking records in one transaction. It also gives sequencing guidance (build hierarchies top-down, create the county before its villages), which is real operational advice rather than filler.

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

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

Beyond the annotations, it discloses transaction atomicity ('either all are created or none'), undo via undo_change/get_recent_changes, the duplicate-refusal behavior with the notDuplicateOf escape hatch, the 50-record cap, pre-save validation with path-style error names ('people[1]'), per-record sequential writes, and account/rate-limit requirements. This is unusually rich behavioral context; the only minor gap is that return-value shape is hinted ('each record's handle and Gramps ID') but not fully detailed, which is acceptable given the volume of other disclosure.

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 verb and transaction semantics, and nearly every sentence carries needed information. It is a dense single paragraph, however, and the linking convention is explained at length; breaking it into shorter logical blocks would improve scannability without losing 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 an 8-parameter batch tool with no output schema, the description covers atomicity, limits, error semantics, duplicate handling, linking rules, prerequisites for media/tags, and authentication/rate-limit behavior. Nothing an agent needs to invoke it correctly appears to be 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 goes further by explaining the cross-record linking model holistically with concrete examples (a citation's sourceHandle "#src", a family's fatherHandle "#ivan"), and by clarifying that people join families only through families rather than familyHandles. That adds meaning beyond the per-field schema descriptions.

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 specific verb and resource set: 'Create many linked records in one call: repositories, places, sources, notes, citations, events, people and families.' It clearly distinguishes the batch tool from the sibling create_* tools and from update_* by framing this as the single-call multi-record creator.

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 explicitly states when not to use it ('Media and tags are not created here: create them first with create_media and create_tag') and when to use alternatives ('Links from existing records to new ones ... are made afterwards with update_* and linkMode "add"'). It also tells the agent to search first for non-person records because only people are duplicate-checked.

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

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

Goes well past the annotations (which only declare non-readonly, non-destructive, non-idempotent, closed-world): it discloses the absence of duplicate checking, that an unknown type is rejected before any write, that noteHandles/tagHandles link only existing objects and create nothing, serialized writes, required edit permission, and lock/rate-limit failure behavior including a retry delay.

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?

Purpose and return values are front-loaded, with constraints and alternatives following in a logical order. It is a dense single block covering a lot of ground, and a few clauses (e.g., restating that nothing else is created or changed) could be trimmed, but almost every sentence carries actionable 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?

With no output schema, the description supplies the return shape (handle, Gramps ID, name) plus next steps. For a 7-parameter mutation tool it also covers permissions, error/rejection behavior, rate limiting, and non-atomicity relative to create_records, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the schema already carries parameter meaning, but the description adds cross-tool semantics the schema cannot: where the call number lives (repositoryHandles on create_source/update_source) and that notes and tags must already exist. It also points at get_reference(topic: "types") for valid repoType values, adding a discovery path 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?

Opens with a specific verb and resource plus a definition of the domain object ('an archive, library, church, website or other holder of sources'), which disambiguates it from create_source, create_note, and create_records. It also states what is returned, so the agent knows the outcome shape without opening anything else.

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?

Explicit routing: check list_objects(objectType: "repositories") first to avoid duplicates, use update_repository for existing records, use create_records for multi-record batches, and link sources afterwards via repositoryHandles on create_source/update_source. Both when-to-use and when-not-to-use are named with concrete 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 give the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. Credit is due for disclosing that no duplicate check runs, that writes are serialized one at a time, that a locked or rate-limited write returns the delay to wait, and what the response contains (handle, Gramps ID, title, next steps).

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 definition is front-loaded and every paragraph carries distinct content. It is dense and long, though: the repositoryHandles and media-type material overlaps the schema's own text, and the closing pointer to get_reference(topic: "input-guide") partly duplicates the gramps://input-guide reference already inside 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 10-parameter mutation with no output schema, the description covers what an agent needs: what the record represents, how the free-text arguments map onto a reference, which handles must pre-exist, the return value, and the failure modes. Nothing essential to invoking it correctly is left out.

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 description adds real conceptual mapping beyond the field docs: title names the document, author is who made it, pubinfo is for published works, abbrev is the list title, and the archive shelf mark (fond/inventory/file) becomes the call number carried on repositoryHandles. It also disambiguates scope, noting that notes and media here describe the whole source while the scan of one entry belongs on the citation.

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 and then defines the resource itself ("a book, register, archive unit or website that facts come from"), which an agent cannot get from the name alone. It also names the sibling that handles the modify case (update_source) and the batch case (create_records), so the tool is distinguishable 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?

Explicit when-to-use and when-not: search first because no duplicate check is made, use update_source to change an existing source, use create_repository for repositories, use create_records when several interlinked records must be created atomically, and follow with create_citation. Prerequisites (edit-permitted Gramps Web account) are also 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 only cover readOnly/destructive/idempotent flags; the description adds substantial non-obvious behavior: no duplicate-name check, update_tag rejects colliding names, a new tag labels nothing until its handle is added to record tagHandles, writes are serialized, and edit permission plus locked/rate-limited failure with a retry delay is required.

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 return values, then constraints. Dense but nearly every sentence carries actionable information; the length is justified by the multi-step follow-up guidance, though it is on the longer side.

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 non-idempotent create tool with no output schema, the description covers return values, duplicate behavior, linking workflow, renaming path, concurrency, auth, and rate-limit handling – everything an agent needs to call and follow up correctly.

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

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

Schema coverage is 100% and each parameter (name, color, priority) is fully documented in the schema, so the description adds little beyond 'colored label'. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a tag') and immediately defines what a tag is with concrete examples, plus what the call returns (handle, Gramps ID, name). An agent can distinguish this from update_tag or list_objects without opening a schema.

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

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

Gives explicit routing: check list_objects(objectType: "tags") first for duplicates, use update_tag to rename/recolor, and use the record's create/update tool with linkMode add to actually attach the tag. It also states the precondition that nested filter rules find tags by name, so names must be distinct.

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

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

Goes well beyond the destructiveHint annotation by disclosing the referential-integrity guard, the exact block-and-list-backlinks-by-type failure mode, the client-side confirmation dialog, the declined/cancelled signals, and the success and not-found responses. An agent knows the failure paths before calling.

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 effect and undo path are front-loaded, then preconditions, then failure modes, then return values. Dense but nearly every clause carries distinct, actionable information; only the return-value sentence borders on over-detail for a tool with no output 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?

With no output schema, the description supplies the return payload (type, action: deleted, handle) and the not-found case, and covers the destructive-mutation risk profile fully. Nothing an agent needs to call this safely 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 schema already defines handle, objectType, and force. The description still adds genuine meaning for force by requiring a separate confirmation before using it, tying the parameter to an approval workflow rather than just its mechanic.

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?

"Delete one record" gives a specific verb, resource, and scope, distinguishing it from the update_* siblings that modify rather than remove records. It immediately links to the restore path (undo_change via get_recent_changes), which pins down its exact effect.

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?

Explicit preconditions are stated: only after the user confirms this exact record, and only after unlinking backlinks with the owners' update tools or passing force=true following a separate confirmation. It also tells the agent how to interpret declined/cancelled outcomes.

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

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

Beyond readOnlyHint/destructiveHint=false, it states 'Nothing changes', quantifies cost (reads every person up to 20000, 10-20s on a few-thousand-person tree), and explains the result ordering (possible duplicates first, then by birth proximity) and pagination. That is exactly the operational context annotations cannot carry.

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 purpose and cost are front-loaded and the closing routing sentences earn their place, but the middle is one sprawling sentence padded with redundant exemplification (six-plus gendered surname pairs, multiple transliteration edge cases). Fewer examples would convey the same rule.

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 scan tool with no output schema, the description covers what is compared, how results are ordered and paged, the performance ceiling, and the required follow-up workflow (verify, then merge). An agent has everything needed to call it and act on the output.

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 limit, offset, surname and personHandle are already fully documented, and the description adds little beyond 'numbered across pages'. The surname filter's spelling-tolerance is explained in the schema itself, so the description's long surname exposition is mostly duplicated rather than additive.

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 specific verb and resource ('Find people entered twice in the tree') and immediately defines the matching semantics: given name containment, surname spelling variants, gendered surname forms, birth/death date windows, and exclusion of spouses and ancestors. It is unmistakably distinct from search, list_objects, and the create_* siblings that reuse the same check.

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 explicit routing: use search to find a single name, compare a pair with get_object, and merge with merge_objects only after the user confirms. It also discloses that create_person and create_records run the same duplicate check, which tells the agent when this tool is redundant.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, and the description adds substantial context beyond them: bookmarks are tree-scoped and shared across users, are written only via Gramps Web/desktop and never through this server, may be empty, and are returned unpaged in a fixed type order with unreadable records surfaced as bare handles. That covers mutation expectations, emptiness, and result 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?

Four sentences, front-loaded with the core purpose, then behavior, then routing. Dense and mostly waste-free, though the type enumeration and ordering clause make it longer than strictly necessary for an agent that will see the actual response.

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, and the description compensates by specifying the return shape: grouped by type, one-line summaries with handles, fixed type ordering, tree bookmark order, and bare-handle fallback for unreadable records. For a zero-parameter read tool this is 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, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly does not invent any parameter discussion.

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 (bookmarked records in this tree) and enumerates the grouping types. It also explicitly names the sibling alternatives (search, list_objects, get_recent_changes), so an agent can distinguish it without opening any schema.

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

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

Gives an explicit positive trigger ('Use it to start from the records the tree's users marked') and three explicit routing rules away from it: name lookup -> search, single-type browse -> list_objects, recent edits -> get_recent_changes. Nothing 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 already declare a safe read (readOnlyHint true, destructiveHint false, closed world), yet the description still adds real behavior: backlinks are read-only here, an ID/type mismatch is rejected rather than guessed, extended is additive and limited to people and families, results come back as plain text with no paging, and a missing record yields a not-found message with a hint. That is well past what the annotations carry.

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 the routing to siblings before the finer details, and every sentence carries information — no filler. It is a dense single paragraph, though, and the return-format sentence is long enough that an agent must read carefully rather than skim.

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 three-parameter read tool with no output schema, the description covers the remaining burden fully: input validation rules, the extended flag's scope, the shape of the plain-text return including 'Referenced by' sections, and the not-found path. 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 coverage is 100%, so the baseline is 3, but the description adds genuine interpretation: objectType is needed only with a handle because a Gramps ID prefix encodes the type, and a disagreeing objectType is rejected. It also explains what 'extended' actually yields for a person whose role in an event is not Primary, which the schema only gestures at.

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 — 'Read one record in full' — and enumerates what full means: fields, links, and backlinks. It also draws a clear boundary against search, list_objects, get_person_tree and get_timeline by name, so an agent can pick it 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 an explicit entry condition ('once you know the Gramps ID or handle') and names the alternatives with the conditions that select them: text lookup goes to search, type browsing to list_objects, relatives/dated events to get_person_tree and get_timeline because they are 'shorter'. Both when-to-use and when-not-to-use are covered.

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 (readOnly, non-destructive, closed-world), and the description goes well beyond them: it explains which lines are traversed, that ancestors include adoptive parent families, that relatives unlinked that way are omitted, that a person reached twice is listed once, and that each extra generation costs another round of reads. The documented not-found message is a useful error-behavior disclosure.

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?

Information-dense and front-loaded with purpose, traversal semantics, and alternatives in that order. The first sentence is a long compound run-on, which slightly hurts readability, but no clause is filler.

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

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

With no output schema, the description takes on the full burden and does so: it enumerates the row fields (generation, kinship label, name, Gramps ID, birth/death with places, handle), documents traversal edge cases, cost per generation, and the missing-person response. Nothing an agent needs to call it correctly is absent.

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 description adds real interpretation: 'generations counts steps from the person (1 = parents or children)' clarifies what the number means, and it explains the cost implication of raising it. kinshipLabels is also described in semantic terms beyond the schema's mechanical default 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 ('List a person's ancestors or descendants'), including the depth cap and the row-level output shape. It explicitly separates itself from get_relations, get_timeline, and get_object, so an agent can pick it 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?

Names three sibling tools with the exact condition that selects each ('for how two given people are related', 'for dated events around one person', 'for one full record'). It also recommends starting with the default 3 generations, giving concrete usage advice rather than just coverage.

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

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

Annotations already declare readOnly/non-destructive, and the description adds substantial behavior beyond that: newest-first ordering, per-transaction truncation at 10 objects with a remainder count, how added/removed links are rendered as Reference, and the hard 100-transaction ceiling that puts older history out of reach.

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 what it returns, then scope limits, then routing to siblings — a logical order with little waste. It is a dense single block with long clauses, so it is slightly harder to scan than it could be, but nearly every sentence carries information.

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

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

There is no output schema, so the description carries the return-shape burden and does so thoroughly: per-transaction fields, per-object fields, truncation behavior, and reference encoding. An agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100% and already documents the 1–100 range, default 20, and clamping. The description still adds meaning the schema lacks: limit counts transactions, not objects, which is the key semantic an agent could get wrong.

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

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

Opens with a specific verb and resource ('Show the tree's recent edit history, newest first') and immediately enumerates the fields returned. It is clearly distinguishable from siblings like get_timeline (dated events for one person) and list_objects (sorted record lists).

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

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

Gives explicit use cases ('check that your own writes landed', 'find the number undo_change takes') and names alternatives with the conditions that select them: list_objects with sort -change for older history, get_timeline for per-person dated events, get_object to read a changed record.

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/destructiveHint/openWorldHint, so the bar is low, yet the description adds real value: it documents error behavior ('an unknown topic or section is rejected with the valid values'), return formats (input-guide as fixed JSON, other topics as plain text read live from the tree), and the MCP-resource mirror (gramps://input-guide). None of that is recoverable from 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-loads purpose and the routing rule before the topic enumeration and return-format notes. It is dense and slightly run-on, but essentially every clause carries either usage routing or parameter semantics, so little is wasted.

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

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

With no output schema, the description correctly fills the gap by stating return formats per topic and the resource equivalent. Combined with the full parameter coverage and explicit alternatives, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning beyond the schema: how topic and section interact ('section returns one part of a topic, e.g. topic types with section event_types') and the note that 'metadata has no sections'. This helps an agent compose valid combinations rather than repeating 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 ('Read the server's reference for writing valid arguments') and immediately scopes it ('it holds no family records'), distinguishing it from the tree-reading siblings. An agent can tell this is a documentation/reference lookup, not a data fetch.

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 explicit timing ('Call it before a create_*, update_* or list_objects call when a date, name, link update, type or filter rule is unclear') and names the correct alternatives for the opposite need ('to read the tree itself use search, list_objects or get_object'). When-to-use, when-not-to-use, and alternatives are all present.

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 a safe read; the description goes well beyond by disclosing the 15-generation search depth, the 10-common-ancestor naming cap with handle fallback, no paging, and ordered results. It also enumerates edge-case behaviors (unrelated, same person twice, missing person) so the agent can interpret non-happy-path responses.

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 direction rule, the most error-prone part, and every sentence carries information. It is a dense single block that would scan better as short clauses, but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does so: both people with Gramps IDs, the closest relationship with generation counts, then all relationships closest-first with common ancestors. Nothing an agent needs to call or interpret 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 coverage is 100%, so both handles are already documented, but the description adds real meaning beyond it: the order-dependence and the fact that swapping handle1/handle2 yields the inverse term ('wife' instead of 'husband'). That is genuinely useful semantics not spelled out as clearly in 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 ('explain how two people are related') and immediately pins down the directional semantics with a concrete example ('third cousin twice removed', 'husband'). It is clearly distinguishable from lineage siblings like get_person_tree, which it explicitly names.

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 prerequisite ('Find both people first with search') and an explicit alternative with its selecting condition ('To list a whole line of ancestors or descendants use get_person_tree'). An agent knows both when to reach for this tool and when not to.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing cross-parameter interactions and edge cases: events/relativeEvents apply only to person timelines and are 'rejected otherwise', dates narrows both, and without dates relatives' whole-life events appear including before birth and after death. It also notes place timelines derive from direct event backlinks and exclude child places.

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-loads the core purpose and return shape, then layers in routing and parameter behavior. It is dense and slightly long as a single paragraph, but every sentence carries distinct, useful information 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 6-parameter read tool with no output schema, the description covers what the tool returns (fields and ordering), how each parameter interacts, and the key default/edge cases. 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 coverage is 100%, so the baseline is 3, but the description adds real cross-parameter semantics the schema cannot express: how events vs relativeEvents partition subject-vs-relative events, the rejection condition for non-person timelines, and the surprising default when dates is omitted.

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

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

States a specific verb and resource (list events around a person/family/place in date order) and even specifies the grouping (by decade, undated last) and returned fields (date, event type, place, whose event, with Gramps IDs). It explicitly distinguishes itself from get_object, get_person_tree, and get_relations.

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 explicit when-to-use ('check a life's sequence or gaps') and names three alternatives with the condition that selects each ('for the full record use get_object', 'for ancestors or descendants use get_person_tree', 'for how two people are related use get_relations'). Nothing 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: server-side filtering behavior, that invalid gql returns its error, invalid rules are explained, and missing IDs/tags/saved filters match nothing rather than failing, plus the interaction order 'rules run first and gql must then also match.'

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

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

The description is front-loaded with the core action and output format, then proceeds to use cases, alternatives, and caveats. It is dense but every sentence carries actionable information for an 8-parameter tool; minor length is justified by the behavioral constraints it discloses.

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 supplies the return format ('one line per record ... with the page and total count'). It covers filtering mechanics, error handling, parameter interactions, and use-case routing, leaving no critical gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter thoroughly, giving a baseline of 3. The description adds value by explaining cross-parameter interactions not present in the schema, such as 'rules run first and gql must then also match' and 'grampsId cannot be combined with rules.'

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 the records of one type a page at a time, optionally filtered and sorted,' and immediately gives the output shape (Gramps ID, summary, handle, page, total count). It distinguishes itself from siblings by naming search for text lookup and get_object for full-record reads.

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 enumerates concrete use cases (browse a type, fetch one Gramps ID, list a source's citations, filter with gql, select by relationships with rules) and explicitly routes agents to alternatives: 'To find records by text use search; to read one record in full use get_object.' It also states a key exclusion: 'grampsId cannot be combined with rules.'

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

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

Beyond the destructiveHint and idempotentHint annotations, the description explains exactly what is moved, what is kept, what is deleted, and that the operation occurs in one transaction. It further discloses family-merge nuances, refusal cases, confirmation-dialog behavior, and how undo_change can restore the deleted duplicate.

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 dense but front-loaded, starting with the core action and scope before moving into prerequisites, behavioral details, and return values. Despite its length, every sentence carries operational information relevant to a destructive merge tool.

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

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

For a destructive, multi-type merge operation with no output schema, the description covers purpose, prerequisites, edge cases, return shape, and undo behavior. An agent has enough information to decide when to call it and what to expect.

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, but the description adds useful semantic context: keepHandle and duplicateHandle are tied to which record keeps its fields versus which is moved and deleted, and mergeFamilies/fatherHandle/motherHandle behavior is elaborated. It stops short of adding new parameter-specific syntax or constraints 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: merge a duplicate into the record to keep, with an explicit list of supported Gramps object types. It clearly distinguishes this operation from update/delete siblings by describing the one-transaction move-and-delete behavior.

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 explicit when-to-use guidance: only after user confirmation that the records are the same, after reading both with get_object, and after finding candidates with search or list_objects. It also names conditions where merging is refused, such as spouses or parent-child pairs, and notes that tags cannot be merged.

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 a safe read (readOnlyHint=true, destructiveHint=false), and the description adds real context beyond them: the GRAMPS_MEDIA_RESOURCES_ENABLED=true prerequisite, EXIF/metadata stripping, no upscaling, and respect for size and private-record safeguards. It also discloses the differing return shapes per mode (MCP image content vs media link vs blob resource by MIME).

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 default mode, and every clause carries information (mode selection, output type, prerequisites, siblings). It is dense with semicolons and a few clauses restate schema details, which slightly blurs the structure.

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 media fetch with no output schema, the description covers the key unknowns: what content type is returned per mode and MIME, the environment flag required, metadata stripping, and where to go for the record itself or for modification. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already carries most semantics, but the description adds decision-level rationale: region is for verifying a crop before saving it, and the default 1568 size is chosen to keep handwriting and small print legible. Some of this overlaps the schema text (e.g., 1568px long edge, 512 for a quick look), so the added value is moderate rather than decisive.

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

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

Opens with a concrete verb+resource ('Download a media file's bytes') and immediately states the default behavior (JPEG thumbnail preview, PNG when transparent, 1568px long edge). It explicitly distinguishes itself from get_object (media record metadata) and update_media (changing it), so an agent can route correctly without opening sibling schemas.

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

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

Gives explicit when-to-use guidance: prefer thumbnail for reading photos and document scans, use region to check a part of an image before persisting it in mediaHandles or attachTo, and use mode file only when the original is needed. It also names the alternatives for adjacent needs (get_object, update_media) and the search/list_objects route to find a handle.

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description still adds substantial behavior: results are ranked by relevance across all types with no type filter, pagination semantics including the past-the-end response, the exact return shape (type, Gramps ID, summary, handle plus page and total), and a concrete failure mode (HTTP 500 on long queries) with a retry strategy.

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 and routing before mechanics, and every sentence carries information — wildcard syntax, result shape, pagination edge case, error recovery. It is dense and slightly long for a search tool, but there is no filler to cut.

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

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

There is no output schema, and the description compensates by describing the return line format, the page/total count, and the empty-page behavior. Combined with the error-recovery note, an agent has everything needed to call this correctly on the first attempt.

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 goes further by explaining that page/pagesize step through ranked hits and that pagesize caps at 100, and by framing query as free text with wildcard endings. Much of the wildcard and range detail duplicates the schema's own parameter descriptions, so the added meaning is real but modest.

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 ('Find records by words in them') and immediately scopes it as one query across ten named object types. It explicitly distinguishes itself from list_objects (browse/filter one type) and get_object (read a hit in full), so an agent can route without opening a schema.

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

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

Gives an explicit entry condition ('Start here when you have a name, place, title or other text but no Gramps ID') and names both alternatives with the conditions that select them: list_objects for browsing/filtering by fields, get_object for reading a hit by ID or handle. When-not guidance is implicit in 'there is no type filter'.

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?

Well beyond the destructiveHint/openWorldHint annotations, it discloses that the undo is a single all-or-nothing transaction that is itself reversible, enumerates the three conflict classes that abort with nothing changed, and explains the client-side confirmation dialog and what a declined action means. It even lists the returned action states (undone, checked, refused, pending).

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?

Effects are front-loaded and the progression (what it does → confirmation requirement → conflicts → ordering/force → return values) is logical. It runs long at roughly six sentences and the trailing sentence on return states plus the client-dialog aside are somewhat stacked, but each carries distinct operational information rather than repetition.

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

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

With no output schema, the description compensates by naming the return values; for a destructive, non-idempotent mutation it covers reversibility, atomicity, conflict failure modes, escape hatches (dryRun, force), and required user confirmation. An agent has everything needed to invoke it safely without trial and error.

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 real value by explaining what conflict conditions force overrides and why a separate confirmation is required, plus that dryRun reports conflicts without writing. It does not add format or syntax detail for transactionId beyond the schema's pointer to get_recent_changes.

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 ('Undo one transaction listed by get_recent_changes') and then spells out the exact effects: added records deleted, updated records reverted, deleted records restored. An agent can distinguish this from every sibling, including get_recent_changes, which it explicitly references as the source of the transaction ID.

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 explicit preconditions ('Call it only after the user confirmed that transaction') and an ordering rule for conflicts ('Undo the later transactions first, newest first, or pass force=true after a separate confirmation'). It also names the alternative for inspection (dryRun) and the sibling that supplies the input, leaving nothing 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?

Goes well beyond the destructive/idempotent annotations: it warns that replace mode with [] deletes every link of that kind while the linked records survive, that attributes always replace wholesale regardless of linkMode, that edits propagate to every citing record, and that writes serialize and need edit rights with a retry delay on lock/rate-limit.

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 and dense with real content, but it repeats several facts already carried in the schema (empty string clears date, sourceHandle semantics, linkMode rules) and packs four distinct topics into a single paragraph. Trimming the duplicated clauses would make it easier to scan.

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

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

For an 11-parameter destructive mutation with no output schema, it covers everything an agent needs: return value (handle and Gramps ID), not-found behavior, auth/rate-limit failure mode, partial-update defaults, and where to find argument formats.

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

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

Schema coverage is already 100%, yet the description adds cross-parameter meaning the per-property docs cannot: omitted arguments are preserved, empty string clears date, sourceHandle relocates the citation, and linkMode governs all …Handles lists. It largely restates schema-level detail (region, handle formats) rather than extending it, keeping it below a 5.

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 plus the exact field set it can change (source, page, date, confidence, attributes, note/media/tag links). It also distinguishes citation-level editing from the record-side citationHandles path, so an agent can route correctly without opening the schema.

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

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

Explicitly names the alternatives and the conditions that select them: use a record's update tool for attaching/detaching support links, create_citation to cite another page for one record, delete_object to remove. It also states the out-of-scope case inline ('not here').

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 confirm destructiveHint=true, idempotentHint=true, and openWorldHint=false, and the description adds substantial context beyond them: shared visibility of changes, empty-string clearing, attributes replacing the whole list, [] removing all links in replace mode while linked records remain in the tree, not-found and validation error behavior, one-write-at-a-time serialization, edit-permission requirement, and rate-limit retry guidance.

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-loads the core action and scope, then layers routing, linkMode semantics, error behavior, and auth/rate-limit notes. It is dense but every sentence carries useful information; the input-guide pointer at the end is a minor extra.

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

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

Covers purpose, alternatives, mutation semantics, error outcomes, permissions, concurrency, and rate limiting for a 12-parameter destructive update. With no output schema, it still states the return value (handle and Gramps ID) and error cases, so an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter in detail. The description still adds cross-cutting meaning not repeated per-parameter: omitted arguments stay as-is, empty string clears date, attributes replace regardless of linkMode, and replace-mode [] removes every link of that kind while keeping linked records.

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 (Change) and resource (existing event) and enumerates exactly which fields can change: type, date, place, description, attributes, links to citations/notes/media/tags. It also explicitly distinguishes scope from sibling operations by naming create_event and delete_object.

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

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

Explicitly routes participation changes to update_person/update_family eventRefs, creation to create_event, and deletion to delete_object. It also states the replace/add/remove linkMode semantics and notes that attributes ignore linkMode, which is guidance an agent would otherwise have to guess.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial behavior beyond them: Gramps Web updates the people's reciprocal records in the same save, a nonexistent father/mother/child aborts the entire change with nothing saved, writes are serialized and require tree-edit permission, and locked or rate-limited writes report a retry delay. It also discloses that the return value is only a short header rather than the changed object, directing the caller to get_object.

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 long but front-loaded: purpose first, then alternatives, then linkMode rules, then side effects and return behavior. Nearly every sentence carries non-obvious operational information, though a few points (linkMode semantics, attributes replacing regardless of linkMode) are restated from the schema descriptions and could be trimmed.

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, yet the description states exactly what comes back (type, action, handle, Gramps ID) and how to retrieve the changed family, and it covers missing-handle and rate-limit failure modes. For a destructive, 14-parameter mutation tool, nothing an agent needs in order to invoke it safely 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 schema carries the per-parameter detail and the baseline is 3. The description still adds cross-parameter semantics the schema cannot easily express: linkMode governs all handle/ref lists uniformly, [] in replace mode removes every link of that kind without deleting the linked records, attributes always replace regardless of linkMode, and sort reorders without changing membership.

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 opening sentence names a specific verb and resource ('Change an existing family's') and enumerates the mutable facets: father, mother, relationship type, children, events, attributes and link lists. It immediately distinguishes itself from create_family and delete_object, so an agent can route without consulting 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?

It gives explicit when-to-use and when-not-to-use guidance by naming create_family and delete_object as alternatives, and it explains the linkMode choice (replace default, add appends, remove drops) plus the special rule that attributes always replace. The 'pass only what changes; omitted arguments stay as they are' sentence resolves the main ambiguity for a 14-parameter update tool.

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 (destructive, idempotent), but the description adds substantial behavioral context the annotations cannot convey: serialized writes, Gramps Web edit authorization, locked/rate-limited failures with retry delay, not-found messaging, pre-save rejection of bad dates/files, and the critical []-removes-all-links semantics in replace mode.

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 alternatives, then behavioral rules, with dense semicolon-separated clauses and no filler sentences. It is long, but for an 11-parameter mutation tool nearly every clause carries load; only minor overlap with the already-verbose schema descriptions.

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 it still states the return value (handle and Gramps ID), error paths, auth requirements, concurrency and retry behavior, and links to the input-format reference. For an 11-param destructive tool, nothing essential for correct invocation 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, but the body adds cross-parameter semantics the schema states only locally: linkMode governs all link lists but not attributes/names/URLs, attachTo is exempt from linkMode, and empty lists clear only in replace mode. That interaction detail is genuine added meaning over per-field schema text.

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

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

Opens with a specific verb+resource ("Change an existing media record") and enumerates the changeable facets: description, date, attributes, links, file replacement. It explicitly names the sibling alternatives create_media and delete_object, so the agent can route without opening another 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 explicit when-to-use and when-not-to-use: create_media for a new record, delete_object to remove one, and the specific alternative ("that record's update tool with mediaHandles and linkMode remove") to detach from a parent record. It also states which knobs affect which lists ("Does not affect attributes...").

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial behavior beyond them: writes run one at a time, auth requirement for editing, lock/rate-limit failure mode with retry delay, return value (handle + Gramps ID) and not-found behavior, and the critical '[] in replace mode REMOVES every link of that kind while linked records stay in the tree'. It also clarifies that attachment records live on the referencing object, not the note.

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, then systems of behavior, then sibling routing, then operational caveats. It is long (8+ sentences) and dense, but nearly every sentence carries non-redundant information for a 10-parameter mutation tool; minor trimming of linkMode restatement is possible.

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, and the description compensates by stating the return value and the not-found case. Combined with auth, concurrency, rate-limit and link-mode semantics, an agent has everything needed to invoke this destructive update correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema documents only piecemeal: replaceText is applied before appendText, the three body-editing params are mutually exclusive, omitted args are left unchanged, and empty link lists only clear in replace mode. This ties the 10 parameters together rather than restating them.

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

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

Opens with a specific verb+resource ('Change an existing note') and enumerates the changeable fields (text, type, format, tags, private flag). It also explicitly names the sibling boundaries: 'For a new note use create_note; to remove one, delete_object.' An agent can distinguish this from create_note/update_* siblings without opening any schema.

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

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

Gives explicit when-to-use routing: use create_note for a new note, delete_object for removal, replaceText/appendText instead of text for long notes, and only pass changed arguments. It also states the operational precondition (Gramps Web account allowed to edit the tree) and the retry behavior on locked/rate-limited writes.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), it discloses the critical destructive edge case — '[] REMOVES every link of that kind, though the linked records themselves stay in the tree' — plus that writes are serialized, require a Gramps Web account with tree-edit rights, and that locked or rate-limited writes fail with a retry delay. It also states the return value (handle and Gramps ID) and the not-found outcome.

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?

For an 18-parameter tool the text is dense but front-loaded: purpose and alternatives come first, then the linkMode/replacement rules, then permissions, then the pointer to get_reference for argument formats. It loses a point for some restatement of what the schema already documents in detail and for the compressed, run-on middle section that takes effort to parse.

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

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

With 18 parameters, no output schema, and mutation semantics, this description covers what an agent needs: what gets changed, how link lists are applied, the destructive empty-list case, ordering behavior via sort, authorization and rate-limit failure modes, and where to find argument grammars. Return values are stated even though no output schema exists.

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

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

Schema description coverage is 100%, so the per-parameter baseline is 3. The description earns extra credit by adding cross-parameter semantics the schema cannot express per-field: which lists ignore linkMode (alternateNames, attributes, addresses, urls always replace wholesale), that sort reorders without changing membership, and the replace/add/remove contract that governs every …Handles/…Refs list.

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 opening sentence gives a specific verb plus the full resource and enumerates the changeable facets (names, gender, attributes, addresses, URLs, associations, links to events/families/citations/notes/media/tags). It also explicitly separates this tool from create_person and delete_object, so the agent can distinguish it from siblings without reading schemas.

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

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

It names the alternatives and the condition that selects them ('For a new person use create_person; to remove one, delete_object'), and adds a routing rule for a related operation ('to make the person a child, add them to the family's childRefs with update_family'). 'Pass only what changes; omitted arguments stay as they are' gives an explicit usage discipline rather than leaving it to inference.

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

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

Annotations already declare write/destructive/idempotent, and the description goes well beyond them: in replace mode an empty list REMOVES every link of that kind while linked records remain; missing place returns a not-found message; unknown type or unreadable date is rejected before anything is saved; writes are serialized, require an edit-capable Gramps Web account, and rate-limited writes return the delay to wait. This is unusually rich operational context.

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

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

Front-loads the verb and scope, then alternatives, then semantics, then errors — a sensible order. It is dense and long, but for a 16-parameter mutation tool almost every sentence carries load; only the detailed linkMode/clearing rules push it near over-length.

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 16-param write tool with no output schema, the description covers what is returned (handle, Gramps ID, stored name/type/coordinates/enclosing places), failure modes, permission and rate-limit behavior, and points to get_reference for argument formats. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: how name/nameLang/nameDate jointly edit the primary name, that alternateNames replaces the other names entirely, that empty strings clear lat/lon/nameDate, and that omitted arguments are preserved. The linkMode semantics governing all link lists further clarify parameter behavior 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?

States a specific verb and resource ('Change an existing place's names, type, coordinates, code, enclosing places or links') and enumerates exactly which fields are mutable. It explicitly distinguishes itself from create_place, delete_object and update_event, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-not guidance: use update_event if only one event names the wrong place, create_place for a new place, delete_object to remove one. It also advises separate calls to add and remove versus replace to edit link metadata, covering alternative invocation strategies.

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

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

Beyond the annotations, it discloses that changes propagate to every source listing the repository, that empty strings/empty lists remove stored values, that replace mode can destroy link metadata, that writes are serialized and require edit permission, and that locked/rate-limited writes return retry delays. It also describes the return value and error cases. It is fully consistent with destructiveHint=true and idempotentHint=true.

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 definition is dense but front-loaded: purpose first, then alternatives, scope boundaries, update semantics, linkMode behavior, returns, and auth/rate-limit behavior. Every sentence carries operational information for a nine-parameter destructive mutation tool.

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

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

For a destructive update tool with no output schema, the description is complete: it covers return values, not-found handling, type validation, propagation effects, partial-update behavior, linkMode semantics, authentication requirements, and retry behavior under locking/rate limits.

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 prose adds integrated meaning: it explains that address becomes a single street line and url a single Web Home link, that both replace all stored values, and that linkMode governs every supplied link list including [] semantics. This is largely reinforcing the schema, but the cross-parameter interaction is usefully clarified.

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 specific verb and resource: changing an existing repository's name, type, address, website, or links to notes and tags. It explicitly distinguishes itself from create_repository, delete_object, and update_source, so an agent can select it without opening sibling schemas.

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

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

It states when to use this tool versus create_repository for new repositories, delete_object for removal, and update_source for source-to-repository links. It also gives important usage rules: pass only changed fields, omitted arguments stay unchanged, and link lists follow linkMode.

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 destructive/idempotent/write, but the description adds substantial context beyond them: write serialization ('one at a time'), the account permission requirement, lock/rate-limit failure with a retry delay, the not-found response, and the destructive edge case that [] in replace mode removes every link of that kind. That is well past what the structured fields 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?

Front-loaded with purpose and alternatives, dense but mostly earning its length for a 12-parameter mutation tool. Some material (linkMode mechanics) duplicates the schema text, and the final grammar pointer is a mild tail, so it is not perfectly tight.

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 complex mutation tool with no output schema, it covers return values (handle and Gramps ID), error cases (not found, locked/rate-limited), and authorization requirements. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the per-field baseline is 3, but the description adds cross-parameter semantics the schema only states per-field: repositoryHandles carry the call number so call numbers are edited via linkMode replace, and attributes replace the whole list regardless of linkMode. These interaction rules are genuinely additive, though the linkMode explanation largely restates the schema's own detailed description.

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

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

States a specific verb (change/update) plus resource (existing source) and enumerates the editable facets (title, author, pubinfo, abbreviation, attributes, links, notes, media, tags). It actively distinguishes itself from create_source, delete_object, and update_citation, so an agent can tell the boundary without opening a schema.

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

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

Explicitly routes to alternatives: create_source for a new one, delete_object to remove, update_citation for a page/act inside the source. It also states the partial-update contract ('Pass only what changes; omitted arguments stay as they are') and that forms live in get_reference, leaving little 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?

Goes well past the annotations: it discloses that the change propagates to every carrying record, that duplicate names are rejected because Gramps filters by name, that omitted arguments persist (matching idempotentHint=true), that it returns name/color/priority, that writes are serialized, that an edit-capable Gramps Web account is required, and that locked/rate-limited writes return a retry delay. No contradiction with destructiveHint=true or idempotentHint=true.

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?

Well front-loaded: purpose, then alternatives, then scope boundary, then behavior. Dense but nearly every clause is load-bearing; the final sentence stacks auth, serialization and retry semantics into one long clause, which is the only mild readability cost.

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 explicitly covers the return value (stored name, color, priority) and the failure message for a missing tag, plus auth and retry behavior. Nothing needed to call or interpret this mutation tool is missing.

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

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

Schema coverage is 100% and each field is documented, so the baseline is 3; the description adds genuine semantics beyond that by stating omitted arguments are left unchanged and by explaining the uniqueness constraint on 'name' (why a duplicate is rejected).

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

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

Opens with a specific verb+resource+effect ('Rename a tag or change its color or priority; every record carrying the tag shows the change'). It also names the sibling tools that would be confused with it (create_tag, delete_object), so the agent can distinguish it 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?

Explicit when-to-use routing: 'For a new tag use create_tag; to remove one, delete_object.' It further excludes a plausible-but-wrong path by stating that record-to-tag membership is edited via tagHandles on the record's own update tool, not here. Partial-update guidance ('Pass only what changes') is also given.

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