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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful precondition that both the individual and family must already exist, but it does not describe side effects, duplicate handling, or what happens to existing family structure.

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

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

The description is a single front-loaded sentence with no wasted words. It immediately states the action and the required entities, making it easy to scan.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description states the core operation and preconditions, but it does not address edge cases like adding a child who is already associated with the family or whether existing children are replaced.

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 file, child_id, and family_id with patterns and examples. The description adds no parameter-level detail beyond what the schema provides, fitting the baseline of 3 when structured data carries the 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 ('Add') and resource ('an existing individual as a child of an existing family'), making the operation clear. However, it does not distinguish this tool from potentially related siblings such as set_parents or add_individual, leaving some ambiguity for an agent choosing among them.

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

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

The description implies when to use the tool (when you want to add an existing individual as a child of an existing family), but it provides no explicit when-to-use guidance, prerequisites, or alternative tools. There is no exclusion or routing advice against siblings like set_parents.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the safety profile. The description adds useful context that FAMS/FAMC back-links are written, which is a behavioral trait beyond the annotations, but it does not describe prerequisites, permissions, or side effects on existing records in depth.

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

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

A single, efficient sentence that front-loads the core action and adds the back-link behavior without any filler. Every clause 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 write tool with 83% of parameters undocumented and no explicit usage guidance, the description is too thin. It notes back-link writes and the family record format, but lacks prerequisites, ID expectations, and when-to-use alternatives among siblings like add_child or set_parents.

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 only 17% (just the 'file' parameter). The description maps vaguely to wife_id, husband_id, and child_ids by saying 'linking spouses and/or children', but it offers no ID format details and completely omits marriage_date and marriage_place, leaving most parameters undocumented in both schema and description.

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

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

States a specific verb ('Create'), resource ('family'), and scope ('linking spouses and/or children'), plus the GEDCOM record format (@F..@). It does not explicitly contrast with siblings like add_child or set_parents, so it is clear but lacks sibling differentiation.

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

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

The description implies that the tool is for creating a family unit with spouses and/or children, but it gives no explicit when-to-use guidance, no exclusions, and no mention of alternative tools such as add_child or set_parents. An agent must infer usage from the action 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 this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real context beyond that: the write is persisted ('and save') and the tool returns a GEDCOM @I..@ id, which the agent needs to chain further calls. It does not mention permissions, file-selection side effects, or failure behavior.

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

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

Two short sentences, front-loaded with the action and immediately followed by the return value and the follow-up routing. 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?

Annotations cover the safety profile and an output schema exists, so return-value documentation is not strictly required (though the id note is a helpful preview). The main gap is the low schema description coverage for a 9-parameter tool, which the description does nothing to fill.

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 only 33% across 9 parameters, so the description must compensate and it does not — it says nothing about birth/death dates, places, note, or sex. The only semantic addition is the @I..@ id return format, which relates to output rather than inputs.

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

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

States a specific verb and resource ('Add a new individual and save'), which cleanly separates it from update_individual, add_family, and set_parents. It does not explicitly contrast itself with those siblings, but the operation is unambiguous from the name plus 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 phrase 'link them with add_family / set_parents' gives useful next-step routing, so the agent knows this tool only creates the record and a separate call wires up relationships. However, there is no explicit when-to-use vs update_individual guidance or exclusion conditions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — it doesn't say whether the note is appended or replaces existing notes, nor anything about auth or scope constraints 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?

A single clean sentence with the verb and object front-loaded and zero filler. It is efficient, though arguably terse for a mutation tool.

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

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

An output schema exists and annotations carry the safety profile, so the description needn't explain returns. However, for a write operation with 3 parameters it omits any behavioral detail about what attaching a note actually does to the record, leaving it only minimally complete.

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

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

Schema coverage is 67%, so the schema documents the id pattern, the optional file argument, and the text field adequately. The description's phrase 'free-text note' loosely maps to the text parameter but adds no format, length, or target-type detail beyond the schema.

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

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

The description states a specific verb (attach) and resource (free-text note) with a clear target (a record). No sibling tool offers note functionality, so differentiation is implicit rather than stated, but an agent can still tell exactly what this does.

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 conditions, and no mention of alternatives among the numerous siblings (add_individual, update_individual, set_event, etc.). The usage context is left entirely 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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds that the file is empty and written to the server's directory, but it omits a key behavioral question: what happens if a file of that name already exists (overwrite vs. error).

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

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

A single sentence with no filler; the action and the location constraint are front-loaded and every word 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?

Output schema exists, so return values need no explanation, and the one parameter is fully documented. The only notable omission is collision/overwrite behavior for an existing filename.

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 'name' parameter is documented as 'New file name, without path'. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a new, empty GEDCOM 5.5.1 file') plus a scope constraint ('in the server's directory'). It does not explicitly differentiate itself from siblings like rename_file or list_files, but the action 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?

Usage is implied by the nature of the operation (you call this when you need a new file), but there is no explicit when-to-use guidance, no prerequisites, and no reference to alternatives such as rename_file. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds only what the summary contains, but no additional behavioral context such as error handling, file-format constraints, or multiple-file behavior; with annotations present, this is adequate but not rich.

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

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

One tight sentence, front-loaded with the tool's purpose and output fields, with no filler or redundancy. Every phrase earns its place.

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

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

For a simple read-only summary tool with full schema coverage, clear annotations, and an output schema, the description is complete enough. It tells the agent what the tool provides without needing to restate parameter details or return-value structure already covered by structured fields.

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

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

The schema description coverage is 100% for the single optional file parameter, so the schema already documents its meaning and optionality. The description does not add any parameter semantics beyond what the schema provides, making the baseline of 3 appropriate.

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

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

States a specific resource (GEDCOM file) and enumerates what the overview covers: record counts, originating software, year range, and common surnames. This clearly differentiates it from siblings like list_files, get_individual, and search_individuals without needing to open their schemas.

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

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

The description gives no when-to-use guidance, exclusions, or alternatives. It does not say when to choose file_summary over list_files or other sibling tools, nor does it mention prerequisites like the file being 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 already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, covering the safety profile. The description adds only that the traversal is recursive and bounded by N generations; it does not disclose pagination, performance limits, or error behavior beyond what annotations and output schema imply.

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

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

A single, front-loaded sentence with no filler. It conveys purpose, traversal direction, and depth constraint efficiently.

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 tool with an output schema and declarative annotations, the description covers the core operation and scope. It could be more complete by mentioning the file parameter or routing guidance against get_descendants, but those gaps are minor.

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

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

Schema description coverage is 67%: id and file are described in the schema, but generations has no schema description. The description partially compensates by clarifying that generations controls depth ('up to N generations'), but it omits default (4) and maximum (10) details that an agent might need.

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 action (get ancestors) and resource (pedigree tree for an individual), and clarifies the traversal direction (father/mother recursively) and depth (up to N generations). It distinguishes itself from siblings like get_individual and get_descendants by scope and direction.

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 states what the tool does but gives no explicit guidance on when to use it versus alternatives such as get_descendants or get_individual. There are no exclusions, prerequisites, or context signals to help an agent choose between siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the result is a recursive tree grouped 'children per marriage' and bounded by a generation limit.

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

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

A single tight sentence with the resource, structure and limit all front-loaded. Nothing extraneous; every clause 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?

An output schema exists, so return values need not be explained, and the description still previews the tree shape and generation bound. Slightly under-specified only on error/edge behavior (e.g., missing id, nonexistent file).

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 67% (id and file documented; generations has only default/min/max bounds with no description). The description's 'up to N generations' supplies the meaning of the undocumented generations parameter, so it partially compensates but doesn't fully close the gap.

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 ('Descendant tree ... for an individual') plus the recursive structure and generation cap, clearly contrasting with the get_ancestors sibling by naming descendants rather than ancestors. It never explicitly names the alternative, but an agent can distinguish the two from the resource noun 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: it applies 'for an individual,' which suggests the id-based lookup context. No when-to-use vs get_ancestors, no exclusions or prerequisites are stated, so the agent must infer the routing decision.

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 read-only, idempotent, and non-open-world, so safety is covered. The description adds a content summary (spouses, children, marriage events) but does not add behavioral details beyond that; output schema covers return values.

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?

Single compact sentence front-loads the resource and its contents. No waste, though it is a noun fragment rather than a full sentence.

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

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

With output schema present and annotations covering safety, the description is nearly sufficient. It could mention that id must reference a family record and that file is optional, but core completeness is high for a simple getter.

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 id and file documented. The description only notes the @F..@ id format, which is redundant with the schema pattern/example, so baseline 3 applies.

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

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

States the resource (family record), its GEDCOM identifier format (@F..@), and the contents (spouses, children, marriage and other family events). Distinguishes from get_individual and get_source by family scope, though it omits an explicit retrieval verb.

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

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

No indication of when to use this tool versus get_individual, get_ancestors, or search_individuals. The context is inferable from the name and siblings, but no when-to-use or alternative guidance is 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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that relatives and citations are part of the return payload, which is useful context, but it omits any optionality or file-selection behavior. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

A single front-loaded sentence lists the contents efficiently with no wasted words. It is compact and well-structured, though the enumerated list is 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?

An output schema exists, so return-value formatting need not be explained. However, for a record-fetch tool that may require a file context, the description does not address how the optional file parameter interacts with single-file vs multi-file setups, leaving 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%, so the schema fully documents id, file, include_notes, and include_sources. The description adds almost no parameter-level detail beyond the schema, which is the baseline expectation when coverage is high.

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

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

The description opens with a clear verb phrase, 'Full record for one individual,' and enumerates what the record contains (names, events, notes, citations, relatives). It distinguishes itself from list/search siblings by implying a single-record fetch, though it doesn't name a sibling 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?

There is no explicit when-to-use guidance, no mention of when to prefer search_individuals or list_files, and no prerequisites such as the required id pattern. The agent must infer the use case from the name and description 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, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds that a source record carries citation relationships ("who cites it"), which is mild extra context, but nothing about lookups failing, file scoping, or error behavior.

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

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

A single terse sentence-fragment listing the record's contents; front-loaded and waste-free. It reads slightly like a glossary entry rather than an instruction, but nothing is padding.

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

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

With an output schema present, the description need not explain return values, and annotations cover the read-only/idempotent profile. What remains—the field list—is adequate context for a simple lookup tool, though the missing verb and absence of usage guidance are small gaps.

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

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

Schema description coverage is 100%, so both the id pattern and the optional file parameter are already documented in the schema. The description's "(@S..@)" restates the id format already enforced by the pattern, adding no new syntax or behavioral detail about 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?

The description implies retrieval of a GEDCOM source record and enumerates the fields it contains, which distinguishes it from siblings like get_individual or get_family. However, it never states the verb explicitly ("retrieves a source record by id"); the intent is inferred from the tool name rather than asserted.

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

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

No when-to-use guidance, no conditions selecting it over alternatives, and no mention of prerequisites such as needing a valid @S..@ id. The agent gets a listing of fields but nothing about when this tool is the right call.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered by structured data. The phrase 'available to this server' adds a small amount of scope context consistent with the closed-world hint, but nothing about ordering, filtering, or failure behavior is disclosed.

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

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

A single front-loaded sentence with no filler. The resource and scope constraint both land in the first clause, and there is nothing to trim.

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 list tool with an output schema, the description needs only to identify the returned resource, which it does. It stops short of noting anything about result shape or whether files are enumerated as names vs. paths, but the output schema carries that 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are needed or missing.

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

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

States a specific verb ('List') and a precise resource ('GEDCOM (.ged) files'), with the scope of 'available to this server' scoping it against the machine's whole filesystem. It implicitly separates itself from file_summary and create_file, but the description never names a sibling to sharpen 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?

There is no when-to-use guidance, no mention of alternatives (e.g., file_summary for inspecting a chosen file), and no stated prerequisites or follow-up actions. The description only says what it returns, leaving routing entirely 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds that deletion targets a tagged fact selected by index, but omits what happens on out-of-range index or missing tag, and whether changes are persisted to the GEDCOM file.

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

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

A single tight sentence with no redundancy, and the delete action plus its selector are front-loaded. It is efficient, though it could afford one more sentence for disambiguation without becoming bloated.

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?

An output schema exists so return values need not be described, and annotations cover the destructive nature. However, for a mutation tool with weak parameter coverage, the absence of usage routing and missing id/file semantics leaves gaps an agent would need to resolve elsewhere.

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 only 25%, so the description must compensate, yet it only implies the meaning of tag and index ('index-th fact with the given tag') and says nothing about the required id (whose @...@ pattern matters) or the file parameter. Two of four parameters remain effectively undocumented.

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 (Delete) and resource (a fact with a given tag at a given index, on an individual or family). It does not explicitly distinguish itself from the sibling set_event, but the destructive framing is clear enough to pick it over read/add tools.

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

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

No guidance on when to use this versus set_event or other mutation tools, and no prerequisites or warnings about deleting the wrong fact. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: deletion cascades to all references and orphaned families are removed as well, which is collateral damage an agent must know before calling. It stops short of stating irreversibility or confirmation 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 sentences, zero waste, with the primary action front-loaded and the cascade caveat following immediately. 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?

An output schema exists, so return values need no explanation, and annotations carry the destructive profile. The description covers the critical cascade side effect, though it omits behavior when the id is not found or which file scope applies when multiple files exist.

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

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

Schema description coverage is 100%, and both parameters (id with its @I12@ pattern, and the optional file) are fully documented in the schema. The description adds no additional parameter meaning, 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 (Delete) and resource (an individual) and further scopes the operation with cascading behavior ('all references to them'). An agent can distinguish this from add_individual and update_individual immediately without opening a schema.

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

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

The purpose implies when to use it (removing a person from the file), but there is no explicit when/when-not guidance and no alternative is named (e.g., update_individual for corrections instead of deletion). Usage is inferable but not spelled out.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world operation. The description adds a genuinely useful behavioral constraint beyond that: it refuses to overwrite an existing file. However, it omits what error/return occurs on refusal and any permission or path-scope requirements, so the added value is modest.

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, zero filler, with the primary action stated first and the key constraint second. Nothing could be removed without losing 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?

An output schema exists, so return values need not be described, and the annotations cover the safety profile. What remains missing for a mutation tool is clarification of the new_name parameter format and the failure mode when the target exists, leaving the definition minimally adequate.

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

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

Schema coverage is only 50% — 'file' is documented as 'Existing file name' but 'new_name' has no description at all. The description adds nothing about whether new_name is a bare name, a path, or whether extensions are required, so it fails to compensate for the coverage gap.

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 ('Rename a GEDCOM file'), making it immediately distinguishable from siblings like create_file, list_files, and file_summary. No ambiguity about what operation is performed.

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

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

No guidance on when to use this versus alternatives such as create_file (copy-then-delete) or how to handle conflicts. The agent is left to infer usage entirely from the name.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuinely non-obvious behavior: matching is case- and accent-insensitive, and results are ranked by match quality with a specific tie-break order. It does not explain pagination interplay between limit/offset, but the ranking semantics are the more valuable disclosure.

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

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

Two sentences, front-loaded with the searchable fields before the matching/ranking rules. Every sentence carries information, though the ranking clause is dense and could be slightly 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?

An output schema exists, so return-value explanation is not needed. For a 12-parameter, zero-required search tool the description covers the semantically important filters and the ranking model; the missing pieces (file scoping, limit/offset behavior) are documented in the schema itself.

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 50%, the baseline for a 3. The description reinforces the meaning of query/given/surname, year ranges, place, and sex, and its note about accent-insensitive matching adds value beyond the raw schema strings. However, file, limit, and offset are left entirely to the schema, and the limit/offset interaction is never surfaced.

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

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

The description opens with a specific verb+resource ("Search individuals") and enumerates the searchable dimensions: name, birth/death year range, place, and sex. This clearly distinguishes it from point-lookup siblings like get_individual and get_family, though it never names those alternatives explicitly.

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

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

Usage is implied by the tool name and the listed filters, but there is no explicit when-to-use/when-not-to-use guidance relative to siblings such as get_individual (exact lookup) or list_files. An agent must infer that this is the fuzzy/discovery entry point rather than one taking a known ID.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is covered. The description's contribution is the upsert framing ('Create or update'), which tells the agent this is not strictly a create, but it omits any mention of overwrite risk when index targets an existing fact.

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

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

A single, front-loaded sentence with parenthetical examples that earn their place by mapping natural-language facts to the tag parameter. No filler, though a second sentence clarifying the create-vs-update distinction would not have been waste.

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

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

With an output schema present and 88% schema coverage, the agent does not need return-value documentation. The description adequately conveys the core operation, though the update-via-index mechanics and the GEDCOM file resolution are left entirely to the schema.

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

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

Schema coverage is 88%, so the schema already documents id, tag, date, type, index, and value thoroughly. The description only echoes tag semantics with examples ('birth date, add an occupation') and adds no format or constraint detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb pair and resource ('Create or update an event/fact on an individual or family') with concrete examples (birth date, occupation). It does not, however, distinguish itself from siblings like remove_event, update_individual, or add_family, so the agent must infer the boundary.

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

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

Examples ('set a birth date, add an occupation') imply intent, but there is no explicit when-to-use guidance, no when-not, and no routing to alternatives such as remove_event for deletion or add_individual for the person record itself.

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

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

Annotations already declare this is a non-read-only but non-destructive, closed-world mutation. The description adds real value by disclosing that existing family records are reused and a new one may be created. It says nothing about what happens when the child already has parents, whether both parents may be omitted, or error behavior.

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

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

One efficient sentence with the action front-loaded. The trailing clause about reusing or creating a family is somewhat compressed and slightly ambiguous, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation. However, for a mutation that reshapes family structure, the description omits the key behavioral questions (replacement of existing parents, optionality of father vs mother, required permissions), leaving gaps for a 4-parameter tool.

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

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

Schema coverage is 50%, and father_id/mother_id have no schema descriptions at all. The description's mention of 'father/mother' partially maps to those undocumented parameters but does not clarify whether either is required, whether omitting one is allowed, or the @I12@ id format beyond what child_id's 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 states a specific verb and resource: making a father/mother the parents of a child. It is clear and distinct from siblings like add_child or add_family, though it never names those alternatives 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?

There is no statement of when to use this tool versus add_child, add_family, or update_individual, and no prerequisites or exclusions are given. The agent must infer usage entirely from the purpose sentence.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already covered. The description adds genuine value beyond them by disclosing partial-update semantics: 'Only supplied fields change,' which tells the agent unsupplied fields are preserved. It stops short of stating error behavior or whether the id must already exist.

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 operation and followed immediately by the partial-update rule. Every word 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description still leaves the 60% undocumented parameters (sex value format, given/surname semantics, file scope) largely to inference, which is a meaningful gap for a mutation tool.

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

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

Schema coverage is only 40%: id and file are documented in the schema, while sex, given and surname have no schema descriptions. The description partially compensates by naming the three editable fields, but adds no format, valid-value, or null-handling detail for them. Baseline 3 given the moderate coverage gap.

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

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

States a specific verb (Change) plus the exact resource and target fields (an individual's given name, surname and/or sex). The verb 'Change' implicitly separates it from siblings like add_individual and remove_individual, though no sibling is named explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. the record must exist), and never names alternatives such as add_individual or set_event. 'Only supplied fields change' is a behavioral note, not routing guidance.

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