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

Annotations only declare openWorldHint=false and destructiveHint=false, which says little for a write tool. The description compensates with a genuine transactional guarantee — 'All entries are added, or none are if any link is invalid' — which is exactly the kind of failure-mode behavior an agent needs before committing a batch. It does not cover permissions or duplicate handling, but the atomicity disclosure is substantive.

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

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

Four short sentences, zero redundancy, with the core capability and the single-person shortcut front-loaded. Every sentence adds distinct information — capability, single-entry case, linking model, atomicity.

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, return values need no explanation, and the description covers the two things that matter for correctness: how cross-entry linking resolves and what happens on failure. Missing only the edge cases an agent might hit — duplicate detection, whether existing ids must be pre-validated, and permission requirements.

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%, so the description must carry weight, and it does: it explains that batch entries link by 'ref (or name)' and to existing people by id, which clarifies the semantics of the parents/partners/siblings arrays beyond their terse schema notes. The remaining gaps are minor fields (sex, dates, notes) whose types are self-evident from the schema.

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

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

States a specific verb and resource ('Add one or many people') plus the relationships it creates (parent, partner, sibling links), and makes the batch-vs-single distinction explicit. It does not name the sibling it is not (update_people, merge_people), so the agent must infer from the verb that this is insertion rather than mutation of existing records.

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

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

'Use a one-entry list to add a single person' gives concrete guidance on parameterizing for the single-person case, and the atomicity sentence implies the precondition that all links must be valid. However, there is no guidance on when to choose this over update_people, merge_people, or find_people, nor on whether existing people should be looked up first.

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

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

The description discloses a real side effect not present in annotations: the entire website is republished on every call. That is valuable, especially with openWorldHint=true indicated by the annotations. However, it omits what 'replace' means for the previous code, whether the republish is immediate and visible to visitors, and what permissions are required.

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

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

One front-loaded sentence with no filler; the primary action and its consequence are both stated up front. It is arguably under-specified rather than verbose, so brevity is not the issue.

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 presence of an output schema relieves the description of explaining return values, and the republish side effect is covered. But for a site-altering write with a single undocumented, nullable parameter, the agent lacks enough to call it correctly when code is omitted.

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

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

There is a single optional parameter with 0% schema description coverage, so the description carries the full burden and does not meet it. It never explains the 'code' parameter: what language/format is expected, size limits, or critically what a null default means (clearing the custom code vs. leaving it untouched).

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 verb 'Replace' plus the specific resource 'site-wide photo editing code' and the explicit side effect 'republish the complete website' make the operation unambiguous. It is distinguishable from publish_site and configure_website by pairing a code replacement with the mandated republish, though it never names those siblings outright.

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?

Nothing states when this should be used rather than configure_website or publish_site, nor whether the republish is unconditional or only triggered by a change. An agent must infer that this is the right tool for photo-code customization rather than site publishing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral guidance: findings should be surfaced to the user and not auto-remediated, which an agent could otherwise get wrong. It does not describe result volume or ordering.

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, the diagnostic list first and the behavioral caveat second. Slightly dense phrasing ('children linked to only one of a couple') costs a little clarity but nothing is wasted.

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

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

With an output schema present, return values need not be explained, and the description covers the full set of checks plus the expected agent posture. Adequate for a single-parameter read-only diagnostic 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?

Only one parameter (tree) with 100% schema description coverage that already explains UUID-preferred-or-exact-name semantics and points at list_trees. The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

The description names a concrete verb (list) and enumerates exactly what is surfaced: children linked to only one parent in a couple, duplicate names, and placeholder parents. That makes it clearly distinct from mutation siblings like merge_people or update_people, though it never names an alternative 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 an implicit directive to report findings rather than fix them, which shapes how the agent should act, but there is no guidance on when to run this check versus calling merge_people or update_people directly. Usage context 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?

Annotations only declare openWorldHint=false and destructiveHint=false, leaving the mutation semantics to the text, which it supplies: it warns that reassigning a published project would move photo storage and URL by accident. That is genuinely useful risk context. It doesn't state required permissions or whether the change is reversible, keeping it out of the top band.

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

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

Two short sentences, front-loaded with the verb and the two fields affected, then the operating constraint. Nothing is redundant and the most important caveat follows immediately.

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

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

An output schema exists, so return values need no explanation, and the description covers the main hazard of a non-destructive config mutation. Only the parameter format details are missing for a tool with zero schema documentation.

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%, so the description has to carry both parameters, and it loosely does by naming 'website title' and 'Cloudflare project'. However it never clarifies the expected format (project name vs. project ID) or why both are required, so it only partially compensates 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?

A specific verb ('Set') paired with two concrete resources ('website title and Cloudflare project'), so the agent knows exactly what state is being changed. It doesn't explicitly contrast itself with siblings like publish_site or export_website, but the domain 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?

'Choose project before the first publication' gives explicit timing guidance, and the follow-on sentence states the exclusion: a published project cannot be re-pointed here and needs a separate installation. That is a clear when-to-use / when-not-to-use boundary, though no sibling tool is named as the alternative.

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 state openWorldHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds that the created tree is empty, which is useful state information, but it does not mention permissions, name uniqueness, or any side effects beyond creation.

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 short sentence with no filler, and the key fact that the tree is new and empty 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?

The tool has an output schema and annotations, so return values and safety are partly covered elsewhere. However, with zero schema description coverage and no parameter explanation, the definition leaves important input semantics and usage context unaddressed.

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

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

Schema description coverage is 0%, and the description does not explain either parameter. It does not clarify that 'name' identifies the new tree or that 'description' is optional and defaults to empty.

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 a specific verb and resource: create a new, empty family tree. The word 'empty' usefully distinguishes this from tools that add people or populate a tree, though it does not explicitly name a sibling alternative.

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 guidance on when to use this tool versus list_trees, rename_tree, delete_tree, or add_people. The intended context is only implied by the creation verb, with no prerequisites or exclusions.

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

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

Annotations already mark the tool as destructive. The description goes further by clarifying the exact behavior: only the tree definition is removed, shared people persist, and there is an 'undo' mechanism available to restore the tree. This is valuable behavioral context.

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

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

The definition is extremely concise, consisting of two highly effective sentences that cover the definition, behavior, and safety profile of the deletion.

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 definition is complete for an MCP tool. It clarifies the resource being managed (definition vs. people), its irreversible nature (destructive hint), and the existence of a recovery path (undo), which is essential context for a deletion function.

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

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

With 100% schema description coverage, the description adds minimal semantic value. It does not clarify the syntax or logical constraints of the input 'tree' beyond what is already stated in the schema and annotations.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a tree definition.' It distinguishes its scope by stating 'Shared people remain,' making it clear what the operation targets without needing to examine 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 implies usage by clarifying that it only removes the definition, suggesting that alternatives would be needed for more comprehensive deletions (like deleting users/people). However, it does not explicitly guide the user on which sibling tools to choose if they are attempting a different type of deletion.

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=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the build is local-only and includes every tree, but says nothing about where output lands, whether it overwrites a prior build, or how long it takes.

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 core action front-loaded and no filler. 'Chooser' is unexplained jargon, but the sentence does not waste 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?

An output schema exists, so return values need not be described, and the local-build/no-deploy behavior is clear. The remaining gap is the undocumented hide_living flag, which materially changes what gets exported.

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 single parameter hide_living (boolean, default true) has 0% schema description coverage and is not mentioned in the description. With no documentation anywhere, an agent cannot tell that this controls whether living people are excluded from the export.

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 action (build the complete site locally) and scopes it ('including chooser and every tree'). The phrase 'without deploying' implicitly separates it from publish_site, though no sibling is named.

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

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

'Without deploying' hints at when to prefer this over publish_site, but the guidance is indirect. There is no explicit statement of when to use this versus publish_site or configure_website, and no prerequisites mentioned.

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?

While the annotations cover the safety profile (readOnly), the description adds crucial operational behavioral traits, such as the matching logic ('matching every query word') and defining the tool's role as a discovery step, which is vital context.

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

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

The two sentences are highly dense with information, providing clear definitions of scope and workflow in a front-loaded, efficient manner.

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 complexity of the ecosystem (multiple tree and people manipulation tools), this description provides all necessary context for the agent to decide when to use this lookup function versus mutation tools like 'set_tree_members'.

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?

Since schema description coverage is 0%, the description must compensate. It successfully explains the intended use of 'tree' (scoping the search) and how to execute a global search (omitting it). It also defines the matching mechanism based on the 'query'.

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 defines the core action ('Find names matching') and immediately differentiates its scope: it searches globally ('shared collection') unless a specific tree is omitted.

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

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

It provides explicit workflow advice by stating 'Search globally before creating people' and gives a clear pathway for subsequent actions by mentioning the related tool, 'set_tree_members'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description contributes the generation-numbering semantics (1 = parents, 2 = grandparents), which is genuine behavioral context, but says nothing about whether omitting generations returns all depths, whether results are ordered, or how deep the traversal goes.

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 that front-loads the action and resource and spends the remainder on the one non-obvious semantic detail. Nothing redundant, nothing that restates the title.

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

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

For a read-only lookup with an output schema and mostly documented parameters, this is close to sufficient. The remaining gap is what happens when generations is omitted or set to null (all ancestors vs. a default depth), which an agent needs before calling without that argument.

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%: tree and person_id are documented in-schema, but generations has no description at all. The description fills exactly that gap by explaining the generation index meaning, which the agent could not infer from the bare integer/null schema; it still leaves the null default behavior undefined.

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

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

States a specific verb and resource ('List a person's ancestors') and defines the generation indexing scheme inline, so the agent knows exactly what shape of result to expect. It does not name the sibling get_descendants, which is the inverse operation, but the ancestor/descendant split is unambiguous from the names alone.

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

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

The scope of use (fetching relatives upward from a person) is implied clearly by 'ancestors by generation,' but there is no explicit guidance on when to prefer get_descendants, get_relationship, or get_person instead, and no stated prerequisites for choosing it over those siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the generation-numbering convention, but it does not explain what generations=null means, whether traversal is exhaustive by default, or any depth/result 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 a single efficient sentence with the key resource and generation convention front-loaded. There is no filler, and every part adds useful meaning.

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

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

An output schema exists and annotations cover the read-only safety profile, so return values and safety do not need description coverage. The main remaining gap is the optional generations parameter's default behavior, which is small but relevant for correct invocation.

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

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

The schema describes tree and person_id, but generations has no schema description. The description partially compensates by defining 1=children, 2=grandchildren, etc., but does not clarify null/default behavior or maximum depth.

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 a person's descendants, and it clarifies the generation numbering convention. It distinguishes itself from the sibling get_ancestors by direction, though it does not explicitly name or route away from that sibling.

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

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

Usage is implied by the resource: use this when you need a person's descendants. However, there is no explicit guidance on when to prefer it over get_ancestors, get_relationship, or get_person, and no exclusions or prerequisites are 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that family relationships are included in the result, but does not discuss missing-person behavior, permissions, or pagination; the output schema also exists, reducing the need for return-shape detail.

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

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

A single front-loaded sentence with no wasted language. It communicates the core action and included relationship data immediately.

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

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

Given the read-only annotations, full schema descriptions, and an output schema, the description is nearly sufficient: it identifies the resource and the included relatives. A small gap remains because it does not distinguish this tool from find_people or state that it targets a single already-known person.

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 (tree, person_id) are documented in the schema with UUID formats and sources. The description adds no parameter meaning beyond that, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get a person's details') and scopes it to immediate relatives (parents, partners, children, siblings). This partly distinguishes it from get_ancestors/get_descendants and find_people, but it never names those siblings or explicitly says it is for a single known person rather than a search.

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: the schema shows it requires a tree and person_id, which suggests the person must already be known. The description gives no explicit when-to-use vs find_people or when-not guidance, and no prerequisites or alternatives are named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description's one useful addition is directional framing (relative_id is described from person_id's perspective), but it says nothing about behavior when the two people are unrelated or in different branches.

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 zero waste, front-loading the action and embedding a concrete example instead of abstract prose. 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?

All three required parameters are documented, an output schema exists so return-value explanation is unnecessary, and annotations cover the safety profile. For a pure read/compute tool of this size, nothing an agent needs in order to call it is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description earns more by establishing directionality: person_id is the reference point and relative_id is the person being named relative to it. This is real added meaning, since the schema gives both parameters identical, interchangeable 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?

States a specific verb ('Name') and resource (kinship relation between two people), and the example 'first cousin once removed' makes the output unambiguous. It fails to distinguish itself from related siblings like get_ancestors or get_descendants, which also navigate kinship.

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 by the operation itself; the description never says when to prefer this over get_ancestors/get_descendants or get_person, nor what conditions make it appropriate. There are no alternatives or exclusions named.

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=true, openWorldHint=false). The description adds the useful fact that the entire tree is returned in one shot, which signals potentially large responses, but it doesn't mention pagination, size limits, or whether removed/archived people are included. Some added context, but not rich behavioral 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?

A single front-loaded sentence with the scope and the returned shape, no 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?

An output schema exists, so return-value detail is not the description's burden, and the one required parameter is fully documented upstream. For a simple whole-tree read the description is nearly sufficient; only the omission of any size/scope caveat on large trees keeps it from a 5.

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

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

Only one parameter and schema description coverage is 100%, with the schema itself explaining the UUID-or-exact-name convention and pointing at list_trees. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return the whole tree') and clarifies the payload shape ('every person with their parent and partner ids'), which distinguishes it from narrower siblings like get_person, get_ancestors and get_descendants. It stops short of explicitly naming those alternatives, so it's clear but not maximally differentiating.

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: 'the whole tree' suggests using this when you need the full dataset rather than a subset, but the description never says when to prefer get_ancestors/get_descendants/find_people instead, nor warns about cost on large trees. Adequate but leaves the agent to infer the routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a useful exposure boundary — the photo editing code is not returned — which is real context beyond annotations, but nothing about freshness, caching, or error behavior is given.

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 the read action and returned fields front-loaded. The trailing clause about photo editing code is slightly cryptic but does earn its place by scoping the response.

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

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

With an output schema present, zero parameters, and annotations covering safety, the description only needs to frame scope — which it does. The main shortfall is the absence of any routing hint among the many sibling tools.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the tool is target-free (no site ID argument needed).

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

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

States a specific verb and resource: 'Read site identity and publication status'. This distinguishes it from mutating siblings like configure_website, publish_site, and change_photo_code, though 'site identity' remains somewhat abstract.

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 call this versus alternatives such as export_website or get_tree; the agent must infer that this is the read-only inspection tool. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety context is covered. The description adds a useful behavioral detail (UUIDs are stable) and return fields, but does not mention ordering, pagination, or permission requirements.

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

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

A single, front-loaded sentence with no wasted words. It delivers the key contract immediately.

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

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

For a zero-parameter read-only listing tool with annotations and an output schema, the description is nearly sufficient. It could optionally note ordering or pagination behavior, but those are minor omissions given the structured data already available.

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 parameter semantics are not a concern; baseline 4 applies. No parameter-related claims 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 resource ('trees') and adds what the listing includes (stable UUIDs, descriptions, membership counts). The scope word 'all' implicitly contrasts with get_tree, but no sibling is named, so it stops short of full 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?

There is no guidance on when to use this versus alternatives like get_tree, check_tree, or find_people, and no exclusions or prerequisites. Usage must be inferred entirely from the tool name and one-sentence description.

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

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

Annotations only declare destructiveHint=true; the description goes further by specifying what survives (keep_id's missing details are filled, parents/partners/children are moved) and what is destroyed (the duplicate record). The 'applies across EVERY tree' note is important operational context. Minor gap: it does not say whether the merge is reversible via undo.

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 with the primary operation front-loaded and secondary use case after. 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?

Output schema and annotations cover the return shape and safety profile, so the description only needed direction, consequences, and scope — all present. The one loose end is whether `tree` must contain both people when the merge spans trees.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by defining the asymmetric roles of keep_id (survivor) and duplicate_id (consumed) — the schema only calls both 'Person UUID'. The meaning of the required `tree` parameter in a cross-tree merge remains slightly unclear.

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 (merge a duplicate) with explicit directionality (into keep_id) and the resulting effect (then remove the duplicate). This makes it trivially distinguishable from remove_person or update_people in the sibling list.

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

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

Gives two concrete usage contexts: deduplicating records and replacing a placeholder parent with the real person. It also flags the cross-tree scope. It lacks an explicit 'do not use when...' clause, but there is no competing merge tool among the siblings, so the guidance is effectively complete.

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?

It provides deep behavioral context beyond the annotations, specifying critical operational behaviors like 'all collection trees are public' and that 'living dates, places and notes are hidden by default.' It also discloses necessary external dependencies, namely Cloudflare authentication.

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

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

The definition is dense with high-value information, efficiently covering workflow, privacy rules, and technical requirements in a few sentences. It is generally well-structured, placing the critical site-wide scope first.

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

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

Despite the lack of parameter explanation, the description is exceptionally complete regarding the tool's operational environment (e.g., Cloudflare dependency, automatic rebuild mechanism, public visibility defaults). It covers all necessary high-level decision points.

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 coverage is 0%, meaning the description must define the inputs. It fails entirely to explain what the 'hide_living' or 'keep_updated' parameters specifically control or what their practical effect is on the published site.

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 tool clearly defines its purpose: to publish the ENTIRE configured website, specifically mentioning the scope of 'chooser and all trees.' This is precise and easily distinguishable from sibling tools like 'configure_website' or 'get_website'.

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 prerequisites and operational context, instructing the agent that it must 'First call configure_website.' It also defines inherent behavior (e.g., automatic rebuild after edits pause), which serves as a clear usage constraint.

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 destructiveHint annotation already signals danger, and the description adds important context beyond it: the deletion applies to all relationships and spans EVERY tree, which is a significant cascading side effect. It does not state irreversibility or whether undo applies, which would be useful for a destructive global operation, so it falls short of a 5.

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

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

Two short sentences with zero waste. The scope constraint is front-loaded, and the alternative routing sentence follows immediately.

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

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

Given a two-parameter tool with full schema coverage, a destructive annotation, and an output schema, the description provides exactly the missing decision-critical context: global scope and the single-tree alternative. An agent has enough information to select and invoke it correctly.

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

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

Schema coverage is 100%, and both parameters are well documented in the schema with format and source hints (tree UUID/name, person UUID). The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Delete a person') plus a critical scope qualifier ('all relationships from EVERY tree'). It also explicitly distinguishes itself from the sibling alternative set_tree_members(remove=True), so an agent can tell exactly what this tool does versus its closest alternative.

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

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

Gives an explicit when-to-use-this versus when-to-use-the-alternative rule: use this for deletion across every tree, use set_tree_members(remove=True) to remove only one tree appearance. The routing condition is unambiguous.

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

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

Annotations only declare destructiveHint=false and openWorldHint=false; the description adds real signal by stating that people, backups, and relationships survive the rename, which tells the agent this is a metadata-only mutation rather than a data-affecting one. It stops short of explaining whether the old name becomes reusable, whether the new name must be unique, or how the rename propagates to references.

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

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

Two sentences, front-loaded with the action and followed immediately by the consequence clause. Nothing is padded or restated.

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 annotations covering the safety profile, the description does not need to explain return values, and the data-preservation note covers the main behavioral concern. However, for a mutation tool with an undocumented required parameter, the absence of name constraints and error/failure conditions leaves a visible gap.

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

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

The 'tree' parameter is well documented in the schema (UUID preferred, or exact name as shown by list_trees), but 'new_name' has no description at all and the tool description adds nothing — no uniqueness requirement, character restrictions, or length limits. With only 50% schema coverage the description needed to compensate for the undocumented parameter and does not.

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 (rename) and resource (tree) in the first sentence, which cleanly separates it from create_tree, delete_tree, and get_tree in the sibling list. An agent can identify the operation without opening the schema.

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

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

Usage is implied by the verb — use it to change an existing tree's name — but there is no explicit when/when-not guidance, no mention of alternatives, and no stated precondition such as the tree existing or the new name needing to be unique. The 'kept' sentence hints at when this is safe versus delete_tree, which is a partial substitute for real 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?

While annotations confirm it is not destructive, the description provides high-value operational transparency. It explicitly states that no person is copied, relationships are maintained/visible within the tree scope, and that removing membership preserves global records.

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 and manages multiple pieces of information efficiently. Although not aggressively short, every sentence serves to clarify scope, input source, or behavioral guarantee.

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 description is highly complete for a complex membership management tool. It covers the source of the IDs, the scope of the operation (tree vs. all), and the persistence of relationships, addressing most potential ambiguities.

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?

Given the low schema coverage (33%), the description is vital for understanding parameter usage. It clarifies that the 'tree' parameter accepts either a stable UUID or the exact name derived from the `list_trees` tool, adding critical semantic context to the UUID/Name choice.

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 defines the dual purpose: adding members or removing membership. It successfully differentiates this tool from others by specifying that it operates on 'existing collection people' and handles relationship visibility within the tree.

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

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

It provides critical procedural guidance regarding parameter input. Specifically, it instructs the agent to reuse UUID identifiers obtained from the `find_people` sibling tool and specifies the condition under which the `tree` UUID can be omitted (to search all people).

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, so the low bar applies; the description still adds genuinely new behavior — that the revert spans all affected trees and that undone changes cannot be redone (irreversibility). It does not say what happens when no transaction exists or whether the revert is atomic.

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

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

Three short sentences, front-loaded with the action and scope, then the scope caveat, then the irreversibility warning. Every sentence carries distinct information.

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

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

With no parameters and an output schema present, the description only needs to convey scope and risk, which it does. The remaining gap is failure behavior (no transaction to undo, or partial failure across trees), which an agent would want before invoking a destructive global operation.

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

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

Zero parameters, so there is nothing to disambiguate and 4 is the baseline. The description correctly signals there are no targeting arguments by stressing the operation is inherently collection-wide.

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

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

Specific verb ('Revert') plus a precisely scoped resource ('the last collection-wide transaction, including all affected trees'). It explicitly distinguishes itself from per-tree history, so an agent can tell what it does and at what blast radius without opening the schema.

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

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

The 'global history, not per-tree history' clause tells the agent the condition under which this tool is the right choice versus any tree-scoped operation. It stops short of naming an alternative or stating when not to call it (e.g. when there is no transaction to undo).

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds genuinely non-redundant behavior: all-or-nothing atomicity ('Everything applies, or nothing does if any entry fails') and reversibility ('undo reverts it all in one step'). Minor tension remains, since link removal is a data-deleting act under destructiveHint=false, but the transactional and undo semantics are the useful additions.

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

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

Four short sentences, front-loaded with purpose and ending with the sibling redirect. Dense but every clause carries information; the link-direction sentence is slightly cryptic in phrasing but 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 the description covers the remaining agent-critical facts: what mutations are supported, atomicity, undo-ability, link directionality, and the alternative for adding people. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is only 33%, so the description must compensate, and it does for the highest-risk parameter: 'Each link reads "relative_id is person_id's relation"; set remove=true to remove it' disambiguates the direction of the relationship, which the schema's one-line 'What relative_id is to person_id' only partly covers. The ordering note ('details and renames, then links') also clarifies intra-call sequencing that the schema does not express.

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

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

The opening sentence names a specific verb and scope: 'Change many existing people at once: details and renames, then links to add or remove.' It also explicitly differentiates from the sibling add_people ('To add new people, use add_people'), so the agent can route without opening either schema.

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

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

'Use for one or many person updates or relationship changes' gives clear context and singles out the add case as belonging elsewhere. It stops short of explicit exclusions for other mutation siblings (merge_people, remove_person, set_tree_members), which would have made the routing complete.

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