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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: it discloses the dedup rule (text already present is skipped, which explains *why* the operation is idempotent) and an all-or-nothing failure guarantee ("fails without saving anything"). It does not mention permissions or concurrency 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 core action is front-loaded in the first line, followed by return behavior, failure semantics, and the sibling alternative — four short sentences with no filler. Every sentence carries distinct information.

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

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

With annotations, a complete input schema, and an output schema (so return structure needn't be spelled out), the description covers the remaining non-obvious aspects: dedup, atomic failure, and the create_entities route. It stops short of only minor details such as 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 description coverage is 100% and the single parameter is fully documented down to the nested contents/entityName level, so the baseline is 3. The description adds nothing about argument shape or formatting beyond what the schema already says.

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

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

The description opens with a specific verb+resource ("Add observations to existing entities") and explicitly scopes it to *existing* entities, immediately separating it from create_entities, which it names. An agent can distinguish this from create_entities, edit_observation, and delete_observations without opening any schema.

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

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

It states a precondition (all named entities must already exist, or the whole call fails) and routes the agent to create_entities when the target does not yet exist. That is clear context plus one named alternative, though it does not cover when to prefer edit_observation or how to correct an existing observation.

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

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

Annotations declare non-readOnly, non-destructive and idempotent, and the description adds genuinely new behavior: duplicate names (existing or repeated in-call) are not saved, are reported under "skipped", and their observations are left unsaved. That partial-failure/dedup semantics is real value beyond the annotations, though it still says nothing about auth needs or size limits.

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

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

Three short sentences, front-loaded with the operation and then the failure mode. 'Returns the entities created' is partially redundant since an output schema exists, which is the only wasted clause.

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 key non-obvious outcome (skipped duplicates). What remains thin is anything about ordering, limits, or permissions, but for a single-parameter create tool this is close to sufficient.

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

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

Schema description coverage is 100%, so name uniqueness, entityType and observation semantics are already documented in the schema. The description only restates that entities carry types and observations, adding no syntax or format detail, which matches the baseline 3.

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

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

States a specific verb (Create) and resource (entities) along with what each entity carries (a type and observations). It distinguishes itself from the sibling add_observations by naming it and describing the different job it 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?

Explicitly routes the agent to add_observations when the goal is adding facts to an existing entity, which is a clear alternative cue. It does not spell out a full when-not-to-use list beyond that single case, so it stops short of a 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely behavioral context beyond that: missing-entity relations are silently dropped and surfaced under 'skipped', and duplicates are neither created nor reported — a non-obvious edge case consistent with the idempotency hint.

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

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

Four short sentences, front-loaded with the action, then layered behavior. Each sentence carries distinct information (return value, failure mode, duplicate handling) and none is padding, though the explicit 'Returns the relations created' line is partly redundant with the output schema.

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

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

With an output schema present, the description needn't explain return structure, and it correctly focuses on the skipped/duplicate behaviors an agent can't infer. Only the create_entities prerequisite for entity existence is left implicit rather than spelled out.

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

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

Schema description coverage is 100% and the nested RelationInput documents from, to and relationType with examples ('uses', 'depends_on'). The description adds directional/type semantics but no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create directed, typed relations') and scopes it to 'existing entities', which implicitly distinguishes it from create_entities and create_entities-adjacent siblings. An agent can tell this tool's job apart from the other create_* tools without opening a schema.

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

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

The constraint that relations are only saved between existing entities implies that create_entities must run first, but this prerequisite is stated as a behavior rather than as guidance. There is no explicit when-to-use or when-not-to-use framing versus alternatives like create_entities or delete_relations.

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 destructive=true and idempotentHint=true, but the description adds real beyond-annotation context: deletions cascade to all touching relations, nonexistent names are silently ignored, and the deleted entities/relations are returned in full. The only redundancy is restating the return payload, which the output schema already covers.

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 destructive action and its cascade scope, then the routing hint. No filler and nothing buried.

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

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

For a destructive one-parameter tool with full annotations and an output schema, the description covers what matters: scope of destruction, no-op behavior for missing names, and the alternative tool. Nothing needed 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?

One required parameter (entityNames) with 100% schema description coverage, so the schema already documents it fully. The description adds no extra semantics such as case sensitivity, exact-match rules, or batch size limits, so the baseline 3 applies.

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

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

States a specific verb+resource ("Delete entities by name") plus the non-obvious cascade scope ("with every relation that touches them"). It also names a sibling, delete_observations, so an agent can distinguish it from the fact-level deletion tool without opening a schema.

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

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

Explicitly routes the agent elsewhere when the intent differs: "To remove single facts from an entity, see delete_observations." Combined with the cascade statement, the agent knows both when to use this tool and when not to.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it returns the deleted observations in full per entity plus a summary, omits entities that lost nothing, and ignores unknown entities/texts — the latter consistent with the idempotent hint.

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

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

Three short sentences, front-loaded with the core operation, then return behavior, then the sibling redirect. No filler and no repetition of the name/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?

Despite a simple one-parameter schema, the description covers matching semantics, partial-failure behavior, return shape, and the alternative tool. With an output schema present, return details are a bonus rather than a necessity, and nothing an agent needs is missing.

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

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

Schema description coverage is 100% and the property descriptions already explain entityName as 'name of the entity to change' and observations as 'exact texts'. The description's 'matched by exact text' reiterates rather than extends the schema, so the baseline 3 applies.

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

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

States a specific verb (delete), resource (observations), and matching mode (exact text), which immediately separates it from add_observations/edit_observation. It also names the sibling to use for a related-but-different task (delete_entities).

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

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

Gives a clear routing rule: use delete_entities to delete a whole entity rather than this tool. It also clarifies that non-existent entities/texts are silently ignored, which tells the agent this call will not fail on a partial match. No prerequisites or permission caveats 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real semantics beyond that by explaining that unmatched relations are ignored (concrete idempotency behavior) and that the full deleted relations are returned with a summary message. Permission requirements and any cascading effects are not mentioned.

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, each carrying distinct information: the match criteria first, then the return shape, then two behavioral caveats. No filler or restatement of 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 single-parameter deletion tool with an output schema and destructive/idempotent annotations, the description covers what is deleted, how matching works, behavior on misses, and the interaction with sibling delete_entities. An agent has everything needed 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 100% and each RelationInput field is documented in the schema, so the baseline is 3. The description's mention of 'source, target, and relation type' only mirrors the schema's from/to/relationType fields without adding format or constraint detail.

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

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

States a specific verb (Delete) plus resource (relations) and the matching keys (source, target, relation type), so the agent knows exactly what gets removed. It also explicitly distinguishes itself from delete_entities, which is the sibling most likely to be confused with it.

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

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

The description gives two useful routing conditions: nonexistent relations are silently ignored, and deleting an entity via delete_entities already removes its relations, implying the agent need not call this afterward. That is clear when-to-use context, though it stops short of an explicit 'use this instead of X when Y' statement.

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

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

Annotations declare a destructive, idempotent write, and the description goes well beyond them: it preserves original added_at/agent, records edited_at/edited_by, returns the edited observation, and enumerates three no-save failure conditions. This is exactly the behavioral context an agent needs before mutating data.

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

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

The core action and the alternative tool are front-loaded, and the atomic-failure clause is a genuinely useful single sentence. The unusual line-wrapping is cosmetic, though the failure sentence is slightly dense.

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

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

For a 3-parameter mutation with annotations and an output schema, nothing material is missing: the agent knows what is replaced, what is preserved, what is returned, how failure manifests, and where to go for a different operation.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic value: oldText must match the exact current text and the call fails without saving if it does not exist or the new text already exists. That ties parameter values directly to observable outcomes.

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

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

States a precise verb+resource+scope: 'Replace one observation's text in place.' It is clearly distinguishable from sibling add_observations, which it explicitly names, and from delete_observations by virtue of being an in-place edit.

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?

Routes the agent to add_observations for adding new facts and spells out the failure conditions (entity missing, old text missing, new text already present). It does not discuss alternatives like delete_observations plus add_observations for multi-fact changes, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already establish the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description goes beyond them by disclosing the side-effect target (memory.local.taxonomy.jsonc beside the memory file), the file's contents (versioned schema, usage counts, comments), and the return values, which is real added context for a write operation.

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

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

The core action and output file are front-loaded in the first sentence, and the following sentences add necessary detail about contents and return values. Slightly verbose with the multi-line breakdown of file contents, but every element is informative.

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 carrying the safety profile, the description is more than complete: it explains the file location, what the file contains, and even summarizes the return values. Nothing an agent needs to invoke this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the tool operates implicitly on 'this repo' with no required input.

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: 'Write this repo's memory taxonomy to a JSONC file.' It names the exact artifact produced and where it lives, and no sibling tool does anything comparable, so an agent can identify it instantly.

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 ('a JSONC file the user can read') – the description never states when to prefer this over siblings like read_graph or search_nodes, nor any trigger condition. It is adequate because the purpose makes the context fairly obvious, but no explicit guidance is given.

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

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

Annotations declare destructive=true, idempotent=true, readOnly=false, and the description goes well beyond them by disclosing exactly what happens: 'fresh' renames the old file to a timestamped backup and starts an empty graph, 'adopt' rewrites the header while keeping memories, and the tool changes nothing when ownership already matches. It also previews the return payload (status, header, backup path).

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

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

Front-loads the core purpose in the first sentence and then layers the error-resolution context and mode semantics. Slightly wordy in the second paragraph but every clause carries operative 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?

Covers purpose, trigger, mode selection, destructive side effects, backup behavior, and return shape. With an output schema present and annotations set, nothing an agent needs to invoke this 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 100% and the enum is already documented, so the baseline is 3. The description adds scenario framing beyond the schema by explaining when each mode applies (file copied from another repo vs. repo moved/renamed), which helps an agent pick the right value.

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 concrete verb and resource ('Claim the memory file for this repo, or start a new one') and is unmistakably distinct from the entity/relation CRUD siblings. An agent can identify it as the header-ownership/repair tool 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?

Names the precise trigger condition ('the error other tools return when the memory file's header names a different repo') and gives the selection rule for each mode: 'fresh' for a file copied from another repo, 'adopt' for a repo that was moved or renamed. It also states the no-op case when the file already belongs to this repo.

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, idempotentHint=true, and readOnlyHint=false, but the description goes well beyond them: observations move with original tags, duplicate texts keep the target's copy, relations are repointed with duplicate and self-relations dropped, and the operation aborts without saving when either entity is absent.

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 destructive action is front-loaded in sentence one, and the following sentences each carry distinct behavioral facts. It is dense but every clause earns its place; a slightly tighter phrasing of the dedup rules could cut a few 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 destructive two-parameter merge, the description covers the edge cases an agent needs (missing entities, duplicate text, duplicate/self relations, target identity preservation), and since an output schema exists it does not need to detail return 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 coverage is 100%, so the baseline is 3, and the description adds real semantic meaning on top: the source is the one deleted and its data migrated, while the target retains its own name and type. That clarifies the role distinction beyond the schema's terse parameter blurbs.

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

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

The first sentence states a specific verb and resource with unambiguous direction: 'Fold one entity into another and delete the first.' This is clearly distinct in behavior from siblings like rename_entity or delete_entities, though the description never names those siblings to route the agent explicitly.

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

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

Usage is implied rather than stated – the schema notes the source is 'such as a typo,' which hints at the dedup use case, and the description explains failure when an entity is missing. But there is no explicit when-to-use guidance or comparison against rename_entity, delete_entities, or edit_observation.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context the annotations cannot: results include every relation touching the entities, a relation's far end may fall outside the result set, and nonexistent names are silently ignored rather than erroring. That last point is the most valuable 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?

Three short sentences, purpose front-loaded, with the alternative-tool pointer and the relation-expansion caveat each earning their place. No filler.

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

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

For a one-parameter read tool with an output schema, the definition covers what it does, what comes back (including relations that reach outside the result), how missing names behave, and which sibling to use instead. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the single 'names' parameter is already documented, giving a baseline of 3. The description still adds meaning by stressing 'exact name' matching and the ignore-missing-names semantics, which the schema's 'Exact names of the entities to open' only hints at.

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 ('Open entities') and pins the matching mode to 'exact name', which immediately separates it from keyword-oriented siblings. An agent can tell it apart from search_nodes without opening either schema.

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

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

Explicitly routes the agent to the alternative: 'To find entities by keyword, see search_nodes,' giving the condition (exact vs keyword) that selects between them. No prerequisites or exclusions are left to inference beyond that.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further and discloses non-obvious filter semantics: matching is tag-based, an entity is included when it or any observation matches (returning only matching observations), and any filter drops untagged entries. It also warns the graph 'grows with the repo's memory'.

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

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

Front-loads the core action ('Read every entity and relation, or only those in a date range') before the filtering detail. It is information-dense but every sentence carries meaning; the tag-matching sentence is slightly convoluted but not wasteful.

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. The description covers purpose, filter semantics, and alternatives, leaving nothing an agent needs in order 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 100%, so the schema already documents agent, since, and before, making the baseline 3. The description adds some meaning beyond the schema by explaining that these filters operate on tags and that observations are filtered along with entities, which the per-parameter descriptions do not convey.

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

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

States a specific verb (Read) and resource (entity and relation graph) with clear scope: the whole graph or a filtered subset. It explicitly contrasts itself with search_nodes and open_nodes, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit when-to-use: read everything, or narrow by date/agent filters. It also names the alternatives ('To read part of the graph by topic, see search_nodes and open_nodes'), routing the agent to the right tool for topic-scoped reads.

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 flag destructiveHint and idempotent; the description adds what annotations cannot: the rename cascades across every relation, tags are preserved to keep provenance metadata, failure is atomic ('fails without saving'), and the response summarizes relations updated. That is rich consequence disclosure beyond the structured hints.

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 cascade behavior and provenance preservation lead; failure semantics and the sibling pointer close. Every sentence carries information and nothing is padded.

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

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

For a mutation tool with an output schema and full annotation coverage, the agent has cascade scope, failure behavior, data preservation, and an alternative tool pointer. Nothing needed 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 100% and both parameters are self-documented ('current name', 'no other entity may have it'), so the description adds no syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (rename), the resource (entity), and an important scope detail: every relation naming it is also renamed. It also distinguishes itself from merge_entities by name, so an agent can separate the two without opening schemas.

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

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

Gives concrete failure conditions (entity missing, name already taken) and routes the combine case to merge_entities. It stops short of a full when-to-use narrative against create/edit paths, but the alternative is named explicitly.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely non-obvious behavior: word-splitting of the query, quoted-phrase handling, case-insensitive matching, ordering by number of matched terms, and the fact that returned relations may have their other endpoint outside the result set. That last point is the kind of surprise an agent needs warned about.

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

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

Purpose is front-loaded in the first sentence, followed by mechanics and routing. Every sentence carries information, though the result-ordering paragraph is dense enough that it could be tightened slightly without loss.

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 covering the return shape and annotations covering the safety profile, the description supplies the remaining behavioral contract: matching rules, ranking, relation inclusion, blank-query behavior, and the sibling to use for exact-name lookup. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (query, since, before, agent) is already documented in the schema, including the quoted-phrase syntax and the date formats. The description restates the query syntax and the filter intent but adds no format or default details beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus the three fields searched (name, type, observation text), which pins down the semantics precisely. It also explicitly differentiates itself from open_nodes ('To fetch entities by exact name, see open_nodes') and references read_graph for the filter semantics, so an agent can route correctly without opening a schema.

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

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

Names the alternative (open_nodes) with the condition that selects it, explains the filter parameters' scope ('narrow the search to matching entries, as in read_graph'), and states the degenerate case ('A blank query returns every entity'). When-to-use, when-not-to-use, and alternatives are all covered.

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