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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety and repeatability are partly covered. The description adds one useful behavioral fact — 'The person's primary name is left unchanged' — but says nothing about duplicate alternate names, permissions, or what a repeated call does despite idempotentHint being false.

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

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

Three short lines, front-loaded with the action and scope, followed by use cases and the key side-effect. No filler or redundancy.

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

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

For a non-destructive mutation tool with full schema coverage and annotations on safety, the description covers purpose, scope, use cases and the primary-name guarantee. Only edge cases (duplicates, repeat calls, error behavior) are unaddressed.

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

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

Schema description coverage is 100% across all 7 parameters, so the schema already explains given, surname, nickname, name_type, prefixes/suffixes and the person handle. The description adds no parameter-level detail beyond that, which is the correct baseline when the schema does the work.

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

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

States a specific verb ('Add') and resource ('alternate (non-primary) name to a person'), and explicitly carves out the non-primary scope so it is distinguishable from update_person or add_person, which handle the primary name.

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

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

The second line enumerates concrete when-to-use cases (maiden/married names, aliases, anglicized forms, nicknames-of-record), giving clear context. It does not, however, name an alternative tool or state when not to use this one (e.g. correcting the primary name).

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, so the description's main added value is the internal behavior that the right class (SrcAttribute vs Attribute) is chosen automatically from object_type. It still omits anything about permissions, duplicate attribute names, or failure modes.

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

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

Three short sentences, front-loaded with the core action and followed by the only non-obvious behavioral rule. No filler.

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

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

For a 4-required-param mutation tool with full schema coverage and annotations carrying the safety profile, the description covers the action and the object_type→class rule adequately. Gaps around duplicate attributes and error conditions are minor.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description adds one genuinely useful semantic link (object_type drives class selection) but no format or syntax details, so baseline 3 fits.

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 ('Add') and resource ('typed key/value attribute to an object'), which is clear and actionable. It does not, however, differentiate itself from adjacent mutation siblings such as update_object_fields or cite_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?

Usage is only implied: 'to an object' and the class-selection note give the agent enough to know it is an attribute-writing tool, but there is no explicit when-to-use vs alternative (e.g. update_object_fields) and no note on prerequisites like target existence or duplicate handling.

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 the mutation profile (readOnly=false, destructive=false, openWorld=false), so the description earns credit for going beyond them by explaining the bidirectional side effect (ChildRef on the family plus the family added to the child's parent-family list) and the duplicate-handling rule. The 'duplicate children are skipped' wording sits in mild tension with idempotentHint=false, but it reads as a data-integrity rule rather than a claim of full operation idempotency, so it is not a hard contradiction.

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 core action is front-loaded in the first sentence, with side effects and preconditions following in short supporting sentences. It is tight overall, with only a small amount of wordiness in the 'Links the child both ways' sentence.

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

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

For a 4-parameter mutation tool with full schema coverage and no output schema, the description covers what is created, the precondition, and duplicate handling. Error behavior (e.g., nonexistent family/child) and permission requirements are unstated, but those gaps are minor.

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

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

Schema description coverage is 100%, so the schema already documents family, child, frel, and mrel with examples. The description adds only the 'child must already exist' constraint and implies the family must pre-exist; it adds no format or value details for the two relationship parameters beyond what the schema provides.

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

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

The description gives a specific verb (Add) and resource (an existing person as a child of an existing family) that is unmistakably distinct from sibling tools like add_person, add_family, add_event_to_family, or link_repository. An agent can identify the operation 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?

It supplies an important precondition ('The child must already exist'), which tells the agent to create the person first via add_person rather than passing new data. However, it never states when to choose this tool over alternatives or explicitly rules any sibling in/out, so usage guidance remains implied.

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

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

Annotations declare the write profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower. The description adds real context: this creates a citation that can also spawn a new source, and reuse is preferred over duplication. It does not say what is returned or how to obtain the handle for later reuse, which is the one operational detail left implicit.

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

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

Three short sentences, zero waste; the core action leads and the routing caveat follows immediately. Nothing could be cut without losing guidance.

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

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

For a single-param create tool with 100% schema coverage and annotations covering the safety profile, the description is nearly complete. The only gap is not stating that a citation handle is returned (the thing needed to reuse the citation later), which the description itself makes relevant.

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 CitationInput already documents the citation/source/source_title precedence and every field. The description only reinforces the reuse-vs-create duality the schema already states, adding no new syntax or format detail, so the baseline 3 applies.

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

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

Specific verb+resource ('Create a standalone Citation on a Source') with the reuse alternative stated in the same sentence. It cleanly separates this tool from the attachment-style siblings (add_person, add_event_to_person, add_family) that are the usual path.

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-not ('Usually you don't call this directly -- pass a CitationInput to add_person / add_event_to_person / add_family instead') and explicit when-to ('when you want a reusable citation handle to attach to several facts'). The routing decision is fully specified.

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 this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds genuinely useful behavior not in the annotations: atomic validation ('Nothing is written unless the segments parse'), the storage/interop guarantee that get_dna_matches will read it back, and the always-mint-a-new-citation semantics. It stops short of permissions, error modes, or return shape, so not a 5.

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

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

Three short, front-loaded sentences: purpose first, then behavioral guarantee, then a scope caveat. Mostly waste-free, though the explanatory clause 'unreadable data would otherwise record a match sharing no DNA' is slightly verbose relative to the point it makes.

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 four-required-parameter write tool with no output schema and fully documented parameters, the description supplies the rationale, the atomicity guarantee, and the conceptual boundary against relationship recording – enough for correct invocation. A return-value or permission note would close the remaining gap, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100% – the segments, citation, person, and match parameters are all richly documented in the schema itself, including the citation precedence rules and segment format. The description reinforces the citation semantics ('cited to the test that found it') but adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Record a DNA match as evidence, cited to the test that found it') and scopes it clearly against the read-side sibling by noting get_dna_matches reads the stored match back. An agent can distinguish this from get_dna_matches, parse_dna_segments, and get_ydna 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?

The description draws a useful boundary ('A match proves the two share DNA, not how they are related. Record any relationship separately'), which implies when this tool is and isn't the right one. However, it never names an alternative tool (e.g. parse_dna_segments for validating raw data) or states prerequisites beyond 'add them first if they are not in the tree' (which lives in the schema). Guidance is implied rather than explicit.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write; the description adds useful context about the 'Family' role assignment and citation practice. It does not mention the require_citation default or that setting it false deliberately records an UNSOURCED fact, nor whether repeat calls duplicate events.

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

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

Three short sentences, front-loaded with the action and then the scope constraint and examples; no filler. The final sentence ('Cite it to the record establishing the fact') is a little vague about which record, slightly diluting an otherwise tight definition.

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

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

For a 3-parameter mutation tool with no output schema and full schema documentation, the essentials are largely carried by the schema and annotations. However, the description never confirms what a successful call produces or how it interacts with require_citation being false, which is a meaningful behavioral gap for an agent.

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

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

Schema description coverage is 100%, so the event type/date/place/citation fields and their resolution rules are already fully documented in the schema. The description only restates the citation habit ('cite it to the record establishing the fact') without adding syntax or precedence detail, which matches the baseline 3 for schema-covered params.

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

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

Names a specific verb+resource ('add a dated/placed event to an existing family') and immediately carves out scope ('Use for family-level facts'), which implicitly distinguishes it from the sibling add_event_to_person. An agent can tell what this tool does 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 says when to use it (family-level facts) and gives concrete examples (marriage, divorce, residence, census), plus the notable behavior that the event gets the 'Family' role. It stops short of naming add_event_to_person as the alternative for person-level facts, so the routing rule is inferred rather than stated.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely non-obvious behavior: that adding a 'Birth'/'Death' event will set the person's primary reference if not already set, and that citations should point at the establishing record. It does not mention e.g. duplicate-event handling or error cases for a missing person.

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

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

Three tight sentences with the core action front-loaded, followed by scope and side-effect caveats. No filler or redundancy.

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

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

For a mutation tool with full schema coverage and no output schema, the description covers purpose, scope, citation expectation, and a key side effect. It omits any mention of the return value or failure behavior (e.g. nonexistent person handle), a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents person, event.type, date, place, citation, and require_citation. The description only reinforces citation intent and the type-specific Birth/Death side effect, adding marginal value over the structured fields.

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 (add) and resource (dated/placed event/fact) and scopes it to 'an existing person', which separates it from the sibling add_event_to_family by target entity. It does not explicitly name or contrast with the sibling tool, so it falls just short of a 5.

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

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

'Use for facts beyond birth/death: residence, occupation, census, baptism, immigration...' gives clear positive usage context with concrete examples. There is no explicit when-not or named alternative tool, but the intended context is unambiguous.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds genuine behavioral context the annotations cannot convey: the automatic bidirectional linking of family/parent-family lists, the existence prerequisite, and the expectation that the marriage event be cited.

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 action and then the prerequisite, side effect, and citation advice in descending priority. Slightly more text than strictly needed, but each sentence carries distinct information.

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

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

For a 6-parameter creation tool with no output schema, the description covers the key gaps: prerequisites, automatic linkage, and citation expectations. It does not say what the return value contains or how missing father/mother are handled, but nothing critical to correct invocation 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 description coverage is 100%, so every parameter (father, mother, children, marriage, relationship, require_citation) is already documented in the schema, including the CitationInput precedence rules. The description's 'optional cited marriage' and 'cite to a marriage record where possible' add only marginal guidance beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Create a family linking parents and children') and immediately scopes it with the optional marriage event. An agent can distinguish this from add_person and add_child_to_family 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 a clear prerequisite ('All members must already exist — create them first with add_person') and tells the agent not to also update individuals separately, which is a real when-to-use cue. It stops short of naming sibling alternatives like add_child_to_family or add_event_to_family explicitly.

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 the safety profile (not read-only, not destructive, not idempotent). The description adds genuine behavioral context beyond them: identical files are reused rather than duplicated, files are stored under checksum names, and a Media object is meant to be cited once but attached in many places. It does not describe auth requirements or the returned reference explicitly.

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 in the first sentence, followed by workflow guidance. The closing sentence about re-uploading the same photograph is slightly editorial but earns its place by motivating the dedup/citation model, so it is not wasted.

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

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

For a simple 3-parameter creation tool with full annotation coverage and no output schema, the description covers purpose, dedup behavior, and the downstream attach/cite workflow. The only gap is that the return value (the media reference used by attach_media) is only implied, not stated.

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 all three parameters, including the dedup_by_checksum default. The description reinforces the dedup semantics ('reusing an identical file already in the tree') but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Upload a document as a standalone Media object') plus the dedup behavior, and implicitly distinguishes itself from attach_media and update_media by framing itself as the creation step. An agent can tell it apart from its siblings 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 routes the agent to the follow-up step ('attach it wherever it belongs with attach_media(media_ref=...)') and warns against the duplicate-per-person upload pattern, giving a clear context of use. It stops short of an explicit when-not-to-use rule (e.g., when to use update_media instead), so not a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description need not restate them. It adds useful context on the attachment mechanism and typical content, but says nothing about required permissions, whether the note is linked atomically, or what happens on failure. Adequate but not rich.

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

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

Two sentences, front-loaded with the core action, no filler. The second sentence is slightly loose (use-case examples plus an attachment line) but each clause carries information.

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

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

For a create tool with full schema coverage, annotations carrying the safety profile, and no output schema, the description supplies the purpose and attachment semantics an agent needs. Missing only edge details like permission requirements or what the created note's handle looks like.

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

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

Schema description coverage is 100%, so both target and target_type are already documented in the schema, and note_type carries its own default and example. The description adds only the relational hint that target + target_type go together, which is marginally beyond the schema. Baseline 3 is correct.

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

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

States a specific verb and resource ('Create a research/general note') and clarifies the scope ('optionally attached to an object'), which cleanly separates it from the read-side sibling get_note. It is clear but never explicitly names a sibling tool or the boundary with add_attribute/add_url, so it stops short of a 5.

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

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

Explicitly says when to reach for it ('research logs, reasoning about conflicting evidence, or transcriptions') and how to attach it ('give target + target_type'). There is no when-not guidance or named alternative, so it falls just short of the top band.

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, so the bar is lower. The description adds real behavioral value beyond them: the call can FAIL when require_citation is True and no citation is supplied, and the unsourced alternative stamps an UNSOURCED attribute detectable by list_unsourced_facts. It further states the return payload (handle and gramps_id).

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

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

Three short paragraphs, front-loaded with the core action before the citation-practice guidance, and every sentence carries actionable content. Slightly more text than strictly needed for a single creation tool, but nothing 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?

No output schema exists, but the description names the return values, and given the very rich nested input schema the citation workflow is fully covered. Remaining gap: no note on duplicate detection or how this interacts with find_duplicates/merge_objects for a non-idempotent create.

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 nonetheless adds operational meaning to require_citation (it is a hard failure gate, not just a flag) and to the citation field (cite the specific record that proves the fact, set confidence honestly), 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?

States a specific verb and resource ('Create a new person') plus the optional scope (cited birth/death events), which cleanly distinguishes it from siblings like add_family, add_event_to_person, and update_person. An agent can pick this out without opening the schema.

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

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

Gives clear context ('Use this to add someone to the tree') and a decision rule for the citation case vs. the legacy-hint case with require_citation=False. It does not name sibling alternatives such as add_event_to_person for adding events to an existing person, so routing is implied rather than explicit.

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/non-idempotent/non-destructive behavior. The description adds genuine context beyond that: the parent must already exist and is never auto-created, and the implicit-event route yields untyped, unparented places that seed duplicate hierarchies. It does not discuss permissions or what the call returns, but the added failure-mode context is valuable.

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

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

Front-loads the action, then justifies the alternative-route warning in a single flowing sentence. Slightly verbose in the duplicate-hierarchy explanation, but no sentence is pure 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 7-parameter create tool with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies exactly the missing piece an agent needs: why to call this instead of the implicit route. Nothing required to invoke 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 description coverage is 100%, so every parameter is already documented in the schema, including the title/parent semantics. The description only reinforces the type and parent concept generically, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb ('Create') plus resource ('a place') with the two defining attributes (type, parent) named up front. It also implicitly distinguishes itself from the event-naming route that creates places as a side effect, so an agent can tell what this tool is for.

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 when-to-use rule: use this rather than letting a place appear as a side effect of naming one in an event. It does not mention the sibling update_place or when to prefer editing an existing place over adding one, so it stops short of full alternative routing.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds conceptual domain context but nothing behavioral beyond the annotations — no mention of duplicate handling (relevant given idempotentHint=false), required permissions, or what the call returns.

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 definition, followed by a compact hierarchy note and a usage sentence; nothing is padded. The hierarchy explanation is useful framing rather than filler, though the definition of "Repository" is restated in slightly different words.

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

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

For a simple three-parameter create tool with full schema documentation and annotations covering the write-safety profile, the description supplies enough domain framing to call it correctly. It is only slightly short given there is no output schema — the return value (e.g., the new repository identifier) is never described.

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

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

Schema description coverage is 100%, so all three parameters (name, url, repository_type) are already documented in the schema. The description's list of repository kinds loosely overlaps with the repository_type enum examples but adds no format or syntax detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ("Create a Repository") and immediately defines the entity: "an institution or place that holds sources." It also places the entity in the evidence model (Repository -> Source -> Citation -> fact), which distinguishes it from siblings like add_source and add_citation without requiring the agent to open any schema.

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

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

It states clear usage context by enumerating the kinds of things to create repositories for (archives, libraries, cemeteries, websites you'll cite sources from). That tells the agent when this tool applies, but it names no alternative tool or exclusion condition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain behavior (a source is created once and reused, repository linkage is optional) but says nothing about duplicate handling or what happens if a similar source already exists, which matters given idempotentHint=false.

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

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

Front-loaded with the imperative verb and resource, and the following sentences each add domain context (evidence model, citation relationship, repository linkage) rather than restating the name. Slightly verbose but no sentence is pure padding.

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

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

For a creation tool with a fully documented schema and no output schema, the description supplies the essential domain model an agent needs in Gramps (Source vs Citation, optional Repository). The main omission is duplicate/already-exists behavior, which the annotations leave open.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds only the optional Repository concept ('where the source is held'), which is a marginal conceptual clarification rather than new format or syntax guidance. Baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (Source), then defines the resource concretely as a body of evidence (record set, book, certificate, website). It also positions it against the sibling add_citation by explaining that a Source is cited *through* a Citation, so an agent can distinguish the two without opening schemas.

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

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

Provides clear workflow guidance: create the source once, then create citations against it for each fact, and optionally link a Repository. This implicitly routes the agent to add_citation for the next step. It lacks an explicit when-not-to-use or a named alternative for a different scenario, so it stops short of a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds a useful scope constraint about which object types carry URL lists, but that constraint is largely mirrored in the object_type schema field, and it does not explain what happens on duplicate calls or invalid URLs. With annotations covering the main behavioral signals, a 3 is appropriate.

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

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

Two tightly written sentences with no filler. The primary action is front-loaded, and the alternative routing follows immediately, making the description easy to scan.

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

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

For a write tool with no output schema and full schema coverage, the description provides the essential routing and scope information, while annotations carry the safety profile. It stops short of warning about duplicate creation (idempotentHint=false) or update scenarios, but nothing critical 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 description coverage is 100%, so all five parameters are documented in the schema itself. The description adds no syntax or format details beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Add a web URL") and immediately bounds the scope to three object types, which an agent can use to distinguish it from sibling tools like add_attribute or update_url. It also explicitly names where the same data belongs for other object types, so the tool's identity is unambiguous.

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

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

It states when to use the tool (person, place, or repository) and when not to (sources/citations), naming add_attribute as the correct alternative for that case. The only minor gap is not mentioning update_url for existing links, but the core routing decision is fully supplied.

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 and openWorldHint=false, but the description adds genuinely useful behavior: it is advisory, it handles undated people via relative inference, and bulk output is filtered by the server's own rule regardless of the return value. These caveats go beyond what the annotations 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 the core purpose, then the mechanism, then usage. Three short paragraphs, each earning its place, though the mechanism sentence is slightly elaborate.

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 assessment tool with no output schema, the description covers what is returned (a verdict, plus reasoning under `explain`) and the advisory caveat. 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 description coverage is 100%, so all four parameters are already documented in the schema. The description only restates the purpose of `explain`, adding no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb ('assess/ask whether a person is probably still alive') and resource (a person), and immediately clarifies the key mechanism — the server walks relatives rather than relying only on the person's own dates. No sibling tool does anything comparable, so it is clearly distinguishable.

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 context ('use it before publishing or sharing anything') and routes to the reasoning mode ('use `explain` when you want to see the reasoning rather than just the verdict'). It does not name a distinct alternative tool or state when NOT to use it, so it stops short of a 5.

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

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

Annotations only declare the coarse safety profile (not read-only, not destructive, not idempotent); the description adds genuinely non-obvious behavior: bytes are copied into the tree's managed media directory, an already-present identical file is reused rather than duplicated, and the write is post-verified with `verified: false` meaning nothing attached. That last point is critical signal beyond any structured field.

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 core action is front-loaded in the first line, and each paragraph carries a distinct payload (upload semantics, linking semantics, duplicate warning + verification). The "ONE Media object... cited once per fact" passage is somewhat discursive, but it earns its place as anti-pattern guidance.

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

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

For a mutation tool with no output schema, the description compensates by explaining the return signal (`verified: false`) and the dedup/verification behavior. Combined with annotations covering the safety profile, an agent has enough to invoke it correctly and interpret the result.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema: it frames file_path/media_ref as mutually exclusive choices, explains the dedup side effect of file_path, and states the reuse preference for media_ref. The "Use this OR media_ref" framing and dedup semantics are not in the schema prose.

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 precise verb+resource ("Attach an image or document to an object") and enumerates its two operating modes: upload via file_path, link via media_ref. It does not name the sibling it differs from (add_media vs. attach/link), so sibling routing is left to inference rather than stated.

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

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

Gives explicit when-to-use conditions for each mode: file_path when uploading bytes, media_ref "when the same document supports several people." Also supplies a caution ("don't point at files you don't want copied") and a strong anti-pattern (uploading the same photo separately for husband and wife creates duplicates). This is real conditional guidance, not vague context.

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 write/non-idempotent/non-destructive, and the description adds genuinely beyond them: it explains that a ChildRef citation asserts BOTH sides of the link, and that reusing a citation handle causes the link to inherit a confidence 'its evidence never earned.' This is real semantic context about the object created.

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 justification, then the single-parent caveat. The confidence-inheritance sentence is long but earns its place by explaining the rationale for not reusing a handle. No redundant restatement of the name.

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

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

For a 3-param mutation tool with annotations and no output schema, the description covers the essential caveats: what the citation asserts, why not to reuse a handle, and the single-parent edge case. Nothing critical is missing 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 baseline is 3. The description adds meaning on top: the citation parameter is 'the PARENTAGE claim,' and it warns to create a new citation rather than reuse a handle, which sharpens how the citation param should be populated beyond the schema's own precedence 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?

States a specific verb and resource: 'Cite the parent-child link itself, on the family's ChildRef.' It sharply distinguishes this claim ('child belongs to these parents') from the adjacent claim ('child appears in this record'), so an agent grasps the target object. It stops short of naming any sibling tool (e.g., add_child_to_family, cite_object), so sibling routing is inferred rather than explicit.

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

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

Gives clear when-not guidance: do not reuse the child's existing citation handle, and 'Where only one parent is evidenced, cite that parent's relationship instead of implying both.' That routes the agent away from a wrong call. It never names an alternative tool to use in those cases, so it is implicit routing rather than explicit tool selection.

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

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

Beyond the annotations (which already signal a safe, non-destructive write), it discloses that the citation is resolved-or-created and appended to the citation list, that duplicates are suppressed, and that no other event field is modified. This is useful mutation context. The only nuance is mild tension between "no duplicates" and idempotentHint=false, but it does not rise to a contradiction.

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 in the first sentence, followed by usage and then mutation behavior. Every sentence earns its place: scope, when-to-use examples, resolution behavior, and the no-side-effects guarantee, with no filler.

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

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

For a two-parameter mutation tool with a nested citation object and no output schema, the description covers purpose, usage, and side-effect behavior adequately. It is nearly complete; the only unaddressed element is what the call returns, which is a minor gap given the mutation nature of the tool.

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

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

Schema description coverage is 100%, so both parameters and the nested CitationInput (including its precedence rules) are already fully documented in the schema. The description restates the resolution modes ("existing handle/id, or an inline source_title + page + confidence") without adding format or precedence detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (attach) and resource (citation to an event) with a scoping qualifier ("that ALREADY exists"), which cleanly separates it from event-creation tools like add_event. It does not explicitly contrast against the obvious siblings cite_object (generic) or cite_child_link, so an agent must infer the tiebreak rather than being routed to the right sibling.

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

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

"Use this to source an event you didn't create with an inline citation" gives clear when-to-use context, reinforced with concrete examples (Gramps web UI events, results from list_unsourced_facts). However, it names no alternative tool and states no exclusions, so the agent isn't told when to prefer cite_object or how to handle events it did create.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds genuine domain behavior: what a citation on a FAMILY actually asserts (a couple claim) versus a person-level identity claim. It omits that repeated calls create duplicate citations (non-idempotent), a minor gap against the annotation.

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

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

Front-loaded with the core verb+scope, then progressively adds routing detail. Each sentence carries distinct information, though the family/person elaboration is dense and could be tightened slightly.

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 none is needed for an attach operation, and the schema fully documents parameters. The description completes the picture by mapping each object type to the claim it supports. It could note idempotency behavior on repeat calls, but otherwise nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema's flat object_type list by explaining the semantic weight of each target type and which citation is preferred per object, adding real meaning to the object_type parameter.

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

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

States a specific verb+resource ('Attach a citation to any object') and immediately scopes it against siblings: cite_event covers facts, cite_child_link covers parent-child links. An agent can route to this tool 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 (family-level and person-level claims that no event makes), when-not (prefer citing the specific event where one exists), and named alternatives (cite_event, cite_child_link). This is textbook routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds return-shape behavior that the annotations cannot: per-event citation count and confidence, plus an aggregate uncited_count. It does not mention ordering or how the merge resolves conflicting dates, which would be the remaining behavioral detail for a merge tool.

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

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

Three sentences, front-loaded with purpose, then intent, then output characteristics. The middle sentence earns its place by grounding the tool in real use cases, though it could be tightened slightly.

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, no-output-schema tool, the description supplies meaningful return context (citation count, confidence, uncited_count) and the merge intent. It stops short of describing event ordering or deduplication across merged subjects, which is the one gap an agent might wonder about.

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

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

Schema description coverage is 100%, so all six parameters including targets, anchor, and include_private are already documented in the schema. The description adds no syntax, format, or cardinality detail beyond what the schema states, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Merge several people or families into one chronological timeline') and clarifies the semantics of the merge (one unified timeline rather than separate ones). It also positions itself against the sibling get_timeline by noting output parity, so an agent can distinguish 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?

It gives two concrete when-to-use scenarios: watching a household move through censuses, and checking family event consistency. This is clear context, but there is no explicit when-not guidance or named alternative to pick instead (it only references get_timeline for output parity, not as a routing choice).

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

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

Annotations only cover readOnly/openWorld, so the description does the heavy lifting: it discloses that results are UNTRUSTED hints, that each fact is flagged for whether a source was attached (with source text), and that probably-living people are withheld and counted. This is exactly the behavioral context an agent needs to interpret and trust the output correctly.

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 statement, then the trust model and workflow directive. Every sentence carries information, though the source-flag sentence is a slightly long construction that could be tightened without losing meaning.

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

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

For a read-only search tool with no output schema, the description adequately explains what comes back (per-file individuals, facts, source flags) and the privacy behavior. It does not discuss result limits, pagination, or how many files are scanned, which is a minor remaining gap.

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

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

Schema description coverage is 100%, so the four parameters are already fully documented in the schema; the description adds no syntax or matching detail beyond it. It does clarify why include_private matters ('Probably-living people are withheld and counted'), but that is general context rather than added per-parameter semantics.

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

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

States a specific verb ('consult') and resource ('legacy GEDCOM reference layer') and immediately scopes it: it searches configured Ancestry/FamilySearch exports and returns matching individuals and claimed facts. This clearly distinguishes it from siblings like search_people/query_records, which operate on the tree itself rather than the external reference layer.

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 when to use the results ('use them to decide what real record to hunt for, then create the fact in the tree citing that record') and when not to ('do not copy a hint in as a sourced fact'). The authoritative-vs-hint distinction tells the agent exactly how this tool fits into the citation workflow without naming every sibling.

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 the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the bar is lowered. The description adds the value proposition of naming a filter for reuse but says nothing about name collisions, persistence scope, or failure modes for a write operation.

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

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

Two sentences with the action front-loaded ('Save a reusable custom filter'), and the second sentence earns its place by justifying the tool's existence. Slightly wordy but no waste.

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

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

For a create tool with no output schema, 100% schema coverage and annotations carry most of the burden; the description adds the motivating rationale. It is nearly complete, only missing a pointer to list_filter_rules for valid rule names.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the namespace enum-like list and rule structure. The description adds no parameter syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Save a reusable custom filter' built from Gramps rules. Clear what it does, but it never names the sibling tools (list_custom_filters, delete_filter) that would let an agent place it in the filter lifecycle without opening schemas.

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

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

Gives a motivating condition — 'a selection you will run repeatedly — an audit scope, a branch of the tree' — which implies usage context. However it names no alternatives and no prerequisites; it does not say that rule names must first come from list_filter_rules or how this differs from simply querying.

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 openWorldHint=false, so the safety profile is covered. The description adds the scope 'in the tree' and the overview-check framing, but nothing about return shape (e.g., a per-type count mapping) or whether it includes soft-deleted/private objects.

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

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

Two sentences, front-loaded with the resource list and tailed with the purpose. The nine-item enumeration is long but each item is load-bearing since it defines the result's coverage.

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

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

For a zero-parameter, read-only counting tool with annotations covering safety, the description is nearly sufficient; the only minor gap is not hinting at the response shape (counts keyed by object type), which is easily inferred from the enumeration.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric an empty schema sets a baseline of 4.

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 (counts) and enumerates exactly which resources are counted (people, families, events, citations, sources, repositories, places, media, notes), which distinguishes it from aggregation siblings like verify_tree or run_report. It stops short of naming a sibling explicitly, so it lands just below top marks.

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

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

The trailing phrase 'A quick health/overview check' implies when an agent would reach for this tool, but there is no explicit when-to-use vs when-not, and no alternatives (e.g., query_records, verify_tree) are named for deeper analysis.

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 readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful blast-radius context beyond that: only the filter definition is removed and no tree objects are affected. It doesn't state behavior when the filter doesn't exist or whether the deletion is undoable, which would complete the picture.

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

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

Two short sentences, zero filler, with the core action front-loaded and the scope constraint immediately after. Every sentence earns its place.

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

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

For a simple two-parameter deletion with full annotation coverage and no output schema, the definition gives the agent what it needs to call it safely, including the key reassurance about tree data. It stops short of noting idempotency or recoverability, which the idempotentHint=false annotation leaves open.

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

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

Schema description coverage is 100% and both parameters (name, namespace) are documented in the schema with examples. The description adds no additional meaning to either parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a saved custom filter') that clearly separates it from creation/list siblings like create_filter and list_custom_filters. The added scope line 'Nothing in the tree is touched' further distinguishes it from the broader delete_object sibling, though no sibling is named explicitly.

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

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

Usage is implied by the narrow object of deletion (a saved filter definition), and the clarification that tree data is unaffected gives context for choosing it over delete_object. However there is no explicit when-to-use, when-not-to-use, or named alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real substance beyond them: irreversibility, the fact that references are NOT cleaned up, and a concrete example (a person still referenced by a family). That is exactly the extra context an agent needs before a destructive call.

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

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

Front-loads the action and the destructive nature in the first two lines, with the caveat and remediation guidance after. The sentence on dangling references is somewhat long but each clause carries actionable information; little waste overall.

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 a small two-parameter schema, full schema coverage, no output schema, and annotations covering the safety profile, the description is nearly complete for correct invocation. It could still mention whether the object handle becomes invalid or whether an undo exists, which would close the remaining gap.

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

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

Schema coverage is 100%, so both parameters and their accepted identity forms are already documented in the schema. The description's 'handle or gramps_id' phrasing restates the schema rather than adding new semantics, so baseline 3 applies.

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

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

States a specific verb (permanently delete) and resource (object from the tree) plus the two accepted identifiers (handle or gramps_id). The warning about dangling references implicitly distinguishes it from detach_object, but no sibling is named explicitly, so an agent must infer the boundary.

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

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

Gives concrete when-not guidance: prefer deleting leaf objects and detach references first where possible. That steers the agent away from this tool in the risky case, though it never names detach_object or merge_objects as the literal alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds substantial behavioral context beyond annotations: the referenced object survives by default, deletion only happens if delete_if_orphan is set AND no other references point to it, and this orphan check exists to avoid dangling handles. That is exactly the kind of operational nuance an agent needs for a destructive mutation.

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

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

Two short paragraphs, front-loaded with the core purpose and then the critical conditional-deletion behavior. Every sentence carries information; there is no filler or repetition.

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

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

For a destructive mutation tool with no output schema, the description covers the essential behavior: references are removed, objects survive by default, and deletion is conditional and checked. It does not describe failure modes such as a missing reference, but the annotations and schema carry enough of the remaining burden that the definition is largely complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the child_kind examples and, more importantly, explains the rationale and guard condition behind delete_if_orphan beyond the schema's wording ('which is checked, because deleting something other facts still reference leaves dangling handles behind'). This adds useful semantic depth, though most parameter detail still 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?

The description states a specific verb and resource: remove a reference from an object, with concrete examples (event from person, image from source, tag, note, child from family). It clearly distinguishes detaching from deleting an object, so an agent can differentiate it from sibling tools like delete_object or uncite without opening schemas.

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

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

The description gives clear context for when to use this tool: to remove a reference while preserving the underlying object. It also explains the conditional delete_if_orphan behavior, which helps distinguish detaching from deleting. However, it does not explicitly name alternative tools or state when-not to use this tool versus siblings.

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 openWorldHint=false, so the safety profile is covered. The description adds that the result is derived arithmetic over formatted dates and that manual computation invites transcription errors, which frames it as a deterministic calculation, but says nothing about error handling for unparseable or imprecise dates.

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

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

Three short sentences, front-loaded with the operation and followed by rationale; nothing is redundant. The third sentence is motivation rather than specification, so it is close to but not quite maximally economical.

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 should describe the returned value, especially how as_age and precision shape it (interval vs. age, units included). That gap leaves an agent unsure what it will actually receive, though the core operation is fully described.

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 as_age, precision, and the event handles are already documented in the schema; baseline 3 applies. The description actually refers to 'two formatted date strings' while the parameters are event handles or gramps_ids, a mild imprecision it never resolves.

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: 'Measure the elapsed time between two events,' which is unambiguous about what the tool computes. It does not, however, distinguish itself from timeline-flavored siblings like consolidated_timeline or get_timeline, so an agent must infer the boundary itself.

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

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

The second sentence gives concrete usage contexts ('age at marriage, years between a census and a death') that tell an agent when this tool is the right choice. There is no explicit when-not guidance or named alternative, keeping it short of the top band.

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

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

Annotations already declare this is a non-read, non-destructive, non-idempotent write, and the description is consistent with that. It adds behavior beyond the annotations: the output is a single full-tree file, the operation is fast ('a few seconds'), and the dump can be re-imported to recover from a botched bulk write. It stops short of stating what the call returns or required permissions.

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 imperative action is front-loaded in the first sentence and the trigger condition follows immediately. The 'cheap insurance' framing is mildly rhetorical but it carries real justification (low cost, high recovery value) rather than padding.

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

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

For a two-parameter write tool with no output schema, the description covers why and when to call it, but does not say what the call returns (e.g., the path of the written file), which is the one piece an agent calling it blind would want.

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

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

Schema description coverage is 100%, so both dest_path and export_format are already fully documented in the schema, including the never-overwrite rule and format trade-offs. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The opening sentence gives a specific verb and resource with scope: 'Write a full-tree export to disk.' The scope word 'full-tree' separates it from partial or object-level operations, and no sibling tool performs exports, so the agent can identify it immediately 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?

It gives an explicit invocation trigger: 'Take one before any bulk write,' and explains why (a failed bulk write cannot always be undone transaction by transaction). No alternative or exclusion is named, but none exists in the sibling set, so the guidance is actionable even if not framed as a comparison.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds operational detail beyond that by clarifying that read-only means "never merges" and that output is candidate groups, not decisions. It also explains the evidentiary rationale for why the tool errs toward caution. No mention of permissions, cost, or performance characteristics.

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 action and its scope in the first sentence. The middle sentences are editorial but functional — they justify why duplicate detection is non-trivial and warn against over-merging. It runs slightly long for the functional payload, but every sentence carries usable guidance.

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

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

For a read-only search tool with full schema coverage and no output schema, the description covers the detection/decision boundary and points at merge_objects for follow-through. It does not describe the shape of the returned report (the grouping is only implied by the limit parameter's "Max groups to return"), which is a minor gap.

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

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

Schema description coverage is 100%, so the kind enum values, limit, and include_private are all documented in the schema itself, including the privacy default. The description text adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb + resource ("Find likely-duplicate objects") and immediately scopes the behavior ("Reports only -- it never merges anything"). It explicitly names the sibling it is not (merge_objects), so an agent can separate detection from mutation without opening either schema.

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

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

Gives clear conditions: this tool produces candidates, the human decides which are truly the same, and merge_objects performs the merge. It supplies the false-positive caution (index entry vs. register page must stay separate), which is real usage guidance. It stops short of explicit when-not triggers against other read tools like verify_tree or list_unsourced_facts.

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 say the call is read-only and closed-world; the description adds the substantive behavior that living/private ancestors are returned as redacted stubs unless include_private is set. That is real value beyond the structured fields, though nothing is said about depth limits on the returned tree or performance.

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

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

Two short sentences, no filler. The core traversal purpose is front-loaded and the privacy caveat follows, which is the right order for an agent deciding whether to call 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 read-only tree traversal with fully documented parameters and no output schema, the description covers purpose, output shape, and the privacy caveat. It is nearly complete, missing only guidance on when this tool is the right choice over the neighboring lookup tools.

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 all three parameters carry their own descriptions, so the schema already does the work. The description's privacy sentence corroborates the include_private semantics but adds no syntax, defaults, or bounds beyond what the schema states.

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

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

States a specific verb and resource ('Walk a person's ancestors up to N generations') and even characterizes the return shape ('a nested parents tree'). The ancestor/descendant split makes it unambiguously distinct from get_descendants without naming it.

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

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

The description implies the traversal use case and clarifies the privacy condition, but never states when to prefer this over get_person, get_family, get_relationship, or get_descendants. Usage is inferable rather than explicit.

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 openWorldHint=false, so safety is covered. The description adds meaningful domain semantics beyond that: results are grouped by type, and an object with zero backlinks is orphaned while one with backlinks will produce dangling references if deleted. It omits return format or error behavior, keeping it at a 4.

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 core action is front-loaded in the first sentence, and the three example questions are compact and each earn their place by illustrating a distinct use case. Slightly verbose but no dead weight.

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

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

For a read-only listing tool with no output schema, the description supplies the key semantic hints — grouping by type and the orphaned/dangling-reference meaning of results. It leaves minor gaps around output shape and invalid-reference behavior, but nothing critical for correct invocation.

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

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

Schema description coverage is 100% for both parameters (ref, object_type), so the schema already carries the burden. The description adds no detail on parameter format, valid object_type values, or how 'ref' accepts a handle versus a gramps_id — baseline 3 applies.

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

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

The description states a specific verb and resource ('List everything that references this object, grouped by type'), which is unambiguous and clearly distinct from direct object fetchers like get_object or query_objects. It does not name a sibling alternative, but the use-case framing effectively separates it from the surrounding lookup tools.

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 three concrete trigger scenarios (citation checking, fact provenance, deletion safety) that make the when-to-use condition explicit. It stops short of stating when NOT to use it or naming an alternative tool, so it falls just under full marks.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds value by explaining the returned fields and interpreting `cited_by_count` zero as orphan debris, which helps an agent understand the result beyond the annotation.

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

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

The description is two short paragraphs, front-loading the core action and then the key field interpretation. Every sentence earns its place without fluff.

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

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

For a simple read tool with one documented parameter and read-only annotations, the description covers the returned fields and the meaning of the important count. It does not cover error behavior, but no output schema exists and the annotations handle safety.

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

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

Schema description coverage is 100% for the single `citation` parameter, so the schema already documents handle or gramps_id. The description adds no additional parameter semantics.

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

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

The description opens with a specific verb and resource ('Read one citation') and enumerates the fields returned (page, confidence, date, source). It is clear, though it does not explicitly differentiate itself from other get_* sibling tools beyond the resource noun.

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 provides implied usage by highlighting `cited_by_count` as the useful part and explaining that zero indicates orphan debris that `uncite` should have removed. It does not explicitly state when to choose this tool over alternatives like `get_source` or `query_objects`.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context: the return value is a nested children tree, and living/private descendants are silently redacted to stubs by default. That redaction default is exactly the kind of non-obvious behavior an agent needs before summarizing output.

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

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

Two sentences, zero filler. The core action is front-loaded in the first sentence and the privacy caveat follows immediately where it matters.

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

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

With no output schema, the description usefully describes the returned structure (nested children tree with redacted stubs) and the privacy default, which is enough for correct invocation. It does not mention depth limits or what happens for a nonexistent root person, but those are covered by the schema's min/max constraints.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond by framing 'generations' as a downward walk depth and by explaining the practical consequence of include_private (redacted stubs vs. full records), which the schema states only as 'show ... in full'.

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 ('walk') and resource ('a person's descendants'), plus the result shape ('a nested children tree'). The distinction from the sibling get_ancestors is carried by the word 'descendants' rather than an explicit contrast, so it is clear but not maximally differentiated.

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

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

Usage is implied by the scope statement ('up to N generations') and the privacy note, but the description never says when to reach for this versus get_person, get_family, or get_ancestors, nor does it name an alternative. The only quasi-guidance ('unless include_private is set') duplicates what the schema already states.

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 openWorldHint=false, so safety is covered. The description adds valuable return-value context: each match reports total shared cM, largest segment, and any common ancestor, plus it explains the interpretive meaning of the data. It stops short of describing pagination, sorting, or the effect of include_raw.

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 front-loads the core purpose in the first sentence, then adds output details and domain caveats. It is somewhat prose-heavy, but the additional context about DNA evidence and `unattributed_count` earns its place for correct interpretation.

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 burden of explaining return values, and it does so by naming total shared cM, largest segment, common ancestor, and unattributed_count. It omits any mention of include_raw, but the input schema covers that parameter, so the definition is largely complete for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including person and include_raw. The description does not add any parameter-specific syntax, format, or edge-case meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the DNA matches recorded against a person.' It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools such as get_ydna or parse_dna_segments.

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

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

The description provides useful context about DNA evidence and points to `unattributed_count` as the key number for open research. However, it does not state when to use this tool versus alternatives like get_ydna, nor does it give explicit prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds the list of returned fields, which is useful behavioral context, but says nothing about behavior on a missing/invalid handle or any output/pagination characteristics.

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

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

Two tight sentences, front-loaded with the purpose and closed with the usage cue; no filler or redundancy.

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

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

For a simple read-only single-param tool with full schema coverage and annotations covering the safety profile, the description is largely sufficient, especially since it lists the return fields despite there being no output schema. Only edge-case behavior on invalid handles is unaddressed.

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

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

With a single parameter and 100% schema description coverage, the schema already documents 'event' with an example ('E0001'), so the baseline is 3. The description adds no additional syntax or format guidance beyond what the schema provides.

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

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

States a specific verb and resource ('Get an event') and enumerates the returned fields (type, date, place handle, description, citation count, attributes), so the agent knows exactly what this retrieves. It is clearly distinguishable from list_event_types, update_event, and query_objects, though it never explicitly contrasts itself with the generic get_object sibling.

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

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

'Use to inspect an event before citing or editing it' gives concrete workflow context that tells the agent when this tool is appropriate (a pre-read for cite/edit flows). It stops short of naming alternatives or stating exclusions, so it is clear context without routing 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 readOnly/openWorld annotations, the description discloses real behavioral traits: living and private people are withheld unless include_private is set, and the call is slow because the server computes everything per call. These are genuine operational facts an agent needs and are not captured by annotations.

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

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

Front-loaded with the core output definition, then one line each for scope, plausibility use, privacy behavior, and performance. No filler; every sentence carries distinct information.

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

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

For a read-only tool with no output schema, it conveys the kind of results returned, the exclusion rule, and the performance cost. It lacks a full enumeration of all statistics produced and pagination/ranking return detail, but is otherwise sufficient to call 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 rank, person, person_filter, and include_private are already documented in the schema. The description restates the include_private exclusion behavior but adds no syntax or format meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (the tree's record-holders) and enumerates concrete outputs — oldest at death, youngest parent, most children. The clause 'Superlatives across a set of people, not statistics about one person' crisply distinguishes it from single-person stat tools like db_stats or get_person.

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 clear when-to-use scenario: an implausible holder signals a data error, making this a quick plausibility check. It does not name specific sibling alternatives (e.g. verify_tree, db_stats) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by naming the shape of the result (relationship type, parent/child handles, event count), which is the only output contract available since no output schema exists. It does not say what happens for an unknown handle, but that is a minor omission.

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

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

One sentence, front-loaded with the verb and resource, followed immediately by the result contents. Every clause earns its place; nothing is redundant or padded.

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

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

For a single-parameter read tool with full schema coverage and safety annotations, the description supplies everything an agent needs: identity, input form, and a summary of return fields. Only error behavior for a missing family is left unstated, which is a small gap.

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

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

Schema description coverage is 100% and the single 'family' parameter is documented as accepting a family handle or gramps_id with an example. The description adds nothing beyond what the schema already says, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Get a family') and enumerates the returned fields (relationship type, parent handles, child handles, event count), which clearly separates it from get_person, get_event, and add_family. It stops short of explicitly naming a sibling it is not, so it lands just below the top band.

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

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

There is no when-to-use guidance, no prerequisite (e.g. that a family handle/gramps_id must already be known), and no pointer to alternatives like search_people or get_relationship. With ~70 sibling tools, the agent gets no routing help at all.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful interpretation context beyond that: that referenced_by_count>1 is normal, and that shared checksums indicate duplicates. It omits failure behavior (e.g., missing handle) but that is a minor gap.

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

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

The first line is tightly front-loaded and efficient. The second paragraph is somewhat tangential for a single-object read (explaining aggregate referenced_by_count semantics) but still earns its place as interpretation guidance.

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

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

With no output schema, the description compensates by enumerating the returned fields, and the annotations cover safety. For a one-parameter read tool this is nearly complete; only error/absence handling is unaddressed.

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

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

Schema description coverage is 100% and the single 'media' parameter is documented in the schema as a handle or gramps_id. The description adds no parameter detail beyond the returned-field list, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one media object') and enumerates the returned fields (path, mime type, checksum, description, date), which clearly separates it from add_media, update_media, and ocr_media siblings.

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

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

Usage is implied by 'Read one media object' and the checksum sentence implicitly routes duplicate hunting to find_duplicates(kind='media_checksum'). However there is no explicit statement of when to prefer get_media over get_object, query_objects, or other retrieval siblings, nor any prerequisites.

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 openWorldHint=false, so the safety profile is covered. The description usefully adds that the text is returned untruncated and that type/attachment metadata is included, but says nothing about permissions, error behavior for a bad handle, or response shape.

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

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

Two short sentences, front-loaded with the action and followed by a rationale for why the full text matters. The second sentence is explanatory rather than operational, but it is brief and does justify itself.

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

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

For a single-parameter, read-only getter with no output schema, the description covers the essentials: what is read, that it is complete rather than truncated, and what metadata accompanies the text. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single 'note' parameter is documented as 'Handle or gramps_id of the note.' The description adds no syntax, format, or lookup-rule detail beyond that, so the baseline 3 for schema-documented parameters is correct.

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

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

The description states a specific verb and resource ('Read one note in full') and even names what the response carries (its type and what it is attached to), so an agent knows exactly what it gets. It does not, however, distinguish itself from sibling getters like get_object or query_objects, which is the only thing keeping it from a 5.

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

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

Usage is implied rather than stated: 'comes back whole rather than truncated' hints that this is the tool to reach for when complete note text matters, but there is no explicit when-to-use or when-not-to-use rule and no named alternative (get_object, query_objects). Adequate but leaves the routing decision 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 openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing that the return is the raw stored record rather than a shaped view, which is the key behavioral distinction motivating its use. It stops short of describing error handling for a missing ref or the effect of the keys field, which keeps it out of the top band.

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

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

Three short sentences, front-loaded with the core capability and its scope before the advice on alternatives. No sentence is redundant and the routing hint lands last where it is most useful.

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

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

For a read-only lookup with full schema coverage and no output schema, the description covers purpose, scope and the alternative-tool decision well. It leaves minor gaps around failure behavior for an unknown ref and how keys interacts with the 'raw record' promise, but nothing that would cause a misinvocation.

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

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

Schema description coverage is 100%, so all three parameters (object_type, ref, keys) are already documented in the schema, including the 'handle or gramps_id' format and the comma-separated fields semantics. The description adds only the framing of 'raw record' versus a shaped getter and no additional parameter detail, so the baseline 3 applies.

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

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

It states a specific verb and resource ('Read any object's raw record') and immediately delimits scope by naming the object types it uniquely serves (places, media, notes, citations). It also distinguishes itself from the shaped getters get_person and get_source, so an agent can route correctly 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?

It gives an explicit use condition ('what you want before editing one') and names the alternatives with the condition that selects them ('for people and sources the shaped getters ... are easier to read'). The selection rule between get_object and its siblings is fully specified.

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 openWorldHint=false, so safety is covered structurally. The description adds genuinely non-obvious behavior the annotations cannot express: single-object lookups bypass the living/private filter that bulk/list tools apply. It stops short of noting error behavior for an unknown handle or result-size limits.

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

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

Three short sentences, front-loaded with the return payload and followed by the privacy rule and usage triggers. The parenthetical '(this is your own local tool)' is mildly redundant, but nothing else wastes space.

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

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

With no output schema, the description usefully enumerates the returned fields, and it covers the one non-obvious behavioral rule for this tool. Missing only minor details such as failure mode on a bad handle or how citation counts are scoped.

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

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

Only one parameter with 100% schema description coverage, including the example handle 'I0001', so the schema does the heavy lifting. The description adds only the implication of a single-valued lookup, which is the baseline case.

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 (get) and resource (person) and enumerates the exact payload: name, gender, events with citation counts, family links, media count. An agent can distinguish this from get_family, get_object or search_people 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 two concrete triggers: inspecting someone before adding facts, and checking whether an event is already cited. It also carves out the privacy boundary versus bulk/list siblings, though it never names a specific alternative tool the way an explicit when/when-not statement would.

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 openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them by explaining that `enclosed_by` is the jurisdictional chain and that an empty chain marks an orphaned, event-minted place, which helps the agent interpret results. It does not cover failure behavior for an unknown handle.

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

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

Two short paragraphs, with the core purpose front-loaded in the first sentence. The second paragraph earns its space by explaining a non-obvious returned field, though it could be tightened slightly.

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 carries the return-shape burden by listing the fields. For a one-parameter read tool that is close to complete; only error/not-found behavior and the coordinate format are left unstated.

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

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

Schema description coverage is 100% and the single `place` parameter is documented as 'Handle or gramps_id'. The description's use of 'handles' loosely corroborates the input but adds no format, resolution, or ambiguity-handling detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one place') and enumerates what comes back: name, title, type, enclosure, coordinates and URLs. This clearly separates it from the write siblings (add_place, update_place) and from other get_* readers on different resource types.

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

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

Usage is implied by the verb and the required `place` handle, but the description never states when to reach for this versus get_object/query_objects or how it pairs with update_place. The second paragraph tells the agent how to interpret one returned field, not when to call the 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 already cover the safety profile (readOnlyHint, openWorldHint=false), so the bar is lower, yet the description still adds real behavioral context: the textual response form, the generation-distance output, and the meaning of a negative result bounded by search depth. It does not say what happens on an unknown handle or how depth defaulting behaves, keeping it out of the top band.

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

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

Three short sentences with the core operation front-loaded, followed by the return shape and the negative-case caveat. No filler and nothing that repeats structured fields verbatim.

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 takes on the return semantics (relationship wording plus generation distance to the common ancestor) and the false case. It is nearly complete; only error behavior for invalid handles and the effect of an omitted depth are unstated.

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

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

Schema description coverage is 100%, including a good description of `all_paths` and the person handle/gramps_id formats, so the schema carries the burden. The description only indirectly gestures at the `depth` parameter via the search-depth note and adds no format or constraint detail beyond the schema.

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

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

State a specific verb and resource: computing the relationship between two named people. It is clearly distinct in substance from single-person readers like get_ancestors, get_descendants and get_family, but it never names a sibling or otherwise explicitly delineates itself from them.

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

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

Usage is implied rather than stated. The description usefully explains that a false `related` result is itself informative when a relationship was expected, which guides interpretation, but it gives no explicit when-to-use vs. alternatives (e.g. get_ancestors for one-sided lineage) and no indication of how `depth` should be chosen.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: reports accept a full option dict, not a partial one, which changes how a caller must use the result. It doesn't describe the shape or size of the returned option dict.

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

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

Two short sentences, front-loaded with the action, and the second sentence earns its place by explaining the non-obvious full-dict constraint. No padding.

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

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

For a one-parameter read tool with a full annotation set and no output schema, the description covers purpose and the key usage constraint adequately. The only gap is that it doesn't indicate what the returned options dict looks like or how to use it in a follow-up run_report call.

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

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

Schema description coverage is 100% for the single report_id parameter, which the schema already documents with an example. The description adds no syntax, format, or lookup guidance for report_id, so the baseline 3 applies.

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

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

The description gives a precise verb (read) and resource (one report's default options), and the phrase 'before running it' implicitly separates it from run_report and list_reports in the sibling set. It stops short of naming those siblings explicitly, so an agent must infer the routing rather than being told.

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?

Clear context for when to call it: before running a report, and specifically when you want to change one setting. It doesn't name an alternative tool or state exclusions, but the workflow condition that selects this tool is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful return-content context (name, type, URLs, address count, source count) in the absence of an output schema, but says nothing about lookup failure behavior or handle resolution.

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

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

One efficient, front-loaded sentence with no filler; the verb comes first and the returned fields follow compactly. The '(if available)' hedge is the only slightly loose element.

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

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

For a single-parameter read tool with full schema coverage and safety annotations, the description covers the important unknown (what comes back). It would be complete at 5 with a note on missing-handle behavior, but nothing essential 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 description coverage is 100% and the single 'repository' parameter is fully documented in the schema with a handle/gramps_id example. The description adds no parameter syntax or format detail beyond that, so the baseline 3 applies.

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

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

Clear verb+resource ('Get a repository') and it enumerates the returned fields, so the agent knows exactly what it retrieves. However, it does not distinguish itself from generic siblings such as get_object or query_records, which could also fetch a repository.

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

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

No statement of when to use this vs get_object, query_records, or query_objects. The agent is left to infer that this is the repository-specific fetch, with no exclusions or prerequisites given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context that this data is embedded in every export and travels with GEDCOM/Gramps XML, but says nothing about the returned fields or scope of the read. A 3 is appropriate given annotations carry the behavioral load.

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

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

Two sentences, front-loaded with the action, and every sentence contributes (what it reads, why it matters). Slightly more prose than strictly needed for the export-embedding point, but no filler.

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

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

For a zero-parameter read tool with no output schema, the description covers what it returns (researcher metadata), why it exists, and when to check it. Only the specific returned fields are unstated, a minor gap.

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

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

The tool takes zero parameters, so there is no parameter meaning to convey. Baseline 4 applies; the description correctly does not invent parameter semantics.

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

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

States a clear verb ('Read') and resource ('the researcher details recorded for this tree'), which is distinct from the person/family/place get_* siblings. It does not explicitly contrast itself with any sibling, but the resource is specific enough that an agent can tell it apart.

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

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

Gives a concrete when-to-use signal: check it 'before sharing' an export. It does not name when-not to use it or point at alternatives, but the triggering context is explicit and actionable.

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 openWorldHint=false, so the safety profile is covered. The description adds useful return-field context but does not disclose deeper behavioral traits such as error handling, authentication needs, or rate limits.

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

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

The definition is two sentences, front-loads the core purpose and return contents, and follows with a concise usage note. Every phrase earns its place.

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

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

No output schema exists, but the description explicitly lists the returned data fields, compensating well. Annotations cover the safe-read nature, and the usage sentence tells the agent when to reach for it.

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

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

Schema description coverage is 100%; the single 'source' parameter is documented with an example handle ('S0001'). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('a source'), then enumerates the fields returned. This clearly distinguishes it from sibling getters for other object types and from mutation tools like add_source or update_source.

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 a clear context for use: 'inspect a source before citing through it or editing it.' That tells the agent when this tool is relevant, though it does not explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds important async behavior: those operations answer before completion. It discloses the polling requirement and the relevant result fields (`finished`, `succeeded`), which is exactly what an agent needs for a job-status tool.

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

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

The description is front-loaded with the core purpose, then efficiently adds async context, polling instructions, and a warning. Every sentence contributes to correct invocation, and there is no redundant or filler text.

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

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

For a read-only polling tool with one fully documented parameter and no output schema, the description supplies the missing return semantics by naming `finished` and `succeeded`. It also explains the broader workflow that necessitates polling, making the definition complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so the `task_id` parameter is already documented in the schema, including an example link to `undo_transaction` or `verify_tree`. The description does not add new syntax, format, or constraint details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: check whether a background job has finished and whether it worked. It distinguishes this from sibling operations by explaining that get_task retrieves the result of dispatched async work, not the work itself.

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 names the operations that require polling: undo, verification, import, and reindex. It then gives concrete usage instructions: poll until `finished` is true, then read `succeeded`, and warns against submitting such operations without checking the result.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: each entry carries age at the time, citation counts, strongest confidence, and an 'uncited_count' that signals how much of the timeline rests on no evidence. That audit-oriented framing is useful, though it says nothing about ordering ties, pagination, or how many events come back.

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

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

The purpose is front-loaded in the first sentence and the remainder is spent on return-value semantics rather than filler. The second sentence is slightly ornate ('doubles as a readable audit of where the evidence thins out') but it does carry information.

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

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

With no output schema, the description usefully compensates by describing the shape and meaning of each entry and of 'uncited_count'. Combined with a fully documented schema and read-only annotations, an agent has enough to call it correctly, though the family mode and generational folding behavior remain unexplained.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description adds nothing about 'target' resolution, 'object_type', or the ancestor/offspring folding semantics, and 'uncited_count' it references is a return field rather than a parameter.

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: 'Build a chronological timeline of someone's life events.' That is far more informative than a tautology, but it never distinguishes itself from the sibling tool 'consolidated_timeline', which appears to serve an overlapping purpose. Without that differentiation the agent cannot reliably choose between the two.

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

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

There is no when-to-use guidance, no stated prerequisites, and no mention of when to prefer 'consolidated_timeline' or 'get_ancestors'/'get_descendants' over folding ancestor/descendant events in here. The 'only when the user asks' note about private records is a parameter-level caution inside the schema, not usage routing in the description.

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 openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context the annotations do not: the return content includes the objects the transaction changed, and it implicitly links to the undo workflow. It stops short of describing the full response shape, but that is a minor gap against existing annotations.

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

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

Three short, front-loaded clauses with zero filler: definition first, sibling contrast second, operational advice last. Every sentence earns its place.

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

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