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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds value beyond that: it discloses that the primary name is untouched (scope of effect), that the citation attaches to the name rather than the person, and that the entry is reversible/correctable later. It omits return/confirmation behavior and any duplicate-name handling, which is a modest gap for a mutation 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 tight sentences with no filler: purpose first, then use cases, then the reversibility/alternative pointer. Every sentence earns its place and the most decision-relevant fact (primary name unchanged) is front-loaded.

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

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

Given rich annotations, a 100%-documented 9-parameter schema, and no output schema, the description supplies what the structured fields cannot: the non-destructive effect on the primary name and the sibling that handles later edits. Only the success/return behavior and duplicate-name handling are left implicit, which is acceptable absent an output schema.

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

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

Schema description coverage is 100% and every parameter carries a detailed description, so the baseline is 3. The description's 'cited to the record using it' restates the schema's citation semantics rather than adding new syntax or format guidance, so it neither compensates nor detracts.

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: adding an alternate (non-primary) name to a person. It explicitly distinguishes the non-primary scope ('The person's primary name is left unchanged') and names update_alternate_name as the distinct sibling for correcting/removing, so an agent can tell it apart from update_alternate_name and update_person 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 concrete usage contexts (maiden/married names, aliases, anglicized forms, nicknames-of-record) and routes the post-hoc correction path to update_alternate_name. It does not, however, state explicit exclusions (e.g., 'do not use this to change the primary name — use update_person'), so guidance is clear but not fully bounded.

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 full safety profile (readOnly=false, destructive=false, idempotent=false), so much of the disclosure burden is lifted. The description adds only the 'typed key/value' framing and no information on duplicate names, permissions, or failure behavior beyond what annotations and the allow_new_type schema field provide.

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

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

Two short sentences, front-loaded with the action and followed immediately by the disambiguating contrast. Every clause earns its place; nothing is repeated from the schema.

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

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

For a non-destructive mutation with full annotation coverage, 100% schema coverage, and no output schema, the definition is nearly sufficient. It could note what happens when an attribute name already exists on the target, but the essential call information is present.

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

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

Schema description coverage is 100%, so all five parameters including allow_new_type are already documented in the schema, including the near-miss refusal behavior. The description's 'typed' phrasing adds no syntax or format 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?

States a specific verb and resource ('Add a typed key/value attribute to an object'), and immediately contrasts with update_attribute, which is the closest sibling in the catalog. An agent can distinguish add vs. modify/remove 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?

Explicitly names the alternative tool (update_attribute) and the condition that selects it ('changes or removes one already there'), which is exactly the when-not guidance an agent needs. It does not cover the add_url/add_note siblings, but the primary routing decision is resolved.

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 mutating but non-destructive operation, and the description adds meaningful behavior beyond that: it links both directions (ChildRef on the family plus the family on the child's parent-family list), requires the child to pre-exist, and skips duplicates. The 'duplicate children are skipped' clause sits slightly awkwardly against idempotentHint=false, but it is not a direct contradiction and is useful context.

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

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

Four short sentences, front-loaded with the core action and then the side effect, prerequisite, and duplicate behavior. Every sentence carries information, and there is no filler.

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

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

For a mutation tool with five params, no output schema, and annotations covering the safety profile, the description is nearly complete: it covers purpose, side effects, prerequisite, and duplicate handling. It omits error conditions and does not touch on the nuanced allow_new_type behavior, but the schema covers that fully.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including frel, mrel, and allow_new_type. The description adds no parameter-level meaning beyond referring to 'existing' child and family, 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 and resource: 'Add an existing person as a child of an existing family.' It is immediately clear what the tool does, but it does not explicitly differentiate itself from siblings like update_child_ref, set_family_parent, or move_child, leaving the agent to 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?

The description provides a prerequisite ('The child must already exist') but does not say when to use this tool versus alternatives such as update_child_ref, move_child, or set_family_parent. Usage is implied rather than explicitly guided, which is the minimum viable level.

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

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

Annotations declare it is a non-read-only, non-idempotent, non-destructive, closed-world write, so the safety profile is already covered. The description adds real behavioral context beyond them: that a citation handle is reusable across facts, that a citation carries a single confidence (so reuse must match the claim), and that source_title causes a new source AND citation to be created as a side effect. It does not say what the call returns (a handle id), which is the one remaining behavioral 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?

Three sentences, front-loaded with the core action, followed by the routing guidance and the positive use case. No filler, no repetition of schema content, and the most important sentence (don't call this directly) comes first.

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-object create tool with a fully documented nested schema but no output schema, the description covers purpose, routing, and side effects well. The only thing an agent might still want is what the call returns (the new or reused citation handle) so it can pass it to later calls, since no output schema supplies that.

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

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

Schema description coverage is 100%, so the schema already documents every field, including the citation/source/source_title precedence rule. The description restates the reuse-vs-create distinction but adds no syntax, format, or constraint detail beyond what the CitationInput 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?

States a specific verb and resource ('Create a standalone Citation on a Source') plus the secondary mode ('or reuse an existing one'). The parenthetical immediately frames the two operating modes, and the following sentences distinguish it from the add_person/add_event_to_person/add_family 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?

Explicitly says when NOT to call it ('Usually you don't call this directly -- pass a CitationInput to add_person / add_event_to_person / add_family instead') and names the exact alternative tools. Then names the positive condition for calling it directly ('when you want a reusable citation handle to attach to several facts'). This is textbook when/when-not/alternatives 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 the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, and the description still adds real context: a validation gate ('Nothing is written unless the segments parse'), the storage format guarantee that get_dna_matches reads back, and the atomicity implied by refusing unparseable data. It does not state what the call returns or whether auth/permissions are required.

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

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

Three short paragraphs, front-loaded with the verb and resource before the mechanics and the caveat. Each paragraph carries information (validation, storage, relationship caveat), though the middle paragraph's format-compatibility explanation is slightly more than an agent needs to invoke the call.

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

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

For a non-idempotent write tool with no output schema, the description covers the essentials: what is recorded, that validation gates the write, that a new citation is minted, and how the result is read back via get_dna_matches. The main gap is the return value (e.g. the new match handle or transaction id), which nothing else documents.

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 four parameters in detail, including the CitationInput precedence rules. The description reinforces the citation parameter's meaning ('the test the match came from') and the segment-row format, but adds little 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?

The opening sentence gives a specific verb and resource ('Record a DNA match') plus the scoping constraint that it is cited to the test that found it. It implicitly distinguishes itself from the read-side sibling get_dna_matches, which it names as the reader. It does not, however, distinguish itself from closely related siblings like parse_dna_segments or add_citation, which an agent might also consider.

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 final paragraph gives explicit when-not guidance: 'A match proves the two share DNA, not how they are related. Record any relationship separately, with its own evidence.' That steers an agent away from a plausible misuse. It stops short of naming a concrete alternative tool (e.g. a relationship/event add) or noting that segments can be checked with parse_dna_segments first.

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/not-destructive/not-idempotent, and the description corroborates the non-idempotent profile by stating it is 'Refused if the person already has it.' It also discloses the shared-citation behavior of references, which annotations cannot express. It does not cover permissions/auth or what the call returns, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the verb and resource, then the scenario, then the routing rules. Every sentence carries distinct information with no repetition of schema content.

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

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

For a write tool with no output schema, it covers purpose, the sharing model, refusal behavior, and sibling routing — enough to invoke it correctly. The only omission is any hint of the return value or side effects on the tree, a minor gap given the annotations.

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 role, event, person, attributes and allow_new_type in detail. The description only alludes to the role concept ('in a role') and adds no format or constraint information beyond the schema. Baseline 3 applies.

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

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

States a specific verb (share/add a reference to) and resource (an EXISTING event) for a person in a role. It explicitly distinguishes itself from the two nearest siblings: 'update_event_ref edits that reference' and 'A new fact is add_event_to_person.' An agent can route correctly 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 a concrete when-to-use scenario (a census entry, residence or burial several people took part in) plus the rationale (shared citations and later corrections). It also states the when-not (refused if the person already has it) and names the correct alternatives for that case and for creating a new fact.

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 this is a non-destructive write. The description adds behavioral detail beyond that: the event is attached with the 'Family' role, and it should be cited to the establishing record. It does not discuss idempotency or what happens on duplicate events, but the added role/citation context is useful.

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 front-loaded sentences with the action first and purpose next; nothing is padding. The final citation sentence is slightly redundant with the require_citation default but still earns its place as 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 a fully documented input schema and no output schema, the description supplies the conceptual frame (family-level fact, Family role, citation) an agent needs. It is mostly complete, missing only edge behavior such as duplicate handling.

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

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

Schema description coverage is 100%, so the schema already documents date formats, the place resolution order, citation precedence, and the require_citation default. The description adds no parameter syntax 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?

State a specific verb and resource ('Add a dated/placed event (fact) to an existing family') and bounds the scope ('family-level facts: marriage, divorce, residence, census'). This cleanly distinguishes it from the sibling add_event_to_person without opening either schema.

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

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

Gives clear when-to-use guidance via the example fact types and the 'Family role' framing, which implies person-level facts belong elsewhere. It stops short of explicitly naming add_event_to_person as the alternative or stating exclusions, so it is strong but not fully 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 only flag non-readonly/non-idempotent; the description adds real behavioral context: adding Birth/Death sets the primary birth/death reference if unset, the citation should point at the establishing record, and require_citation=false records the fact UNSOURCED. It omits failure modes (unknown person handle) and any return information.

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, purpose first, then usage, then side effects. No filler and nothing redundant with the schema.

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

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

For a non-idempotent write tool with no output schema, the description covers purpose, usage scope, and the key mutation side effect. It could note error behavior and whether the created event handle is returned, but the rich schema carries most remaining burden.

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 adds semantic intent for the citation parameter (must point at the record establishing the fact) and the birth/death side effect of the event type, which is meaning the schema 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 ('Add a dated/placed event (fact) to an existing person'), and the 'to an existing person' scoping distinguishes it from the family-scoped sibling add_event_to_family without needing the schema.

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

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

'Use for facts beyond birth/death: residence, occupation, census, baptism, immigration...' gives concrete positive usage context. It stops short of naming the alternative (add_event_to_family) or an explicit when-not-to-use, and the birth/death caveat slightly muddies the stated boundary.

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/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds real behavioral context beyond that: the side effect that family/parent-family lists on each person are linked automatically, the prerequisite that referenced people must exist, and the citation expectation for the marriage.

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 prerequisites, then the auto-linking side effect and citation advice. Four sentences, each carrying distinct information; only the closing citation sentence overlaps mildly with the schema's 'Cite 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 write tool with no output schema and a rich 7-parameter schema, the description covers the prerequisite, the auto-linking behavior, and citation guidance. It could say more about what is returned or about idempotency/re-run behavior, but 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%, so every parameter (father, mother, children, marriage, relationship, allow_new_type, require_citation) is already documented in the schema, including the ChildLink frel/mrel and CitationInput precedence. The description mentions marriage citation 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 and resource ('Create a family linking parents and children') plus the optional cited marriage, so the agent can distinguish it from add_person and the granular family-mutation siblings (add_child_to_family, set_family_parent). The scope of what the tool produces 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?

Gives a clear prerequisite ('All members must already exist (create them first with add_person)') and tells the agent when citing is warranted ('Cite the marriage event to a marriage record where possible'). It does not, however, address when to prefer this tool over the granular siblings like add_child_to_family or move_child.

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 disclose that this is a non-read-only, non-destructive, non-open-world operation. The description adds useful behavioral context beyond that: the upload is standalone, identical files are reused via checksum, and duplicate uploads create cleanup work later. It does not cover permissions or exact return behavior, but annotations lower the burden.

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

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

The description is front-loaded with the core action and then gives workflow and anti-duplication context. Every sentence is relevant, though the second paragraph is slightly editorial in phrasing and could be marginally tighter.

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?

Given full schema coverage, annotations, and no output schema, the description provides enough context to call the tool correctly: it explains the upload-as-standalone-object model, the dedup behavior, and the follow-up attach/cite workflow. It stops short of describing return values or edge cases such as dedup_by_checksum=false, but nothing critical 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 schema already fully documents file_path, description, and dedup_by_checksum. The description echoes the reuse/dedup concept but adds no parameter syntax or constraints beyond what the schema provides, making 3 the appropriate baseline.

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

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

The description states a specific verb and resource: upload a document as a standalone Media object. It distinguishes this tool from the sibling attach_media by explaining that add_media creates the Media object, which is then attached elsewhere.

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

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

It gives explicit workflow guidance: create one Media object per image, then use attach_media(media_ref=...) to attach it, and cite it once per fact. It also warns against the duplicate pattern of uploading the same photograph repeatedly, which is an explicit misuse scenario.

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 non-destructive, non-idempotent, closed-world behavior, so the bar is lower. The description still adds real value by disclosing atomicity and failure semantics ('Any length is written in one call; a server error says whether anything was'), which tells the agent it won't be silently partially written. Auth requirements and return payload are not covered.

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

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

Front-loaded purpose in the first sentence, then usage, then behavior; every sentence carries content. Minor deduction for the truncated final clause ('a server error says whether anything was') and the stray blank line that slightly interrupt readability.

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

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

With no output schema, the description should ideally say what comes back (e.g. the new note handle); it only gestures at this via the error-semantics sentence. Otherwise a mutation tool with annotations and full schema coverage is adequately documented for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns an extra point by explaining the semantic coupling between two parameters ('Attach ... by giving target + target_type'), which the schema lists separately without stating that relationship.

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 ... note') and immediately qualifies scope with the optional attachment to an object. The verb clearly separates it from the read sibling get_note, and the 'research/general' qualifier ties it to the note_type parameter an agent will see in 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 concrete usage contexts ('research logs, reasoning about conflicting evidence, or transcriptions') and the how-to for attaching ('giving target + target_type'). It does not name exclusions or contrast with near neighbors like add_research_task, so it stops short of explicit when-not guidance.

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

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

Beyond the annotations (which only declare this is a non-read-only, non-idempotent write), the description discloses concrete behavior: the call FAILS if a birth/death event lacks a citation under the default require_citation=True, unsourced events get stamped with an UNSOURCED attribute that list_unsourced_facts can later surface, and it states the return value (handle and gramps_id). Those failure modes and side effects are not derivable from the annotations or schema.

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

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

Four sentences, front-loaded with the core purpose, then the citation workflow, then the fallback for unsourced hints, then the return value. Every sentence carries actionable information and none restates the tool name or schema.

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

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

There is no output schema, and the description fills that gap by naming the returned handle and gramps_id. Combined with the citation-requirement semantics and the UNSOURCED follow-up path, an agent has everything needed to invoke an 8-parameter mutation 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 baseline is 3, but the description adds real interpretive value by explaining the intent behind require_citation (hard failure vs. flagged follow-up) and by instructing the agent to set citation confidence honestly. It reinforces rather than repeats the schema, so it earns one point above baseline.

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

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

The description gives a specific verb+resource ('Create a new person') and narrows scope with 'optionally with cited birth and/or death events', which is enough to separate it from pure event tools like add_event_to_person. It stops short of naming any sibling it must not be confused with (e.g. add_family), so it is clear but not fully 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?

'Use this to add someone to the tree' anchors when to reach for it, and the citation guidance supplies conditional rules: cite the specific record when you have one, and either omit the event or set require_citation=False when only a legacy hint exists. No explicit 'use X instead when Y' routing to siblings is given, so it is strong context rather than full when/when-not guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint false, destructiveHint false, non-idempotent). The description adds real behavioral context: the deliberate route yields typed/parented places, while the implicit route produces duplicates. It stops short of noting that a repeated call is not idempotent and can itself create duplicate places, which would be the one remaining behavioral 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?

Front-loaded with the core action in the first sentence, and the following sentences justify the 'deliberately' framing rather than padding it. Slightly more explanation of the anti-pattern than strictly needed, but every sentence carries information.

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

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

For a create tool with full schema coverage and no output schema, the description covers purpose, timing, and consequences well. The one missing piece is what the call returns (e.g., the new place's handle/gramps_id), which matters since no output schema exists to tell the 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 baseline is 3. The description only echoes 'a type and a parent,' adding no syntax, format, or matching semantics beyond what the schema already documents for all eight parameters.

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

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

States a specific verb and resource ('Create a place') with the distinguishing scope 'deliberately, with a type and a parent.' It also contrasts against the implicit side-effect route, so an agent can tell what this tool does differently from letting an event naming produce a place.

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 ('Use this instead of letting a place appear as a side effect of naming one in an event') with the failure consequence of the alternative ('untyped, unparented place... duplicate hierarchies'). Nothing is left to inference about when this tool is the right choice.

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

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

Annotations already declare a non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description adds the domain-model context but says nothing about duplicate-name handling, what identity the new repository receives, or what the call returns — the near-miss type-refusal behavior lives only in the schema's allow_new_type text.

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 entity, then a short conceptual gloss. Three sentences with minimal waste; the hierarchy line earns its place by orienting the agent in the evidence model.

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?

Annotations carry the safety profile and there is no output schema to explain, so the description is nearly sufficient. Missing nothing critical, but for a create tool it would help to note that a duplicate/identical repository is not deduplicated here (find_duplicates and merge_objects exist) and roughly what comes back.

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 (name, url, repository_type, allow_new_type) are already documented with examples and defaults. The description's phrase 'institution or place that holds sources' lightly reinforces what `name` means but adds no syntax, format, or constraint detail.

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 Repository') and immediately defines the resource as 'an institution or place that holds sources.' The evidence-model line (Repository -> Source -> Citation -> fact) places it relative to add_source and add_citation, giving implicit sibling differentiation, though it never names those tools directly.

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?

'Create these for archives, libraries, cemeteries, or websites you'll cite sources from' gives a domain context for use, but largely restates the repository_type values already documented in the schema. No alternative is named (e.g., link_repository for attaching an existing repository to a source), so the agent must infer when this tool wins over its 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 establish this is a write operation that is neither idempotent nor destructive, so the bar is lower; the description adds real context by disclosing the internal write shape (Source tagged ToDo, Status 'Open', a Priority, and the description stored as a To Do note). It does not mention potential duplicate creation despite idempotentHint=false, nor any permission requirements.

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

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

Two short sentences, no filler, with the action and its target front-loaded and the cautionary rule last. Every clause carries information the agent cannot get from the name or schema alone.

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, non-idempotent write tool with no output schema, the description covers what it creates and the key domain constraint well. The remaining gap is the response (whether the created task's identifier is returned) and duplicate-creation behavior, which would help an agent chain a follow-up update_research_task 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 coverage is 100%, so the baseline is 3, but the description adds semantic framing beyond the schema: it explains that this is written as a Source with the description as a To Do note and a Status of 'Open', which explains how priority/description map onto stored fields. It still says nothing about tags or allow_new_type behavior beyond what the schema already 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 ('Add a research task to Gramps Web's own task list (its Tasks view)') and pins it to the Tasks view, which cleanly separates it from list_research_tasks and update_research_task. The second sentence clarifies what artifact is actually produced, so the agent knows this is not note/citation creation.

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 positive context (modeling a task the way Gramps Web's New Task form does) plus a hard exclusion: 'A task is a to-do, never evidence: never cite it,' which steers the agent away from representing this as a source of evidence. It does not name sibling alternatives such as update_research_task for later modification, so it falls short of requiring the top score.

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 (write, non-destructive, non-idempotent, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the evidence-model relationship to citations and the optional repository link. It stops short of operational details such as duplicate handling on a non-idempotent create 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?

Four sentences, front-loaded with the definition and then the workflow, with no filler. The parenthetical gloss on 'Source' and the citation relationship both earn their space, though the text is slightly longer than strictly needed for an 8-param create tool.

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

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

For a create tool with full schema coverage and safety annotations, the description supplies the domain framing an agent needs to call it correctly. No output schema exists, so the return value is unspecified, and duplicate/error behavior for a non-idempotent create is left implicit — the only notable gaps.

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

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

Schema description coverage is 100% and every one of the 8 parameters is documented in the schema itself (title, author, repository, call_number, allow_new_type, etc.). The description adds no parameter-level syntax or format guidance, 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?

States a specific verb (Create) plus resource (Source) and defines the resource in domain terms ('a body of evidence: a record set, book, certificate, website'). It also separates itself from the closely-related add_citation by explaining that a Source is cited *through* a Citation, so an agent can distinguish the two without opening a schema.

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

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

Gives real context: create the source once, then create citations against it per fact, and optionally link it to a Repository. This tells the agent where add_source sits in the workflow, but it never states a when-not (e.g. use update_source for existing sources, or what to do if it may already exist).

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real domain context not present in the annotations or schema: only these three object types carry a URL list. It stops short of saying what happens on a duplicate URL or how a rejected near-miss type surfaces, though the allow_new_type schema text covers the latter.

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 primary action stated first and the routing rule second. 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 6-parameter mutation tool with no output schema, the description covers target scope and alternative-tool routing, and all parameters are fully documented in the schema. It omits any indication of the return value or duplicate/upsert behavior, which is a minor gap given the annotations already convey the safety profile.

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 the object_type enum-ish restriction and the allow_new_type behavior, so the schema does the heavy lifting. The description reinforces the object_type constraint but adds no further syntax, defaults, or format guidance beyond what the properties already state. 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 ('Add') plus the resource ('a web URL') and constrains the valid targets to person, place, or repository. It also cites the sibling it is not (add_attribute) for sources/citations, so an agent can distinguish it without opening any schema.

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

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

Explicitly gives the when ('person, place, or repository') and the when-not with a named alternative ('For sources/citations, record a web address as an attribute (add_attribute) instead'). Nothing about tool selection is left to inference for the source/citation case.

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

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

Annotations only declare readOnlyHint and openWorldHint=false, which the description goes well beyond: it discloses the relative-walking heuristic, that it works for undated people, that the answer is advisory, and that bulk output is filtered by an independent server rule regardless of the result. Those are real behavioral caveats an agent could not infer from the annotations.

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

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

Purpose is front-loaded in the first sentence, followed by mechanism, usage guidance, and caveat in a logical order. Slightly line-broken and a touch verbose, but every sentence contributes a distinct point 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 read-only advisory tool with no output schema, the description covers the mechanism, the advisory caveat, the explain mode, and an independent filtering behavior. It stops short of describing the verdict's shape or any confidence/error semantics, which would help an agent interpret results, but the essentials are present.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, which sets the baseline at 3. The description reinforces `explain` by framing it as reasoning vs. verdict, but says nothing about `average_generation_gap` or `max_age_probably_alive` beyond what the schema already 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?

The description gives a specific operation on a specific resource: determine whether a person is probably still alive, with a rationale. It also explains the mechanism (walking relatives) so an agent knows what class of question this answers. It does not explicitly contrast itself with any sibling, though none of the listed siblings overlaps this capability.

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 a concrete use condition ('before publishing or sharing anything') and routes between modes ('use explain when you want to see the reasoning rather than just the verdict'). No explicit when-not or named alternative tool, but the trigger context is clear enough to act on.

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?

With annotations already covering safety (readOnlyHint=false, destructiveHint=false), the description still adds substantial behavioral context beyond them: the file is copied into the tree's managed media directory ('don't point at files you don't want copied'), an identical existing file is reused rather than duplicated, and the write is verified afterwards with 'verified: false' meaning nothing attached. That verification semantics is essential since there is no output schema.

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

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

The purpose is front-loaded in the first sentence and the mode split follows immediately, so the agent gets the key decision first. The remaining sentences mostly earn their place (side effect, dedup, verification), though the duplicate-upload anecdote and parenthetical asides make it slightly longer than necessary.

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, it covers the essentials: side effects (file copy), dedup/reuse behavior, mode selection, the mutual exclusivity of file_path and media_ref, and how to interpret the verification result. Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds real meaning on top: it explains that file_path causes bytes to be uploaded into the managed media directory with dedup behavior, and that media_ref links an already-existing Media object. It also reinforces the mutual exclusivity of the two parameters, going slightly beyond the schema's own wording.

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

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

The description names a specific verb and resource ('Attach an image or document to an object') and explicitly splits the operation into two modes: a new upload via file_path, or linking an existing Media object via media_ref. It is very clear on what it does, but it never distinguishes itself from the sibling tool add_media, which an agent could easily confuse with attach_media.

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 clear in-context guidance for choosing between the two modes ('With file_path... With media_ref...') and adds an operational warning about duplicate uploads ('Uploading the same photograph separately for the husband and the wife creates duplicates'). However, it never names an alternative tool or states when not to use this one, so the routing burden against siblings like add_media/update_media is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: it confirms 'Reports only' (no auto-repair) and states that findings include repair guidance, which is behavioral context the annotations do not carry.

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

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

Purpose is front-loaded in the first sentence, then the finding catalogue is presented compactly, and it closes with the one operational constraint that matters ('Reports only'). No filler sentences.

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 read-only audit tool with no output schema, the definition covers scope, defect classes, repair guidance, and the non-mutating nature. Minor gap: nothing about result volume/truncation behavior when limit is hit, though limit's schema description mitigates this.

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 limit and include_private are fully documented in the schema itself. The description contributes nothing about parameters (e.g., whether limit truncates silently or what counts as one finding), 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 ('audit the links between people and families') followed by an enumeration of the four exact defect classes it detects. An agent can distinguish this consistency-check tool from siblings like verify_tree or find_duplicates 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?

The scope is clear enough to know when to reach for it (link integrity auditing), and 'Reports only' signals it is a diagnostic pass rather than a fixer. However, it never names or contrasts with nearby siblings such as verify_tree, find_duplicates, or the various link-mutation tools, so the agent must infer the boundary.

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 mark this as a non-destructive write (readOnlyHint=false, destructiveHint=false), so the bar is lower; the description adds real value by explaining what the created citation asserts (both sides of the link) and the confidence-inheritance hazard of handle reuse. It does not disclose the response shape or whether an existing citation is created versus linked, leaving some behavior 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?

Front-loaded with the core action, then the rationale, then the one-parent caveat. It is longer than strictly necessary and somewhat prose-heavy, but each sentence carries a distinct, non-redundant point.

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, the description covers the purpose, the claim semantics, and the reuse pitfall well. It omits what a successful call returns (e.g. new citation handle) and any prerequisite about the ChildRef already existing, which are minor gaps given the rich schema.

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

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

Schema description coverage is 100% and the nested CitationInput already documents the source/citation/page/confidence precedence, so the baseline is 3. The description goes beyond the schema by warning that the `citation` argument is for the PARENTAGE claim and should be a new citation rather than a reused handle, which adds decision guidance on which of the three required parameters to fill how.

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: 'Cite the parent-child link itself, on the family's ChildRef.' This cleanly separates it from siblings like cite_event, cite_object, add_child_to_family, and update_child_ref, and the framing around the parentage claim being distinct from a record-entry claim sharpens the scope.

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-not: do not reuse the child's existing citation handle because it borrows confidence from an unrelated claim, and when only one parent is evidenced, cite that parent's relationship instead of implying both. It stops short of naming the exact alternative tool, so the routing is clear but not fully enumerated.

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 profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds useful behavior the annotations cannot convey: the citation is resolved-or-created, appended to the citation list with no duplicates, and no other event field is touched. It stops short of saying what the response looks like or how it behaves against a duplicate 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?

Three compact sentences, with the hard constraint ('ALREADY exists') front-loaded and the resolution/dedup behavior following. No filler, though the parenthetical about handles and inline fields is slightly dense.

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 no output schema, the description covers what is written, what is left untouched, and the dedup rule. The only real gap is the unspecified return value and error behavior on a bad event handle.

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 embedded CitationInput docstring already spells out the citation/source/source_title precedence, page, and confidence semantics. The description only summarizes that precedence at a high level, so it adds little beyond the structured schema.

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

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

States a specific verb and resource ('Attach a citation to an event') and immediately narrows the scope with the capitalized 'ALREADY exists', which separates it from the add_event/add_citation creation siblings. An agent can tell what it writes and to which object type 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 concrete triggering conditions: source an event you didn't create inline, an event added via the Gramps web UI, or an event surfaced by list_unsourced_facts. It names a sibling tool as the discovery path but doesn't explicitly state when to prefer cite_event over cite_object or cite_child_link, so routing for the other cite_* variants is left to inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the safety story is covered. The description adds domain semantics about which claims a citation supports, but says nothing about side effects, whether a new citation object is created, or what happens to an existing citation on re-cite. Useful context, but not rich behavioral disclosure beyond the annotations.

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

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

Front-loaded with the core action and scope, then organized as distinct routing paragraphs. Every sentence maps to a real decision, though the prose is dense and the family/name cases could be tighter.

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

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

Covers scope, alternatives, and the tricky name/family/link cases well, and the schema fully documents the citation precedence. It stops short of describing the return value or failure mode (e.g. a name match that matches zero or multiple names), which would matter for a non-idempotent mutation with no output schema.

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

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

Schema coverage is 100% and CitationInput's precedence rules are fully spelled out in the schema, so the baseline is 3. The description reinforces the object_type='name' case and the family case but adds no new syntax or format detail beyond what the schema already documents.

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 ('Attach a citation to any object that carries one') and immediately scopes it against the sibling cite_event ('cite_event covers facts; this covers the rest'). An agent can distinguish this from cite_event and cite_child_link without opening any schema.

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

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

Gives explicit routing rules: events go to cite_event, parent-child links to cite_child_link, person-level citations only for whole-person evidence, names via object_type='name'. It even states a preference ('prefer citing the specific event where one exists'), which is exactly the when-not guidance an agent needs.

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 output-side behavior that the annotations don't: per-event citation count and confidence parity with get_timeline, plus an aggregate uncited_count — meaningful because there is no output schema to convey this.

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 action is front-loaded in the first sentence, followed by when-to-use and then output characteristics. Three short paragraphs, each earning its place, with no filler — only slightly looser than an ideal single tight block.

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 annotations covering the safety profile and a 100%-covered schema, the main remaining gap was return-value information, which the description supplies (citation count, confidence, uncited_count). The one thing an agent cannot learn is pagination/ordering behavior for a merge across multiple targets, but overall the definition is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so all six parameters (limit, anchor, targets, event_types, object_type, include_private) are already documented in the schema. The description's mention of 'people or families' loosely maps to object_type but adds no syntax, default, or interaction 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?

The first sentence gives a specific verb and resource ('Merge several people or families into one chronological timeline'), and the description explicitly references get_timeline, noting it carries the same per-event citation count and confidence plus an uncited_count across the set. This differentiates it from the single-timeline sibling, though the contrast is framed as output parity rather than a crisp 'use this instead of that' statement.

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?

Two concrete usage scenarios are given: seeing a household move together through censuses, and checking whether a family's events are mutually consistent. These tell the agent when the tool fits well, but there is no explicit exclusion or routing rule against get_timeline, event_span, or verify_tree.

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 substantial behavioral context beyond that: results are per file, each fact is flagged for whether a source was attached, source text is included when present, results are untrusted, and probably-living people are withheld and counted. This is exactly the kind of return-behavior and privacy disclosure that helps an agent use the tool 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?

The description is front-loaded with the core purpose and then layers return details, source-flagging behavior, usage warning, and privacy handling in a compact block. Every sentence adds useful information without repetition or 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 search/consult tool with no output schema, the description supplies enough return-shape information, trust-level guidance, source-flagging semantics, and privacy behavior. Combined with annotations that cover safety, an agent has what it needs to call and interpret this 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 all four parameters are already documented in the input schema. The description does not add syntax, matching behavior, or format details beyond what the schema provides. Baseline 3 is appropriate when the schema carries 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 states a specific verb and resource: consult/search the legacy GEDCOM reference layer for hints. It clearly frames the tool as returning untrusted, non-authoritative hints rather than definitive records, which distinguishes it from sibling lookup tools. An agent can understand the tool's unique role 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 explicit usage context: use hints to decide what real record to hunt for, then create the fact in the tree citing that record. It also gives a clear prohibition: do not copy a hint in as a sourced fact. It does not name alternative sibling tools, so it falls short of full when/when-not/alternatives 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 this as a non-read-only, non-destructive, non-idempotent write. The description adds that the result is persisted and reappliable, but never warns that repeated calls with the same name are not idempotent (idempotentHint=false), nor describes permissions or duplicate-name behaviour. It adds some context but leaves the main behavioural risk unstated.

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

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

Two short paragraphs, purpose first, rationale second; there is no filler and the alternative/rationale clause is front-loaded within its sentence. The second paragraph is slightly padding-like for an agent that only needs invocation facts, costing it a point.

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 mutation with no output schema, the description never states what is returned (a filter handle/ID? the saved object?) or what happens on a name collision. With annotations and 100% schema coverage the remainder is adequate, but the return-value gap is real.

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 6 parameters, including the plain-language hints for namespace, rules, function and invert, so the schema carries the parameter semantics. The description adds no syntax or format detail beyond what is already documented (e.g. the list_filter_rules reference for rule names 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?

States a specific verb and resource (save/create a reusable custom filter) plus the constraint that it is built from Gramps' own rules. An agent can immediately distinguish it from the sibling reads (list_custom_filters) and destructive operation (delete_filter) 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?

The second paragraph gives an explicit when-to-use cue: pick this for a selection you will run repeatedly (audit scope, branch of the tree) because the filter gains a name instead of being retyped. It stops short of naming alternatives such as list_custom_filters or delete_filter, and gives no when-not guidance.

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

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

Annotations already declare readOnlyHint=true 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 idempotentHint=false, so the agent knows this is a destructive, non-idempotent write. The description adds genuine value beyond that by scoping the destruction: only the saved filter definition is removed and nothing in the tree is affected. It stops short of stating whether the deletion is permanent or recoverable.

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 clarification immediately following. 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 two-parameter delete tool with full schema coverage, no output schema, and annotations carrying the safety profile, the definition is close to complete. The remaining gap is the absence of any consequence statement (permanence, recoverability, permission requirements) for what is a destructive operation.

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

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

Schema description coverage is 100%, with both 'name' and 'namespace' documented in the schema itself, so the baseline is 3. The description adds no extra meaning about parameter format, accepted namespaces, or identifier conventions 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 ('Delete a saved custom filter'), which is unambiguous and separable from siblings like create_filter and list_custom_filters. It does not explicitly name a sibling to distinguish itself from, so it falls short of a 5.

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

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

The description says nothing about when to use this tool versus alternatives, nor about prerequisites such as needing the filter to exist or having permission to remove it. Usage is only implied by the verb 'Delete' and the required namespace/name pair.

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 destructive=true; the description goes well beyond that by disclosing cascading behavior ('the server also removes every reference to it') and two specific refusal conditions with the carry_to workaround. Those are exactly the side effects an agent must know before invoking a destructive delete.

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 identifier forms, then a one-word DESTRUCTIVE flag, then the exception cases. Every sentence carries non-redundant information; nothing is padded.

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

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

With no output schema, the description still covers the destructive semantics, cascade scope, and failure modes, which is sufficient for a 3-param delete tool. It omits what the tool returns on success and whether the action is recoverable (e.g., undo_transaction), leaving 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 target/object_type/carry_to are already documented in the schema. The description restates carry_to's purpose ('pass carry_to to move them') but adds no format, default, or syntactic 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 ('Permanently delete an object from the tree') plus the identifier forms (handle or gramps_id), and the word 'Permanently' implicitly distinguishes it from sibling detach_object/uncite. It does not name a sibling explicitly, 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?

Gives concrete preconditions and the alternative path: refused when the object is the only holder of a note/image, in which case 'pass carry_to to move them', and refused for a source with citations. That is clear when-it-works guidance, though it does not explicitly route to sibling tools like detach_object or merge_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 already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description goes beyond that by disclosing the orphan-check semantics: deletion only happens when delete_if_orphan is set AND nothing else references the object, precisely because dangling handles would otherwise result. It does not cover permissions or what the response looks like.

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 and its scope are front-loaded in the first sentence, with the destructive edge case in the second. The em-dash clause is slightly ornate but every sentence carries load; 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 six-parameter, four-required mutation tool with no output schema, the definition covers the action, the supported relationship kinds and the one genuinely risky flag. It never explains parent_type's valid values or the relationship to check_family_links beyond a passing reference in the schema, 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%, including per-parameter docs for child_kind, call_number and delete_if_orphan. The prose restates the detach-vs-delete distinction but adds no syntax or format detail beyond what the schema already supplies, so the baseline of 3 is right.

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 ('Remove a reference from an object') and immediately enumerates concrete cases: event from person, image from source, tag, note, child from family. It also implicitly separates itself from delete_object by asserting 'the object itself survives,' 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?

There is real usage guidance embedded ('detaching and deleting are different decisions', delete_if_orphan is off by default), but no sibling is ever named. With uncite, delete_object, update_child_ref and move_child all in scope, the agent must infer which to pick rather than being routed.

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 rationale about avoiding transcription errors but does not disclose return format, error behavior, or precision handling beyond what the schema implies.

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 that are front-loaded with the core action. The final sentence is somewhat wordy but adds useful rationale; no significant 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 computation tool with no output schema, the description does not explain what the result looks like (e.g., an interval string or age format). It covers purpose and use case but leaves a notable gap in return value expectations.

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 documented in the schema. The description adds no additional meaning for event handles, as_age, or precision, 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?

States a specific verb and resource: 'Measure the elapsed time between two events.' It clearly distinguishes from event retrieval tools by focusing on the interval calculation, though it does not explicitly name a sibling it is not.

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 context for when to use it: 'The arithmetic behind most plausibility checks: age at marriage, years between a census and a death.' No alternatives or exclusions are named, but the use case is well-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?

Adds meaningful context beyond annotations: explains the rationale (irreversibility of bulk writes), reassures on cost ('a few seconds and one file'), and clarifies recoverability ('can be re-imported'). The annotations already cover safety signals. Minor gap: doesn't mention disk space or overwrite behavior, though the schema covers the latter.

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 action, then rationale. Every sentence earns its place; 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 backup tool with no output schema, the description explains purpose, timing, cost, and recovery value. It doesn't explain what the export returns (file path?), but that's not critical for an agent invoking it. Complete enough.

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 parameters are thoroughly documented in the schema itself ('gramps' as lossless safety dump, dest_path behavior). The description adds no parameter-specific detail, which is acceptable given full schema coverage. 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 clear verb+resource ('Write a full-tree export to disk'), which distinguishes it from read-only siblings like query_objects or get_object. It doesn't name a sibling alternative, but its purpose is unmistakable.

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 timing guidance ('Take one before any bulk write'), which is a concrete usage condition. It lacks explicit when-not-to-use guidance, but the context is well-defined for a backup 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds that it never mutates and explains the consequential risk of over-merging, which is real behavioral context. It stops short of describing what a returned group looks like or how scoring/'likely' is determined.

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 action and its safety constraint are front-loaded in the first sentence, which is exactly right. The middle narrative about false evidentiary claims is somewhat discursive, but it justifies the tool's caution 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 read-only, no-output-schema discovery tool with fully documented parameters, the essentials are present: it finds candidates, returns grouped results, and defers the merge decision to the caller. Only the shape/ordering of returned groups is unstated, which is minor here.

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

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

Schema description coverage is 100% with rich enum-like detail on 'kind' values, so the schema does the heavy lifting. The description adds no parameter-level syntax beyond what the schema provides, making 3 the appropriate baseline.

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

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

States a specific verb and resource ('Find likely-duplicate objects') and immediately scopes it against the merge behavior ('Reports only -- it never merges anything'). An agent can distinguish it from merge_objects 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?

Explicitly tells the agent when to use it (candidate discovery), what it must NOT treat as duplicates (index entry vs. register page), and which sibling to use for the follow-up action ('Merge with merge_objects'). The when-to-use and hand-off routing are both present.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely non-obvious behavior: living/private ancestors are returned as redacted stubs by default. It also discloses the nested-tree return shape, which matters since there is no output schema. It stops short of describing error behavior for an unknown 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?

Two sentences, no filler. The core operation is front-loaded and the privacy caveat is placed second, where it belongs.

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 sketches the return shape (nested parents tree with redacted stubs) and the annotations carry the safety profile. It is nearly complete; only failure modes and depth-limit behavior are left unaddressed.

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

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

Schema description coverage is 100%, so all three parameters (person, generations, include_private) are already documented with types, defaults, and bounds. The description echoes 'up to N generations' and the include_private effect with no additional 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?

States a specific verb ('Walk') and resource ('ancestors') with scope ('up to N generations') and return shape ('a nested parents tree'). An agent can distinguish it from the sibling get_descendants purely on the description.

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 when to use it (tracing ancestry upward) and hints at the privacy trade-off, but never explicitly names alternatives such as get_person or get_descendants, nor states exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: zero backlinks means the object is orphaned, and backlinks imply dangling references on delete, plus the 'grouped by type' shape of the result. It is not a rich disclosure (no pagination/volume caveats), but it materially exceeds the annotations.

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

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

The core purpose is front-loaded in one sentence, with usage scenarios in a compact second block. Every sentence earns its place, though 'The right way to ask' is slightly discursive 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 read tool with no output schema, the description covers purpose, usage scenarios, the deletion-safety implication, and hints at the grouped return shape. Only minor gaps remain, such as result volume or how orphaned objects are represented.

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 ref and object_type are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, making the baseline 3 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 ('List everything that references this object') and adds the grouping dimension ('grouped by type'), which no sibling tool provides. An agent can distinguish it from get_object or cite_object 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 concrete invocation contexts ('is this source actually cited?', 'which facts rest on this citation?', 'is it safe to delete this?'), which is strong when-to-use guidance. It never names an alternative tool or states when not to use it, so it falls 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by interpreting cited_by_count — zero signals an orphaned citation that should have been removed by uncite — which is semantics the agent could not derive from annotations or schema.

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

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

Front-loaded with the core action and return fields, then a short second paragraph on the one field that matters. Both sentences earn their place, though the orphan-debris editorializing is slightly informal for a tool contract.

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 must convey the return shape, and it does list the principal fields plus the significance of cited_by_count. It omits error behavior for an unresolvable handle and does not enumerate every returned field, leaving a small gap for a read tool of this complexity.

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

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

Schema description coverage is 100% ('Handle or gramps_id of the citation'), so the schema fully documents the single parameter. The description adds nothing about accepted identifier formats or resolution behavior, which is the baseline-3 case when the schema carries the load.

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 citation') and enumerates the fields surfaced (page, confidence, date, source), which distinguishes it from the write-side siblings like update_citation and uncite. It does not explicitly distinguish itself from adjacent readers such as get_source or get_object, so it falls 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?

There is no explicit when-to-use statement, but the second paragraph implies a diagnostic use case: fetch a citation to inspect cited_by_count and decide whether it is orphan debris. The reference to 'uncite should have deleted it' gestures at a workflow without naming when to prefer this tool over query_objects or get_object.

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 genuinely non-structured behavior: living/private descendants are redacted to stubs by default, and the result is a nested tree rather than a flat list.

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

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

Two compact sentences, front-loaded with the core action and followed by the one behavioral caveat an agent must know. No filler or repetition.

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

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

With no output schema, the description usefully characterizes the return value as a nested children tree and discloses the redaction default, which are the key facts for this traversal tool. It stops short of covering failure modes (e.g., unknown person) or how the generations cap interacts with sparse data.

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, generations, and include_private fully. The description only echoes the generation cap ('up to N generations') and the default redaction behavior, adding little beyond the schema baseline.

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

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

States a specific verb (walk) and resource (a person's descendants) plus the return shape (nested children tree), which is more than a restated name. It is inherently distinguishable from the get_ancestors sibling, but it never names or contrasts with any sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the downward-traversal counterpart to get_ancestors. There is no explicit when-to-use/when-not guidance or routing to alternatives such as get_family or get_relationship.

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 real value beyond that: it names the key returned figures (shared cM, largest segment, common ancestor) and flags `unattributed_count` as the field that identifies open research, which shapes how an agent interprets results. It still omits pagination/return-shape specifics.

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

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

Purpose is front-loaded in the opening sentence and the structure (what it returns, then interpretive caveat) is easy to scan. The bolded DNA-evidence paragraph is a bit editorial for a two-parameter read tool, but it is short and each sentence carries a distinct idea.

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

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

There is no output schema, so the description usefully compensates by enumerating the per-match fields and calling out `unattributed_count`. For a simple read-only list tool with fully documented params this is nearly complete; only pagination and error behavior are unspecified.

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

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

Schema description coverage is 100%, so both `person` and `include_raw` are documented in the schema itself. The description does not add syntax, handle-format, or default behavior 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 first sentence gives a specific verb and resource ('List the DNA matches recorded against a person'), and the following sentences clarify the per-match payload. It does not differentiate itself from close siblings such as add_dna_match, get_ydna, or parse_dna_segments, so an agent still has to infer the boundaries from names alone.

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

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

Usage is only implied: an agent can tell this returns matches for a tested person, but there is no explicit when-to-use guidance or routing to alternatives like get_ydna (Y-DNA) or parse_dna_segments. The bolded note explains how to interpret DNA evidence generally, not when to call this tool instead of a 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 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 readOnlyHint/openWorldHint it discloses two behaviors the annotations cannot convey: living and private people are withheld by default and only shown when include_private is set, and the call is slow because the server computes results per call. It also frames implausible results as likely data errors, which shapes how the agent should interpret 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?

Front-loads purpose in the first sentence, then clarifies scope, interpretation, privacy, and cost in order. Every sentence contributes, though the privacy sentence duplicates the include_private schema description and the length is near the upper bound for a list-style tool.

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

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

There is no output schema, and the description does not describe the shape of the returned record-holders (names, values, ordering by rank), which is the main remaining gap. Parameters, safety, privacy defaults and performance are all covered, so an agent has enough to decide and call, just not to anticipate the response.

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's mention of include_private largely restates that. It adds only a light framing of the scope ('across a set of people'), which the schema's person_filter description already covers in more detail. 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 an unusual resource ('the tree's record-holders'), then immediately concretizes it with three examples: oldest at death, youngest parent, most children. The line 'Superlatives across a set of people, not statistics about one person' separates it from per-person getters like get_person or db_stats without requiring the schema to be opened.

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 usage scenario ('a quick plausibility check' for data errors) and a condition on the include_private flag. However it never names an alternative tool or states an explicit when-not-to-use case, so the agent must infer routing from the purpose line alone.

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

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

Annotations already declare 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 meaningful async semantics — that the dispatching tools answer before the work completes and that status must be polled to a terminal `finished` flag — which is real behavioral context beyond the annotations. It does not mention timing, retry limits, or error behaviour if the task_id is unknown.

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 outcome question, then the polling protocol. The closing sentence about never checking is slightly motivational rather than instructional, but it reinforces the polling contract and does not bloat the definition materially.

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

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

There is no output schema, so the description carries the burden of naming the fields an agent must read — it does this for `finished` and `succeeded`. What is still missing for a polling tool is terminal-state handling (e.g. failure detail, whether the job record survives until polled, or what happens after several polls).

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 sole parameter's schema text already explains that task_id comes from undo_transaction, verify_tree, reindex_search or run_report. The description restates the same dispatching set, so it adds little 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 ('check whether a background job has finished, and whether it worked') tied to a named object ('task_id'). An agent can distinguish this from list_jobs because the description frames it as polling a single dispatched job for its terminal state, not enumerating jobs.

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

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

Explicitly names the operations that dispatch work (undo, verification, import, reindex) and the exact usage loop: 'Poll this until `finished` is true, then read `succeeded`.' It even states the failure mode of not using it ('leaves you assuming an outcome you have not seen'), so when-to-use and when-not-to-skip are both covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing return-field semantics (referenced_by_count >1 is normal, shared checksums indicate duplicates), which is valuable given there is no output schema.

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

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

Front-loaded with the core purpose, then two compact notes on interpreting results. The em-dash asides and backticked field references are slightly informal but each 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 read-only, one-parameter tool with no output schema, the description helpfully enumerates the returned fields and explains how to interpret the reference count and checksum. This compensates well for the missing output schema, leaving only the get_object vs get_media distinction 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 fully documented as 'Handle or gramps_id of the media object.' The description adds no syntax or format detail beyond what the schema already 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 and resource ('Read one media object') and enumerates the fields it returns (path, mime type, checksum, description, date). It is clearly distinct from the get_person/get_event/get_source siblings, though it does not explicitly contrast with the generic get_object, which could also fetch media.

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 routes the agent toward find_duplicates(kind='media_checksum') for duplicate hunting and explains how to read referenced_by_count, which is useful context. However, it never states plainly when to choose this tool over alternatives like get_object, so usage guidance remains 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail: the note text is returned whole rather than truncated, and the result includes the note's type and its attachment. With no output schema, this return-shape disclosure is the right kind of added value.

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. The second sentence is longer than a typical definition but earns its place by justifying why the full text matters, though it leans slightly into narrative.

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

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

For a one-parameter, read-only tool with no output schema, the description covers purpose, return content (full text, type, attachment) and the reason notes exist. Return-value expectations are adequately set, and no auth or edge-case caveats appear necessary.

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

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

Schema coverage is 100% and the single parameter is documented in-schema as a 'Handle or gramps_id of the note.' The description adds no format, prefix, or resolution guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one note') plus the scope of what comes back ('in full, with its type and what it is attached to'), which is more than a restatement of the name. It does not, however, distinguish itself from the generic sibling get_object, which plausibly also retrieves notes by handle.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative is named. The agent is left to infer that get_note is the note-specific equivalent of get_object/get_person.

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 the safety profile is covered. The description adds genuinely useful behavioral context beyond them: it returns the record 'as stored' (raw, unshaped), and that this raw form is preferable prior to an edit. It stops short of describing key-filtering behavior or the absent output 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?

Three tight sentences; the core capability is front-loaded and each following sentence adds a distinct routing or behavioral fact. No filler or 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 read-only generic getter with full schema coverage and annotations, the description covers purpose, routing, and the nature of the return (raw vs shaped), which is what an agent needs to call it correctly. Minor gap: it says nothing about how the returned record is rendered or its field structure, though no output schema exists to cover that.

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 object_type, ref, and keys are already documented in the schema. The description only hints at the object_type domain (places, media, notes, citations) and adds no syntax or format detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (Read) and resource (any object's raw record) and explicitly carves out the subset of objects without shaped getters. It also names the sibling getters (get_person, get_source) it is differentiated from, so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use ('what you want before editing one') and when-to-prefer-an-alternative ('for people and sources the shaped getters ... are easier to read'). The condition selecting the alternative sibling is spelled out, not inferred.

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 genuinely new behavioral context beyond that: direct single-record access bypasses the privacy filtering that bulk/list tools apply, which an agent could not infer from the annotations alone.

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

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

Two short paragraphs, zero filler. The return-field list is front-loaded in the first sentence and the when-to-use/privacy guidance follows, so an agent gets the essential shape immediately.

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

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

There is no output schema, but the description compensates by enumerating the fields returned, and the read-only annotation covers the safety profile. For a single-record fetch this is nearly complete; only incidental details like what happens when the handle is not found 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?

There is only one parameter and schema description coverage is 100%, with the schema itself giving the format and example ('I0001'). The description adds no additional parameter syntax or constraints, and per the high-coverage baseline a 3 is appropriate.

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

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

States a specific verb+resource ('Get full detail for one person') and enumerates the returned facets (name, gender, events with citation counts, attributes, family links, media count). This distinguishes it from siblings such as get_family, get_event, and 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 clear usage contexts: 'inspect someone before adding facts' and 'check whether an event is already cited.' It also carves out a when-this-is-permitted rule (direct lookup allowed for living/private people, only bulk/list tools filter them). It does not, however, name a competing lookup alternative such as get_object or query_objects for the caller to compare against.

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 genuinely useful behavioral context beyond the annotations: that `enclosed_by` forms the jurisdictional chain and that a missing chain signals an orphaned, event-minted place. It stops short of describing error behavior for a bad 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 tight sentences, front-loaded with what is read and what comes back, followed by a short interpretive note. Every sentence carries information; no filler.

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

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

With no output schema, the field enumeration is doing real work for the agent, and the enclosed_by/orphan explanation covers the tool's main subtlety. It is not fully complete: error/not-found behavior and the exact response shape remain unspecified.

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

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

Schema coverage is 100% and the schema already documents `place` as a handle or gramps_id, so the description need not restate it. The description's `enclosed_by` discussion concerns an output field rather than the input parameter, so it adds no input-side semantics. Baseline 3 applies.

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