recordari

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

Annotations already mark the tool readOnly and non-destructive, and the description adds substantial behavioral context beyond that: lean result shape, compact text-line rendering vs full object, suppression of conflict pairs, memory_id being silently ignored in other modes, and which filters apply to which modes. This gives the agent a realistic model of how the tool behaves at call time.

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

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

The description is long but information-dense, with the core purpose front-loaded and each mode and filter earning its place. Some parenthetical asides, such as the shadow-rows explanation, add necessary context. It is structured effectively, though it could be tightened without losing key details.

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 seven optional parameters, no output schema, and multiple modes, the description covers most of what an agent needs: mode semantics, filter behavior, output format variations, suppression behavior, and cross-tool safety guidance. Minor gaps remain, such as domain/limit semantics and definitive mode enum values, but overall it is nearly complete for a tool of this complexity.

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

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

Schema description coverage is only 14%, so the description carries most of the burden, and it largely succeeds: tags, node_kind, state, and memory_id all receive semantic explanations. However, domain and limit are named but not given semantics such as allowed domain values or default/maximum limits, so compensation is strong but not complete.

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

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

The description opens with a specific verb and resource: 'Inspect the health of the knowledge graph,' then enumerates four distinct modes (stale, orphans, archived, conflicts) that make the tool's scope concrete. This clearly separates audit from sibling retrieval tools like recall and search, even without naming them.

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

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

Each mode is tied to a specific use case, e.g., stale surfaces drift candidates, orphans returns memories with no connections, and conflicts surfaces semantically close pairs. It also gives an explicit safety rule for archived mode ('only call forget(restore=true) ... after explicit unambiguous user confirmation') and points to recall(id) for full content. However, it does not explicitly say when to prefer a sibling tool over audit, so it stops short of full 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?

The description reveals important behaviors beyond the sparse annotations: relationship=resolved is pure-additive and does not remove existing contradicts connections, wrong-pair resolutions fail silently, override requires Editor/Owner role, and resolved pairs stop appearing in audit and significance. This is exactly the kind of behavioral context annotations do not provide.

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

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

The description is dense and long, but nearly every sentence carries essential caveats or constraints. It front-loads the core purpose and relationship list before diving into edge cases, though the run-on style and heavy use of quotes make it harder to scan quickly.

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

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

Given the tool's complexity, lack of output schema, and conditional authorization requirements, the description covers the critical ground: single vs batch, return shape, rejection reporting, cross-owner overrides, and integration with audit and significance. An agent has enough to call this tool correctly in most scenarios.

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 zero schema description coverage, the description compensates by explaining relationship values/default, verdict options, override_reason/override_confirm conditions, and batch structure. However, narrative is only mentioned in the batch shape without any semantic explanation, and from_memory/to_memory are described indirectly as ids rather than explicitly defined.

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

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

The description opens with a specific verb and resource: 'Create one or more typed connections between memories.' It enumerates the supported relationship types, including a default, so an agent knows exactly what the tool does and can distinguish it from sibling tools like disconnect.

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

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

It gives explicit when-to-use guidance, including verifying ids with why_connected before resolving audit suggestions, using the single form when override is needed, and avoiding batch connect for resolved cross-owner conflicts. It also clarifies the intended scope of 'works on any pair,' preventing misuse.

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=true annotation already signals mutation, and 'Remove' is consistent with it. The description adds genuinely useful behavior: it explains single versus batch processing and the per-item success/error result envelope, which are not derivable from annotations alone.

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

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

Two short sentences carry the entire necessary payload: action, scope, parameter syntax, and return shape. There is no wasted wording, and the primary action is front-loaded.

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

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

For a low-complexity destructive tool with no output schema, the description covers input, output, and semantics efficiently. It stops short of advising when to choose single versus batch mode, but the semantics are simple enough that this is a minor gap.

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

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

With 0% schema description coverage, the description fully compensates by documenting both parameters explicitly: 'id' for single removal and 'ids' for batch removal. It also gives concrete payload shapes and the result format, so an agent understands how to invoke the tool correctly.

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 a precise verb ('Remove') and resource ('connections') and immediately clarifies both invocation modes. It is clearly scoped relative to siblings like 'connect' (the opposite action) and 'remember'/'forget' (which manage memories rather than connections).

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, and it does not mention alternative tools. Usage context must be inferred entirely from the tool name and sibling list, so an agent gets no direct routing help.

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 provides rich behavioral detail, including memory movement on rename, automatic alias registration, and the rejection of aliases with live memories. However, it directly contradicts the annotations: destructiveHint=false while action=unalias explicitly deletes a registered alias and rename mutates domain state in place. This makes the safety signal unreliable and earns a score of 1 under the contradiction rule.

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

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

The description is long but densely structured, with no filler. Each sentence adds a distinct behavior, precondition, or synonym, and the default/list behavior is front-loaded before the action-specific cases. This is efficient for a six-parameter multi-action tool.

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

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

For a complex multi-action tool with no output schema, the description covers the default return shape, the resolve return shape, preconditions, and the merge_domains alternative. The main gaps are that return values for alias, unalias, and rename are not specified, and no auth/permission context is given, but these are minor given the overall detail.

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 carries the full burden for all six parameters. It maps every parameter to a concrete action and condition: {alias,domain} for alias registration, {alias} for unalias, {name} for resolve, {old_domain,new_domain} for rename, and action values/synonyms are listed explicitly. This fully compensates for the empty schema.

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

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

The description opens with a clear verb+resource pair, 'Domain administration and discovery,' and then details every action (list, alias, unalias, resolve, rename) with its specific effect and required parameters. The default behavior is explicitly defined, so an agent can distinguish this tool from the memory- and search-focused siblings.

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

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

The description states exactly when to omit action (default list), enumerates action choices and synonyms, and gives a concrete exclusion: if the new_domain already has memories, use merge_domains instead. It also tells the agent to move or archive live memories before registering an alias, making the routing guidance explicit.

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

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

Despite destructiveHint=true already signaling danger, the description adds crucial behavioral detail: archive is soft-delete, purge is hard delete, connected memories return structured warnings rather than errors, force can override the guard but is forbidden for workspace keys. It also discloses the JSON error format and retry guidance, which annotations alone would never convey.

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

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

The description is long but the complexity justifies it. Information is grouped by mode (ARCHIVE, RESTORE, PURGE), with examples inline and error handling at the end. A few patterns repeat, but each sentence adds operational value.

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 multi-mode tool with no output schema and minimal annotations, the description is remarkably complete. It covers preconditions, confirmation gates, permission restrictions, edge cases like live inbound connections, response shapes, and error handling. An agent has everything needed to call any variant correctly.

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

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

Schema description coverage is 0%, so the description carries full parameter semantics. It explains the role of id, reason, items, restore, purge, and force, maps them to each mode, and gives concrete request shapes for single and batch calls. This far exceeds what the bare schema provides.

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

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

The description names the tool's exact operations: archive (soft-delete), un-archive, and permanently purge memories. It clearly distinguishes three modes with distinct intents and parameter shapes, so an agent knows precisely what resource and action are being invoked.

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 strong operational guidance: explicit confirmation is required for archive/restore, batch use is recommended for multiple items, restore IDs must come from audit(mode=archived), purge only works on archived memories, and force is restricted to org_admin or platform keys. It also explains when to switch between single and batch calls, and how to handle failures via error_class.

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 read-only and non-destructive, and the description adds substantial operational detail: precedence of memory_id over domain, depth default, effective-date filtering, whole-word tags matching, node_kind union semantics, lean result shape, and multi-result line rendering. This goes well beyond structured annotations.

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

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

The description is dense but every sentence adds operational information, with the core behavior front-loaded. While a bulleted structure could improve scannability, there is no filler or repetition.

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

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

Given eight optional parameters, no output schema, and no required fields, the description explains result formatting, single vs multi-result rendering, effective dates, and filter interactions. There is no obvious gap an agent would need to make a correct invocation.

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

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

Schema coverage is only 13% with just node_kind described, so the description carries the weight for all eight parameters. It explains from/to date filtering, tags whole-word matching, important_only semantics, depth, memory_id precedence over domain, and node_kind union behavior—fully compensating for the sparse schema.

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

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

States a specific verb ('Return') plus resource ('memories') and specifies chronological ordering. It also distinguishes itself from siblings by describing scope and explicitly routing importance analysis to significance and full content to recall.

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

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

Explicitly tells the agent to use recall(id) for full content and significance for importance analysis beyond the timeline. It also clarifies when memory_id is useful for understanding a specific workstream's evolution, giving clear selection context.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It goes beyond annotations with rich behavioral detail: conflicts_count is a density signal, not a monotonically-decreasing queue; suppression mechanics; owned_* fields are zero for plain workspace-key sessions; lean results render as single-line digest strings at 2+ entries; overlap between sections is intentional; server_version staleness handling. This is exactly the kind of non-obvious behavior an agent needs.

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

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

The description is dense and information-rich, and it front-loads the core purpose well. However, it is very long and covers a lot of output-section detail that is arguably output-schema territory; an agent must parse several hundred words before reaching the action items. Every sentence does earn its place functionally, but the lack of structural formatting (headers, bullets, separation of summary vs edge cases) makes it harder to scan.

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

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

For a read-only orientation tool with no output schema, the description fully compensates: it explains return sections, their counts, when they appear, how to handle truncation (rules_count > len(rules) → search), how to get full content (recall), rendering format, scope-dependent fields, and server_version handling. There is no output schema, so this level of descriptive detail is necessary, and it is complete.

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

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

Schema description coverage is 67%, and for the documented parameters (scope, topic) the schema already provides solid semantics. The description compensates for the undocumented domain parameter with extensive details about passing a domain vs omitting it, and it adds critical behavioral semantics for scope (which fields are computed per scope) and topic (replaces significant with relevant). A slight deduction because the domain parameter itself has no schema description, but the description more than covers its meaning.

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: "Get a bounded orientation snapshot." It then enumerates the exact sections returned (rules, declared_spine, significant/relevant, recent, digest) and how they differ, which clearly distinguishes this tool from siblings like search, recall, and audit. The purpose is unambiguous and grounded in named outputs.

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 when-to-use guidance: omit domain at session start for a cross-domain bootstrap; pass topic for a purpose-driven session; call audit(mode=stale) if stale_count > 0; call audit(mode=conflicts) for full contradiction pairs; use search instead of orient for finding specific memories; and call tools/list again if server_version changed. It also tells the agent when not to call orient again because sections are bounded. This is exemplary 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds significant behavioral detail beyond annotations: on failure, content[0].text is a JSON error envelope with a specific error_class discriminator and a suggested recovery action per error type.

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

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

Three sentences with the primary action front-loaded and error-handling instructions compactly integrated. No filler, redundancy, or repetition of annotation information.

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

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

For a single-parameter read tool with no output schema, the description covers the failure response format and recovery steps well. The successful return structure is only summarized as 'memory along with its connections', which is sufficient for high-level invocation but leaves parsing details implicit.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'id' refers to the memory ID, which adds some meaning, but it does not describe ID format, validity, or optionality. Compensation is partial for a single-parameter tool.

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

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

Description uses a specific verb ('Retrieve'), a resource ('a memory by ID'), and an additional output ('along with its connections'). This clearly distinguishes it from siblings like remember, forget, and search, which create, delete, or query memories differently.

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 clear usage context: call when you have a memory ID and need that memory plus its connections. It also gives explicit guidance on failure handling—retry on retryable errors and prompt the user to verify the ID on not_found—though it does not name alternative tools or exclusion cases.

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 goes well beyond the readOnlyHint/destructiveHint annotations, disclosing union matching, intersection behavior, updated_at ordering, lean result format, and compact text-line rendering rules. These behavioral details materially change how an agent should interpret results and are not available elsewhere.

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 mostly front-loaded with the core behavior. It contains several necessary output-format details, though the phrase 'the existing behaviour is unchanged' is vague and the rendering rules could have been tightened. No sentence is purely filler.

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

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

With no output schema, the description appropriately explains the return format and directs the agent to recall for full content. It is complete enough for the main use case, but unexplained limit and domain parameters leave moderate ambiguity in a six-parameter tool.

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

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

Schema description coverage is only 17%, so the description must compensate. It does explain tags, node_kind, memory_id, and group_by_domain semantics thoroughly, but it leaves limit and domain without explicit meaning. This is a real gap, but the description still adds substantial value for most parameters.

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

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

The description opens with a specific verb and resource: 'Return recently modified memories', and adds an optional grouping dimension. It clearly differentiates itself from recall by stating 'call recall(id) for full content', so an agent can distinguish listing recent memories from retrieving a full memory.

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

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

The description gives clear conditional guidance for tags, node_kind, memory_id, and their interaction, and explicitly routes to recall for full content. It does not explicitly contrast with search or history, but the tool's purpose and alternatives are clear enough for correct selection.

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

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

The description discloses many non-obvious behaviors beyond the sparse annotations: suggested_connections reflect aboutness not agreement, possible_contradicts are flagged as candidates rather than confirmed conflicts, and failures return a structured error_class with explicit handling rules ('retry on retryable, surface message on validation, treat conflict as duplicate'). These details substantially exceed what annotations provide.

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

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

The description is long but logically ordered: purpose, pre-filing search, invocation shapes, post-filing review, contradiction handling, connect mandate, and error handling. Each sentence adds a distinct piece of guidance with minimal redundancy, though the continuous prose format could be more scannable with paragraph breaks or bullet lists.

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

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

For a complex write tool without an output schema, the description thoroughly covers return values ({memory, suggested_connections}, {memories:[...]}), the error JSON structure, domain inference, and the mandatory connect step. It does not explicitly explain every parameter, but many are self-explanatory or covered by the schema, making the description complete enough for correct invocation in most cases.

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

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

With schema coverage at only 27%, the description compensates partially by clarifying the two invocation shapes ('Single: pass fields directly' and 'Batch: pass {items:[{label,domain,...},...]}') and their return formats. However, several parameters (tags, transient, why_matters, related_to) are not explained beyond the sparse schema, leaving their meanings to inference. The compensation is partial, not complete.

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 'Store one or more new memories (concepts, decisions, findings)', naming a specific verb (store), resource (memories), and scope (new). It clearly differentiates from siblings such as recall (read), revise (update), forget (delete), and search (query) by focusing on creation, and it distinguishes the singular and batch invocation forms.

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 explicit workflow guidance: 'Before filing, search for related content first — use the search results to infer the domain' and 'Prefer existing domains over creating new ones'. It also mandates post-action behavior with 'ALWAYS call connect for any suggested_connections you accept before ending your session', naming complementary tools (search, connect) and making the conditions for use clear.

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

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

The description discloses far more than the annotations provide: ownership rejection with error_class=forbidden, override requirements, in-place vs. supersede semantics, claim ownership race behavior, domain-move validation, batch all-or-nothing rejection, and exact return shapes. It also reveals the post-success review convention for connections and possible_contradicts, which is behavior an agent could not infer from annotations.

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

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

The description is extremely long, but nearly every sentence encodes a distinct behavioral rule, and the most urgent warning (bulk migration) is front-loaded. It loses a point for dense, wall-of-text structure that would be more scannable with bullets or clearer separation between the single, batch, override, supersede, claim, and domain cases.

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

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

Given no output schema and a high-complexity mutation tool, the description is exceptionally complete. It specifies both single and batch return envelopes, error handling via content[0].text JSON with error_class switching guidance, ownership/override paths, and the review obligation after success. An agent has enough information to invoke the tool correctly across all documented scenarios.

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 only 13% schema description coverage, the description carries nearly the full semantic burden and succeeds. It explains the meaning and constraints of override_reason, override_confirm, supersede, claim, domain, domain_move_reason, and items, and clarifies that omitted fields are unchanged. This adds substantial meaning beyond the bare schema.

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

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

The description states a precise action ('Update one or more existing memories') and explicitly distinguishes revise from bulk migration via merge_domains and from remember() by scoping it to existing memories. It also clarifies the single vs. batch forms immediately, leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: individual corrections only, never to emulate bulk merge by looping revise calls. It also provides conditional alternatives for override vs. supersede, claim vs. override, and single vs. batch, including when batch revise cannot be used.

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?

Even with readOnlyHint=true and destructiveHint=false annotations, the description adds substantial behavioral detail: exact=true returns full objects regardless of count, multi-result lists render as compact text lines, state is a post-filter, FTS tokenisation drops hyphens, and failures return a structured error_class JSON. These details go well beyond the safety profile captured by annotations.

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

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

The description is dense but every clause earns its place, covering query semantics, listing behavior, exact-match nuance, result rendering, fallback guidance, state filtering, and error handling. It is front-loaded with the core purpose and then layers edge cases in a logical order. It is arguably long, but for a tool with eight parameters and no output schema, the length is justified.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: lean result fields, compact text-line rendering versus full objects, exact=true exemption, and error JSON with retry semantics. It also covers failure fallbacks and sibling routing, leaving an agent well-equipped to invoke the tool correctly and interpret its results.

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 75%, and the description adds meaning beyond the schema for key parameters: query must echo stored vocabulary, node_kind excludes unrelated matching kinds, exact=true bypasses FTS hyphen issues, and state values are enumerated. The main gap is that the domain parameter is never directly explained in the description, and max_distance is left entirely to the schema, so the description doesn't fully carry the parameter-semantics burden.

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 'Search memories by keyword,' giving a clear verb and resource, and is further sharpened by the title 'Search memories.' It distinguishes itself from siblings by explicitly routing full-content retrieval to recall(id) and browsing to orient, so an agent can tell this tool apart even though the tool name is the generic '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?

The description gives explicit guidance on when to use keyword vocabulary, when to set exact=true for identifiers, and how to use node_kind for listing. It also provides a fallback escalation path—'use orient (with domain) to browse all memories, then recall by ID, then follow connections'—and names the alternatives directly. This is exceptional contextual routing beyond what schemas or annotations provide.

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 read-only and non-destructive, and the description adds substantial behavioral context beyond that: truncation semantics with *_results_truncated flags, the exact structural ranking formula, recency_window zero-weight behavior, memory_id precedence, trust-mode scoring, and lean-result rendering rules. No statement contradicts the annotations.

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

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

Although long, the description is densely informative and well-structured with bullet sections, bolded section names, and clear mode/usage/format subsections. Every sentence contributes operational meaning, and the most decision-relevant facts (alternative tools, truncation, and scope precedence) are stated directly rather than 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?

Given the tool's complexity — two modes, four result sections, truncation flags, filtering, output formatting, and no output schema — the description covers all necessary invocation and interpretation details. It even explains the actionable gap between uncurated and potentially_stale and tells the agent to call recall(id) for full content, leaving no critical gap.

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

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

Schema description coverage is only 14%, so the description carries the parameter burden, and it does so thoroughly for limit, mode, memory_id, domain, node_kind, and recency_window. It explains default limit, the trust-mode switch, scoping precedence, filtering behavior, and how recency_window affects weighting. The tags parameter is not explained in the description, which prevents a perfect score, but the overall compensation is strong.

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 'Dual-signal importance analysis' and immediately enumerates the four result sections, tying the tool to a specific analytic resource. It explicitly differentiates from siblings by naming history and audit as the correct tools for chronological listing and age-based staleness, so the agent can tell significance apart without opening other definitions.

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 guidance is explicit and actionable: 'Do not use this tool to list all memories chronologically — use history for that' and 'For age-based staleness, use audit(mode=stale)'. It also clarifies when to pass memory_id vs domain, how to paginate with limit, and that memory_id takes precedence when both are supplied.

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 read-only and non-destructive behavior, and the description reinforces this while adding important nuance: semantic similarity reflects aboutness, not agreement, and the server never asserts conflicts. This helps prevent misinterpretation of returned candidates.

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

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

The description is dense but well-structured, front-loading the core behavior and then adding interpretative guidance. A small amount of redundancy exists in restating read-only behavior already covered by annotations, but every sentence adds value.

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 tool with no output schema, the description adequately covers input semantics, ranking behavior, and result contents (domain and semantic_distance). It does not specify the ordering direction of semantic_distance, which is a minor gap, but overall an agent has enough to invoke and interpret results.

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 0% schema description coverage, the description compensates by explaining that 'id' is a memory ID and 'limit' controls the maximum number of candidates (default 5). It could specify constraints or types more precisely, but the core meaning of both parameters is clear.

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

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

The description clearly states the tool returns semantically similar candidates for a given memory ID, ranked by semantic_distance, and explicitly contrasts with connection creation via 'Read-only — never creates connections.' This distinguishes it from sibling tools like 'connect' and 'why_connected.'

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

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

The description gives clear usage context: use it to surface candidates for review of agreement or contradiction, not just for connect opportunities. It does not explicitly name alternative tools or when not to use them, but the context is strong enough for an agent to decide appropriately.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, and the description adds meaningful behavioral context beyond that: truncation can occur for large domains, properties must not be inferred from truncated results, and ordered output is 'most-connected memories first.' It also fully discloses the JSON return fields, including truncated counts, which helps the agent understand and safely interpret results.

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

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

Every sentence earns its place: purpose and exclusions, parameter behavior, return shape, rendering guidance, and truncation caveat. The description is longer than usual but densely packed with necessary information and well-ordered from high-level purpose to concrete invocation details.

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

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

There is no output schema, yet the description enumerates the full JSON response shape (mermaid, node_count, edge_count, nodes_shown, nodes_total, edges_shown, edges_total, truncated, memories, connections). It also covers invocation modes, limits, truncation semantics, and client-specific rendering instructions. Nothing an agent needs to correctly select and invoke this tool is missing.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It clearly explains all three parameters: memory_id views a single memory and its direct connections, domain views the full domain graph, and limit is capped at 100 with a default of 40. This adds substantive meaning beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Generate a Mermaid.js flowchart for human visual inspection only.' It also explicitly distinguishes itself from audit(mode=orphans), making it clear this tool is for visualization rather than orphan detection or programmatic analysis. The title 'Visualise domain graph' reinforces the purpose without creating ambiguity.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including a direct alternative: 'NOT for orphan detection or programmatic analysis — use audit(mode=orphans) to find isolated memories.' It also explains when to pass memory_id vs domain, the limit default and cap, and how to render output depending on client support for HTML widgets. This is unusually actionable usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: id resolution errors when no live memory matches, label resolution falls back to fuzzy substring matching against the most recently created candidate, and there is no silent fallback from id to label. No contradiction with annotations.

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

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

Every sentence adds distinct value: core purpose, exact-id guidance with error behavior, recommended use case, label fallback semantics, and independent resolution. The description is front-loaded with the action and uses clear contrasts without redundancy.

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

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

For a read-only tool with no output schema, the description covers the main resolution modes and error behavior well. The missing explanation of the domain parameter is the main gap, and the description does not state what happens if neither ids nor labels are supplied. Otherwise, an agent has enough to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden. It thoroughly explains from_id, to_id, from_label, and to_label, including resolution modes and combinability. The domain parameter, however, is never mentioned, leaving a five-parameter tool with one parameter unexplained.

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

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

Description opens with a specific verb and resource: 'Find direct connections between two memories, in either direction.' It clearly distinguishes this tool from siblings like connect, recall, and suggest_connections by framing it as a verification/query tool for exact pairs, even naming connect as a follow-up use case.

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 specifies when to use from_id/to_id versus from_label/to_label, explains the exact-match versus fuzzy-match behavior, and gives a concrete recommended scenario: 'before connect(relationship=resolved)'. It also states that sides resolve independently, so mixed id/label combinations are allowed.

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