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

With no annotations, the description discloses the HTTP method per action (GET vs POST), marks parse as the only write ('Writes: parse only'), and explains the raw flag's effect on output. It also notes how matches are persisted as DNA associations. It stops short of auth/error/pagination details, so it is strong but not exhaustive.

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 purpose, then organized into Actions, Args, and Returns. It is compact yet information-dense, with no redundant sentences or filler, and the formatting makes the multi-action behavior 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?

Given the absence of an output schema, the description explains the return dict and the per-action content (matches, clade, parsed segments), and covers all invocation details. It lacks error handling and detailed result shapes, but for a three-action analysis tool the essential context 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 coverage is 0% and there are no enums in the schema, so the description must carry the full parameter burden. The Args section defines all five parameters, maps action values, states which parameters are required per action, and gives the default for instance. This fully compensates for the bare input 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 opens with a concrete purpose, 'DNA match analysis and raw match-string parsing', then enumerates three distinct actions (matches, ydna, parse) with endpoints and output content. This clearly identifies the resource and distinguishes the tool from the manage_* siblings, which focus on entity CRUD rather than DNA-specific analysis.

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 action list gives explicit context for each mode and required parameters, and it points to manage_person/manage_note for how DNA associations and notes are stored, and to get_instances for the instance parameter. It does not state an explicit when-not-to-use rule, but the references to sibling tools provide enough routing guidance.

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

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

With no annotations provided, the description carries the full burden and does so excellently. It explicitly states 'Read-only' and reveals the return shape, including the conditional behavior of the 'scope' field when GRAMPS_MCP_INSTANCES is unset. This leaves little ambiguity about side effects or expected results.

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 tightly structured with a header, args section, and returns section. Every line contributes meaningful information, and the core purpose and read-only nature are front-loaded. No unnecessary elaboration exists.

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 the tool's zero-parameter complexity, no output schema, and no annotations, the description is fully sufficient. It provides the return dict shapeaine, the meaning of the fields, and the fallback behavior. No critical operational detail 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?

There are zero parametersholistic, so the baseline of 4 applies. The description's 'Args: (none)' matches the empty schema and adds no misleading expectations. Parameter semantics are not a concern for this tool.

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

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

The description states a specific verb and resource: 'List the configured target instances.' This accurately reflects the tool's function and clearly differentiates it from the sibling management tools like manage_person or manage_place. The 'Read-only' qualifier further distinguishes it from mutating operations.

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: whenever an agent needs to see the configured target instances or discover the scope. However, it does not explicitly state usage context or mention alternatives, relying mostly on the self-evident nature of a zero-parameter read-only query.

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?

No annotations are present, so the description carries the full behavioral burden. It discloses read-only semantics, the two endpoint behaviors, heuristic defaults, and the return dict, which is strong context; it omits only peripheral details like error/edge-case 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?

The description is front-loaded with the core purpose, then uses compact code-style lines for modes and a structured Args/Returns layout. Every sentence adds actionable information without 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 6-parameter tool with no output schema and no annotations, the description covers purpose, modes, parameters, defaults, and return shape. It lacks only a concrete example or an explanation of the 'status' key, but the overall invocation context is essentially complete.

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

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

Schema description coverage is 0%, but the Args section documents every parameter with its meaning, allowed values for mode, constraints for the heuristic integers, and the source of instance. This fully compensates for the schema 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?

The opening line states a specific verb and resource: 'Estimate whether (or until when) a person is alive.' The read-only note and the mode/endpoint explanation make the intended domain unmistakable and separate it from the management/search 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?

The description explains when to choose 'status' versus 'dates' and tells the agent to source the instance from get_instances with a default of first. It does not explicitly name sibling exclusions, but the purpose and mode guidance are clear enough for correct selection.

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

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

The description explicitly declares 'Read-only,' which is the key behavioral trait, and also discloses the endpoint pattern, the optional depth cap, and the shape of the return value. Without annotations, this provides a solid safety profile, though it omits error behavior and authentication needs.

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 well-organized with a front-loaded summary, a mode explanation, and clear Args and Returns sections. Each sentence carries functional information with minimal 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 read-only two-person relationship computation with no output schema, the description adequately explains both modes, the returned dict keys, and the endpoint. It gives an agent enough to call the tool correctly, with only minor edge-case details absent.

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

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

With schema description coverage at 0%, the description compensates fully by explaining all five parameters, their meanings, defaults, and constraints such as depth defaulting to 15 with a minimum of 2 and instance defaulting to the first. This adds substantial value beyond the bare 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 clearly states the operation with a specific verb and resource: 'Compute a genealogical relationship between two people.' The mode breakdown and read-only note add precision, making it easy to distinguish from siblings like get_timeline or analyze_dna.

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 explains when to use the default mode versus all=true, covering the trade-off between the shortest relationship and all possible relationships. It does not explicitly name sibling alternatives, but the context is clear enough for selection.

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

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

The description explicitly states 'Read-only' and details the full scope of metadata returned, including the conditional behavior when `surnames` is true. It also discloses the return envelope ('status', 'url', 'data'). Since no annotations are provided, the description carries the burden and does a solid job, though it doesn't mention potential errors or rate limits.

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

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

The description is well-structured with a clear opening sentence, a detailed but organized list of metadata categories, and a compact Args/Returns section. It is slightly long but every sentence adds value, and the key read-only nature is front-loaded.

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

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

For a read-only metadata tool with 2 optional parameters and no output schema, the description is quite complete: it lists the endpoint, the metadata contents, the parameter effects, and the return envelope. It lacks explicit error/edge-case behavior, but that is a minor gap for this simple tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `surnames` ('If true, include the full list of surnames') and `instance` ('Gramps Web base URL from get_instances; default = first'), adding meaning beyond the bare schema. It could be more explicit about the format of `instance`, but it is adequate.

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 ('Read') and resource ('Gramps Web server, database, locale and object-count metadata'), and enumerates the exact metadata categories returned. It clearly distinguishes itself from siblings like ping and get_instances by naming the wrapped endpoint (GET /metadata) and listing its contents.

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 explains what the tool returns and mentions the `instance` parameter defaulting to the first from get_instances, which implies a relationship to get_instances. However, it does not explicitly state when to use this tool versus alternatives like ping or get_instances, nor does it state when not to use it.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: it explicitly declares the operation read-only, describes the returned dict shape, and documents behavioral flags like strip, discard_empty, omit_anchor, and ratings. It also exposes underlying endpoint routing, which is valuable behavioral context beyond the schema.

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

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

The description is long, but it earns its length by covering 15 parameters and endpoint variants. It is well-structured with a clear overview, endpoint mappings, a bulleted Args list, and a Returns line. Slightly tighter wording could trim verbosity, but no sentence is filler.

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

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

For a complex tool with 15 parameters, no output schema, and no annotations, the description is essentially complete. It explains every parameter, the required/optional relationship, the return structure, and even the default instance behavior. An agent has enough context to call this tool correctly without additional lookup.

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 0%, so the description must explain all 15 parameters, and it does. Each arg gets a meaningful explanation: kind values, handle requirements, page/pagesize semantics, boolean toggles, precision meaning, generation counts, and the query dict contents. This fully compensates for the empty schema descriptions.

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

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

The description states exactly what the tool does: it returns a chronological event timeline for a person, family, or tree-wide scope. It also marks the operation as read-only and distinguishes the allowed resource kinds. This is a specific, unambiguous purpose that an agent can act on immediately.

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 clear usage context by mapping each `kind` value to an endpoint and stating which parameters apply to which kind, including the handle requirement for person/family. It does not explicitly name sibling alternatives or state when not to use this tool, but the guidance for selecting kind and scope is strong enough to route an agent correctly.

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 no annotations, the description carries the behavioral burden. It clearly discloses read vs. write operations, idempotent add, existence validation, DELETE semantics, and per-user/per-type scoping. It does not cover auth requirements or error behavior for removing nonexistent handles, but this is sufficient for a bookmark management tool.

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

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

The description is front-loaded with a concise summary, then organized into compact Arg and Returns sections. Every sentence adds useful operational detail such as HTTP verbs, idempotency, and defaults, with 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?

Given the minimal schema, absent annotations, and no output schema, the description is thorough: it documents all parameters, behavior, defaults, and the return structure. It provides enough context for an agent to select and invoke the tool correctly without additional external information.

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 0%, so the description must compensate. It does so fully: namespace values are enumerated, all action values are listed, handle is described as required for add/remove, and instance is tied to get_instances with a default. This adds significant meaning beyond the bare 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 opens with 'Read or edit bookmarks per object namespace,' which names a specific verb and resource. It then enumerates the exact actions (list_all, list, add, remove), making the tool's purpose unambiguous and distinguishing it from the other manage_* 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?

The description gives clear per-action usage: what each action does, the corresponding HTTP endpoint, idempotency, default behavior, and the requirement for handle on add/remove. It does not explicitly compare against sibling tools, but the namespace scope and action semantics leave little ambiguity.

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

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

With no annotations, the description carries the full burden, and it discloses the important behavioral traits: HTTP methods for each write action, handle requirements, the fact that get with absent handle returns a list, and the return shape {'status', 'url', 'data'}. It highlights 'Writes: create, update, delete' so agents know mutations are involved. It does not cover error behavior or pagination, but it is transparent about the core operation semantics.

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 well-structured with sections for purpose, action behaviors, payload fields, arguments, and returns. It is front-loaded with the overall purpose. There is minor redundancy: 'Create, read, update or delete' is immediately followed by 'Writes: create, update, delete,' which adds little. Overall it earns its length, but a small trim would improve conciseness.

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 the absence of annotations and output schema, the description covers the essentials: purpose, per-action semantics, parameter requirements, expected payload fields, return format, and instance default. It also explains how to attach citations to other Gramps objects, which addresses cross-tool usage. Missing details include pagination for list reads, error/status value ranges, and concrete query parameter examples, but these are minor given the tool's CRUD nature.

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 0%, so the description's parameter explanations are essential and well-delivered. It explains each of the five parameters, including action-specific requirements (handle needed for get-one/update/delete, data required for create/update), and it enumerates Citation payload fields beyond the schema. This adds substantial meaning that the input schema alone lacks.

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 precise statement of scope: 'Create, read, update or delete Gramps Citation records.' It further distinguishes the tool from siblings by detailing Citation-specific fields (source_handle, gramps_id, citation_list) and how citations attach to Person/Family/Event objects. This makes the tool's resource and actions 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?

The description clearly explains when each action applies: get with empty handle lists citations, get with handle returns one, create/update/delete operate on a specific citation. It also provides integration guidance ('Attach a citation to a Person/Family/Event by adding its handle to that object's citation_list'). However, it does not explicitly name alternatives or say when not to use this tool, though the sibling names make the resource boundary clear.

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 no annotations, the description carries the full burden of behavioral disclosure. It covers the actions, parameters, and return format, but does not mention side effects, permissions, reversibility, or error handling. Adequate for a CRUD tool, 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?

The description is well-structured with sections for actions, parameters, and returns. It is concise enough to scan, though the example field list could be trimmed. Front-loaded purpose is clear.

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 5 parameters, nested objects, no output schema, and no annotations, the description covers the essential operational aspects: actions, parameter semantics, return shape, and a note on typical usage context. It lacks error handling or edge-case details, but is largely complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains every parameter: action options, handle requirement for get-one/update/delete, data structure with example fields, query for read parameters, and instance sourcing. This far exceeds the schema's bare property names.

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 explicitly states 'Create, read, update or delete Gramps Event records', using a specific verb and resource. It clearly distinguishes this from sibling tools (e.g., manage_person, manage_family) by focusing on Event records, and enumerates the four CRUD actions.

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

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

The description provides useful context (e.g., events are referenced by Person/Family event_ref_list entries) and notes the instance default from get_instances. It does not explicitly contrast with sibling tools, but the event-specific scope makes the intended usage clear.

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 no annotations, the description carries the behavioral burden. It discloses that run is an asynchronous operation returning a task reference, file is synchronous returning base64, and exports apply to the whole tree unless filtered. It also flags 'Writes: run' as a side-effect indicator. Missing auth and failure details, but this is solid behavioral coverage.

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

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

The description is dense but organized: an opening summary, action-by-action bullets, a filtering note, an options list, and an Args/Returns layout. The long options list is justified because the schema has no descriptions. There is minimal filler, though the length is near the upper bound.

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 no annotations, no output schema, and four parameters, the description supplies nearly everything needed: action semantics, extension constraints, option keys, instance defaulting, return shape, and async polling guidance. It is complete enough for an agent to select and invoke the tool correctly without opening other resources.

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 0% and no enum values are provided, so the description must define the parameters. It does: action values are listed as 'list', 'info', 'run', 'file'; extension is described as required for info/run/file with examples; options is explained as a dict of query parameters with many named keys; and instance is given a default. This fully compensates for the sparse 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 resource ('exporters'/'export file') and concrete verbs for each mode: list, info, run, file. It also names file formats (GEDCOM, Gramps XML, CSV), which distinguishes it from siblings like manage_import and manage_report.

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

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

The description gives clear per-action guidance: use list to enumerate exporters, info to describe one, run for asynchronous export, and file for synchronous base64 export. It also points to manage_transaction for polling. It does not explicitly state when not to use this tool versus other management tools, but the action breakdown provides strong contextual 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?

With no annotations, the description carries the full burden, and it delivers: it exposes HTTP semantics (POST/PUT/DELETE/GET), the side effect that creating a family rewrites parents/children person records, and the permission requirement. It also documents the return envelope, making behavior predictable.

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

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

Well-organized with a short intro, operation details, args, and returns section, and key caveats are front-loaded. The 'Writes: create, update, delete' line is mildly redundant with the opening sentence, costing a point, but the rest is efficient.

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?

The tool has 5 parameters, nested objects, no annotations, and no output schema, so the description must be self-sufficient. It covers operation modes, required fields, side effects, permissions, return shape, and cross-tool instance handling. Nothing essential for selecting and invoking the tool correctly is missing.

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

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

Schema coverage is 0%, and the description fully compensates by defining every parameter: action values, handle requirements per operation, data payload requirements, query usage, and instance sourcing default from get_instances. It also provides a field list for the Family payload beyond what the schema exposes.

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, read, update or delete Gramps Family records') and enumerates the exact action values and their semantics. This distinguishes manage_family from sibling CRUD tools like manage_person/manage_event by resource type and operation.

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 operational context: which action to use for listing vs single fetch, which params are required per action, and notes that creating requires edit+add permissions upstream. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description carries the behavioral burden and meets it: it discloses that file/restore are writes, that restore replaces all content, that it requires batch delete permission, and that dry_run avoids touching the tree. Endpoints are given, making side effects traceable.

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 a one-line summary, then action modes, args, and returns in scannable blocks. The length is justified by the number of actions and no sentence is redundant.

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

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

For a five-parameter multi-action tool with no annotations and no output schema, the description supplies everything necessary: endpoint semantics, per-action requirements, permissions, destructive behavior, dry-run safety, and the return dict shape. No operation-critical detail is left 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?

The schema provides only names/defaults with no descriptions or enums (0% coverage), but the Args section defines all five parameters, states which actions require each, lists acceptable extensions, and explains dry_run/instance behavior. This fully compensates for 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 opening line names a concrete verb-resource pairing ('List importers or import a family tree file') and then breaks out four action modes with endpoints, so an agent can tell manage_import apart from export/search tools. The multi-action nature is explicit rather than hidden.

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?

Action-specific guidance is strong: list/info/file/restore each have distinct endpoints and required parameters, and dry_run is flagged as the safe preview path. However, the description does not explicitly contrast with sibling tools such as manage_export or manage_tree, so the when-vs-alternatives guidance is implied rather than stated.

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

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

With no annotations, the description carries the behavioral burden and covers a lot: upload streams file_path and computes checksum/creates the Media row, binary endpoints return base64, and the return shape is documented. It falls slightly short by not addressing auth/permission needs or reversibility, and face_detection parameters are deferred to upstream.

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

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

The description is long but well organized: summary, operation bullets, Args, and Returns. It front-loads the core purpose and action list; there is minor redundancy between the operation bullets and the Args section, but it remains scannable and purposeful.

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 the tool's complexity—8 parameters, 9 actions, no output schema, and no annotations—the description covers action semantics, endpoint patterns, required-parameter relationships, and the return envelope. An agent has enough information to select and invoke this tool correctly for each listed action.

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 0%, but the Args section documents all 8 parameters, including valid action values, which actions require handle/data/file_path/mime_type/size, and the default behavior for instance. This fully compensates for the empty schema descriptions.

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

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

The description opens with a specific verb and resource: 'Manage Gramps Media objects and their files.' It enumerates the full action set (get/create/update/delete/upload/file/thumbnail/ocr/face_detection) and distinguishes itself from siblings by referencing manage_person for the CRUD pattern and merge_objects for duplicates.

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 per-action usage semantics and required parameters, and explicitly recommends merge_objects for duplicate media. It does not explicitly enumerate when not to use each sibling manage_* tool, but the resource-specific focus and sibling names make the intended use clear.

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 no annotations provided, the description carries the full behavioral disclosure burden. It clearly states the read vs. write nature, maps actions to HTTP verbs, identifies required vs. optional parameters per action, and specifies the return shape. It stops short of detailing side effects such as delete permanence, overwrite semantics, or error behavior, but it is substantially transparent for a CRUD tool.

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

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

The description is well-structured with action breakdown, payload fields, Args, and Returns. The opening sentence and the following 'Writes: create, update, delete.' are slightly redundant, but the rest of the content is dense and purposeful, with key behavioral and parameter details front-loaded.

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

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

For a five-parameter CRUD tool with no output schema and no annotations, the description is quite complete: it explains action semantics, payload field examples, relevance to other objects' note_list fields, the analyze_dna connection, and the return contract. Minor gaps remain around full Note object schema and error/edge-case behavior, but the essential invocation context 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?

The schema has 0% description coverage, so the description must compensate, and it does comprehensively. The Args section explains each parameter in context: allowed action values, handle requirements by operation, data payload obligations, query as optional read-time parameters, and instance sourcing from get_instances. This adds real meaning beyond the bare schema fields.

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

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

The description opens with a clear CRUD verb and resource: 'Create, read, update or delete Gramps Note records.' It distinguishes manage_note from the many sibling manage_* tools by scoping to Note records, and the action-based breakdown removes ambiguity about what each operation 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?

The description gives operation-specific guidance: `action=get` lists or fetches one note by handle, while create/update/delete have distinct payload and endpoint requirements. It also points to analyze_dna for DNA match segment strings in notes, offering a relevant sibling alternative, though it does not exhaustively list when not to use the tool.

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

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

No annotations are present, so the description correctly carries the burden of disclosing side effects: it labels create/update/delete as writes and states that delete removes the record. It also discloses server-assigned handles and that GET with a handle returns one person while an empty handle lists people.

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 well-structured with a one-line purpose, action bullets, Args, and Returns headers, making it easy to scan. The 'Writes: create, update, delete' line is somewhat redundant with the opening sentence, but it is short and does not materially bloat the text.

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

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

For a CRUD tool with minimal schema, no annotations, and no output schema, the description covers the core invocation contract: supported actions, parameter roles, expected payload shape, query options, instance selection, and return dict structure. It does not enumerate every Gramps schema field, but explicitly defers to the Gramps schema and gives representative 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?

Schema description coverage is 0%, but the Args section compensates fully, adding meaning for all 5 parameters: action options, handle requirements, data object content, query dictionary examples, and instance default. It also specifies which parameters are required for which action, going well beyond the schema's minimal type-only properties.

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 'Create, read, update or delete Gramps Person records,' naming a specific verb set and resource. The action-by-action breakdown (get/create/update/delete) and reference to Person payload fields makes it clearly distinct from the sibling manage_* tools for other record types.

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

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

It gives clear context for when to use manage_person: any Person record CRUD operation, with action-specific usage (`get` for list/one, `create` for new, etc.). It does not explicitly name alternatives or exclusions, but the sibling names manage_family/manage_source make the resource boundary obvious.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly discloses that this is a mutation tool, maps each action to an HTTP verb/endpoint, and states the return dict shape. It does not mention auth requirements, reversibility, or side effects of updates/deletes, but it provides substantially more behavioral context than the schema 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?

The description is well-organized and front-loaded with the core purpose. It is slightly redundant: the opening sentence already says 'create, read, update or delete,' and the next sentence repeats the write subset. Overall the extra length is justified by the lack of annotations and output schema, but a small redundancy keeps it from being maximally concise.

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 CRUD tool with five parameters, no annotations, and no output schema, this description is remarkably complete. It covers every parameter, the operation-specific behavior, the return structure, and the relationship to search. The open-ended Place object and query parameters would benefit from more examples, but the essential invocation context is fully 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 coverage is 0%, yet the description compensates thoroughly: it defines action values, explains when handle is required, identifies data as the Place object payload, clarifies query as read-only extra parameters, and states the instance default. It also lists common place payload fields, which the schema does not document at all.

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

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

The description opens with a specific verb and resource: 'Create, read, update or delete Gramps Place records.' It then maps each action to concrete behavior, making it unmistakable what the tool operates on. It also distinguishes itself from the search sibling by noting it returns raw object data rather than full-text hits.

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 explicitly says to use manage_place over search when raw object data is needed rather than full-text hits. It also explains the list-versus-single-read behavior based on whether handle is empty, giving an agent clear selection and invocation 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?

With no annotations, the description carries the behavioral burden. It discloses that run is asynchronous ('generates a report in the background ... returning a task reference'), file is synchronous and returns base64, and result downloads a previously generated file. The 'Writes: run' marker adds a useful side-effect hint, though auth and cleanup behavior are not addressed.

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

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

The description is long but every sentence adds necessary information for a six-parameter, five-action tool. The structure is well organized: overview, action-by-action semantics, argument list, and return summary. The most important action distinctions are 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 the tool's complexity, no output schema, and no annotations, the description is thorough. It covers all six parameters, all action modes, return shape ('{"status", "url", "data": reports, task ref, or base64 file}'), and even explains how to provide the filename for result. An agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description fully compensates. It explains each parameter, enumerates valid action values, clarifies when report_id is required, describes options as a JSON dict, notes locale defaults, and explains include_help and instance, including its source from get_instances.

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 specific verbs and a resource: 'List, configure or generate Gramps reports' and enumerates five concrete actions. It clearly delimits what type of report operations are supported and differentiates the internal action modes without ambiguity.

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?

Each action is described with its exact HTTP endpoint and purpose, and parameter prerequisites are stated, e.g. 'report_id: Report id ... required for info, run, file, result'. It provides strong practical routing within the tool, though it does not explicitly compare against sibling tools such as manage_export.

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 no annotations provided, the description carries the full behavioral burden. It explicitly discloses that create/update/delete are write operations, states the HTTP methods used, and notes that delete removes the repository. It also explains how an empty handle changes get behavior. It could add permission or error details, but the core side effects are visible.

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 well structured with a summary line, then action details, payload guidance, and an Args/Returns block. It is longer than strictly necessary, with some redundancy between the first line and 'Writes: create, update, delete,' but every section adds practical value and is 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?

Given the tool has no annotations and no output schema, the description does a good job covering actions, parameter semantics, payload fields, and the return dict shape. It falls short of fully specifying the Repository object structure, but the listed fields plus the ellipsis and the CRUD details make the tool usable in most cases.

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 0%, so the description must explain all parameters, and it does. It defines the valid action values, when handle is required, when data is required, what query is for, and that instance comes from get_instances with a default of the first instance. It even lists common payload fields, fully compensating for the sparse 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 opens with a specific verb and resource: 'Create, read, update or delete Gramps Repository records.' It clearly identifies the resource type, distinguishes it from sibling manage_* tools for other Gramps objects, and immediately clarifies that this is the CRUD tool for repositories.

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

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

The description gives clear operation-level guidance: get can list or fetch one, create requires a payload, update uses a handle, and delete removes the record. It also notes that sources link to repositories via reporef_list, providing helpful context. It does not explicitly name alternative tools for non-repository records, but the resource-specific framing makes appropriate usage clear.

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 no annotations provided, the description bears the full burden of disclosing behavior. It clearly states the operations are read/write, including the destructive delete, and outlines the request/response shape: 'Returns: dict: {"status", "url", "data"}.' It specifies the payload fields and the default instance. It doesn't mention authorization requirements or irreversible side effects explicitly, but the description of delete as 'removes it' implies the effect. This is solid behavioral transparency for a CRUD tool without 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 description is a bit long but well-structured with clear sections: a one-line summary, a paragraph detailing each action's HTTP method and payload, a bullet list of payload fields, an Args block, and a Returns block. Information is front-loaded with the core purpose and action semantics before details. Every sentence adds value; there's no fluff. It could be slightly tighter, but it's appropriately sized for a CRUD tool with five parameters.

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 the tool's complexity (CRUD with multiple parameters and nested objects) and the absence of annotations or an output schema, the description is remarkably complete. It covers all actions, parameter requirements, payload structure, the return format, and even the default instance behavior. It also directs the agent to manage_citation for citation handling, preventing misuse. An agent can confidently invoke this tool correctly based on the description alone.

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 0%, so the description must fully explain each parameter. It does: action lists the allowed values, handle is marked as required for get-one/update/delete, data is required for create/update, query is described as 'optional dict of extra query-string parameters for reads,' and instance is noted as defaulting to the first from get_instances. This exceeds what the schema provides, giving an agent complete parameter semantics without needing to guess.

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 precise statement of the tool's function: 'Create, read, update or delete Gramps Source records.' It names the resource (Source records) and the four verbs, clearly distinguishing it from siblings like manage_citation, which handle a different entity. The actions are spelled out (get, create, update, delete) with concrete HTTP semantics (POST, PUT, DELETE), so an agent can immediately identify the tool's 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?

The description explains when each action is appropriate: 'action=get lists sources (handle empty) or returns one source by handle; action=create posts a full Source JSON object...' It also provides a pointer to an alternative for related data: 'Citations of a source are managed with manage_citation.' While it doesn't explicitly list exclusions or when not to use the tool, the action breakdown and the citation pointer give enough context to route correctly. It also notes the instance default, aiding selection in multi-instance setups.

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 no annotations, the description carries the full behavioral burden and does well by identifying which actions are writes, describing the HTTP endpoint patterns, and stating the return dict shape. It does not mention permissions, authentication, or cascading effects of deletion, but the core write/read behavior is transparently 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?

The summary sentence is front-loaded, followed by tight behavioral details and a structured Args/Returns layout. Despite being longer than typical descriptions, each sentence contributes needed information and there is no filler or repetition.

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

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

For a 5-parameter CRUD tool with no output schema and no annotations, this description covers all invocation scenarios, parameter semantics, return shape, and even cross-object guidance about tag_list. An agent has enough context to select and call the tool correctly without opening sibling definitions.

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 0%, yet the description's Args section compensates fully: it defines the allowed action values, when handle is required, what data contains, the optional nature of query, and the instance default from get_instances. Every parameter is given meaning beyond its bare type in the schema.

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

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

The description opens with 'Create, read, update or delete Gramps Tag records,' a specific verb-resource pairing that immediately distinguishes it from the many manage_* siblings such as manage_person and manage_source. The added note that tags are 'lightweight labels attachable to any object' further clarifies the resource's role.

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?

Action-specific usage is explicit: get lists tags when handle is empty or returns by handle, create requires a name, update PUTs data, delete removes by handle. It also gives cross-context guidance ('To tag an object, reference the tag handle in that object's tag_list'), though it does not explicitly state when not to use this tool versus other manage_* 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?

With no annotations, the description carries the behavioral burden and largely succeeds: it states 'Writes: all actions', warns about cross-reference maintenance and corruption risk, and discloses that delete_objects is async. The slight overbreadth of 'Writes: all actions' given read-only history/history_id GETs keeps this from 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?

The description is long but well organized: summary line, per-action endpoint map, safety warning, then Args. Every line carries operational value, and the risk warning is prominently placed near the top.

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 multi-action tool with no output schema or annotations, this is unusually complete. Every action has an endpoint, required arguments, and return shape ('status', 'url', 'data'), and nothing essential for safe invocation is missing.

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

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

Schema description coverage is 0%, so the Args section is essential and highly informative. It defines the allowed action values, the conditional transaction_id requirement, payload shape per action, namespace/handles for deletes, and params options. It goes well beyond what the bare schema provides.

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

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

The description leads with a concrete verb phrase: 'Apply raw DB transactions, undo history, or bulk create/delete' and enumerates every action. It differentiates from sibling manage_* tools by labeling these as low-level operations that object endpoints cannot express and advising typed tools for single-record work.

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

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

It explicitly scopes this tool to 'Low-level database operations that the object endpoints cannot express' and says 'Prefer the typed manage_* tools for single-record work'. It also warns that malformed raw apply can corrupt a tree, giving clear routing and safety criteria.

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 no annotations provided, the description fully carries the behavioral burden. It explicitly separates read actions from writes, explains what each action does (create, disable/enable, repair, migrate, verify, config_set), documents the missing delete endpoint, and states the admin-only requirement.

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

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

The description is long but dense and well-structured: a one-line summary, action-by-action breakdown, parameter list, and return shape. It front-loads the core purpose and every section earns its place given the tool's 11 distinct actions and 4 parameters.

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?

This is a complex tool with no output schema and no annotations, yet the description covers action semantics, parameter constraints, permissions, an important deletion caveat, and the return structure. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does comprehensively. Each parameter is explained: action values are listed, tree_id semantics including '-' for current tree are given, data requirements include the required 'name' field for create, and instance is defined with a default and a reference to get_instances.

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

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

The description opens with a specific verb and resource: 'Inspect or administer Gramps Web family trees.' It then enumerates every supported action, making it unambiguous what the tool does and clearly distinguishing it from sibling manage_* tools that target different Gramps resources.

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

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

The description gives clear operational context: it lists all action modes, marks the tool as admin-only, and explicitly notes that deletion is not supported and should be done via the server CLI. It does not name a sibling tool to prefer for tree viewing, but the resource-specific scope is enough for an agent to select it correctly.

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

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

The description explicitly states the tool is read-only, which is important behavioral context. It also discloses that 'action=all' merges default and custom types, and that 'locale' translates default type names. While there are no annotations to contradict, the description could add more about error cases or rate limits, but it covers the key behavioral traits well.

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 detailed but well-organized, with a clear opening summary, a list of actions, and a parameter breakdown. It is longer than minimal but every sentence adds value. The structure (summary, action list, datatypes, args, returns) makes 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?

Given the tool's moderate complexity (4 parameters, 6 action modes, no output schema), the description is quite complete. It explains the return shape ('status', 'url', 'data'), enumerates datatypes, and covers all parameters. It could mention potential errors or the exact structure of the returned vocabulary dict, but overall it's sufficient for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It does this well: 'action' is fully enumerated, 'datatype' is explained with examples and when it's required, 'locale' is described, and 'instance' is tied to get_instances. The only minor gap is not detailing the exact format of the 'instance' parameter beyond 'base URL'.

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 clearly states the tool's purpose: listing Gramps type vocabularies (custom + default) for all object types, and explicitly notes it is read-only. It distinguishes itself from sibling tools by focusing on type vocabularies rather than managing specific records like persons, families, or events.

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 explicit guidance on when to use this tool and how to select among its actions. It enumerates each action value ('all', 'defaults', 'default', 'default_map', 'customs', 'custom') and explains what each returns, plus when 'datatype' is required. This is comprehensive usage 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?

With no annotations, the description carries the behavioral burden, and it does so well: it states that create/update/delete/change_password write data, exposes the underlying HTTP verbs (GET, POST, PUT), notes the permission requirement, and defines the return dict. The only residual ambiguity is 'most actions' for permissions, which does not specify which actions are exempt.

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 a one-line purpose and write warning, then uses a structured action list, Args block, and Returns block. Everything present earns its place, and the detailed endpoint mapping is organized rather than verbose.

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?

This is a multi-action admin tool with a nested data object and no output schema, yet the description covers operations, required fields, permissions, endpoints, instance selection, and return shape. An agent has enough context to select and invoke each action without needing to inspect the API.

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 0%, but the description fully compensates: it enumerates valid action values, states when user_name is required, specifies data fields per API call, and documents the instance default. This is far more actionable than the bare JSON Schema with only titles and defaults.

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 the specific verb-resource pair 'Administer Gramps Web users' and then enumerates six concrete actions (list, get, create, update, delete, change_password). This clearly distinguishes it from sibling manage_* tools because the resource is users and the action set is explicit.

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

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

The action-by-action breakdown tells an agent exactly which parameters are needed for each operation, and 'instance: Gramps Web base URL from get_instances' explicitly routes to a sibling tool. It lacks an explicit 'use X instead for non-user administration' statement, but the naming and content make the tool's domain unambiguous.

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

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

With no annotations supplied, the description carries the full disclosure burden and meets it: it says the operation 'writes', that handle2 is 'absorbed and deleted', that handle1 survives, and that edit+delete permissions are required. This clearly flags a destructive mutation with permission prerequisites, which is exactly the behavioral context an agent needs.

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 organized with a terse overview, semantic details, permission/usage note, Args block, and Returns block. No sentence is filler; the phoenix/titanic metaphor and supported-type list are compact and high-value. It earns its length.

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

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

Despite no annotations and no output schema, the definition covers the tool's domain (same-type Gramps objects), destructive side effects, permissions, supported obj_type values, merge-option keys, parameter defaults, and a return-shape sketch. An agent has enough to select and invoke it correctly without additional context.

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 0%, so the description must define every parameter, and it does: obj_type is explained with a supported-value list, handle1/handle2 are given phoenix/titanic roles, data is clarified with person/family-specific keys, and instance is tied to get_instances with a default. This goes beyond the bare schema in every case.

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

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

The description opens with a specific action ('Merge two Gramps objects of the same type into one'), names the resource (Gramps objects), and immediately defines the directional semantics: handle1 survives, handle2 is absorbed and deleted. This makes the tool's role unmistakable and distinguishes it from the sibling manage_* tools, which handle single-object operations and duplicate probing.

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 workflow guidance: for duplicate handling use manage_* to probe first, then merge_objects to combine, and it states the required edit+delete permissions. It lacks an explicit 'use this only when...' contrast with manage_* for ordinary edits, but the merge-vs-manage distinction is strongly implied and actionable.

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

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

No annotations are provided, so the description carries the full behavioral burden. It explicitly states 'Read-only' and specifies the exact return value, which fully discloses the side-effect profile and output for this simple tool.

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

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

The description is compact and front-loaded: 'Health check. Read-only.' immediately conveys the action and safety profile, followed by minimal Args and Returns sections. No unnecessary words.

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

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

For a zero-argument health check with no output schema, the description is complete: it states the purpose, side-effect guarantee, and return format. There is no missing information an agent would need to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly documents 'Args: (none)', and the empty input schema provides complete parameter coverage.

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 clearly identifies the tool as a health check with a read-only guarantee and a specific return shape ({"pong": true, "version": ...}). It is distinct from the listed sibling tools, though it does not explicitly compare itself to any sibling such as get_server_info.

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 'Health check' implies the intended use case, but the description gives no explicit guidance on when to prefer this tool over alternatives or when not to use it. For a zero-argument ping endpoint this is adequate, but not as explicit as it could be.

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 no annotations, the description carries the full burden. It discloses read-only behavior, semantic vs full-text mode, pagination, sorting, filtering, and the return shape. Minor gaps remain around error behavior and index freshness, but these are not critical for correct invocation.

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 opens with purpose and read-only status, then delivers a tightly formatted arg list where every line adds value. No filler or repetition; the length is justified by 11 undocumented parameters.

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

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

For a complex 11-parameter tool with no output schema and no annotations, the description is thorough: it covers all parameters, return keys, mode selection, and alternatives. It could add more detail about hit shapes or error cases, but the agent can invoke correctly from this definition.

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 0%, so the description fully compensates. Every parameter is explained with syntax details, defaults, examples, and even the instance source. This goes far beyond the schema's bare names and types.

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?

Description states a specific verb and resource: full-text or semantic search across the Gramps tree, read-only. It distinguishes itself from manage_<type> tools by explicitly saying those are for known handles or raw object data.

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 to use manage_<type> with get/filter when you already know the handle or want raw object data, which is a clear when-not-to-use condition. The description also frames the tool as type-ahead style search across the index, making its intended context obvious.

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