Ontonym

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

The description richly discloses behavior beyond annotations: idempotency semantics, force behavior, default kinds, write scope requirement, the fact that the call returns quickly but unfinished, the ~25s CPU-bound budget, remaining counts, and background worker draining. This goes far beyond the idempotentHint and destructiveHint 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 longer than typical but every section earns its place: purpose, failure-mode explanation, idempotency, defaults, permissions, async behavior, and retry guidance. It is front-loaded with the core action and structured so the operational warnings are easy to absorb.

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

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

The definition provides everything an agent needs to both select and invoke the tool correctly: when to use, why missing embeddings cause empty results, parameter defaults, scoping requirements, asynchronous behavior, and what results mean. The output schema exists but the description even mentions the key output fields, making it fully self-contained.

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 for parameters. It explains force (skip already-embedded unless set), kinds (defaults to ['object','class']), and memory implicitly as the target memory's index. Only the 'memory' parameter's format is not explicit, but the context is sufficient.

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

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

The description states a specific verb and resource: "Build (or top up) the vector index a memory's semantic_search reads." It clearly distinguishes itself from the sibling semantic_search by positioning this tool as the index builder that search depends on, so an agent can tell them apart immediately.

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

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

It explicitly states when to run: "Run this once per memory, and again after a large ingestion." It also clarifies when repeated calls are unnecessary and that calling again immediately is safe, and that looping to zero is not required. This is actionable usage guidance beyond vague 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 already declare destructiveHint=true and non-idempotence, but the description goes further: it enumerates exactly what is destroyed (properties, relationship/action occurrences, mentions, ownership rows), states there is no undo or tombstone, notes it refuses graph plumbing and the _system.* namespace, and discloses the write-access requirement and audit-log behavior of `reason`.

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

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

Front-loaded with the destructive action and the IRREVERSIBLE warning, then proceeds through consequences, usage, exclusions, and parameter notes. Dense rather than padded, though the multi-paragraph layout is longer than strictly necessary for a three-parameter tool.

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

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

An output schema exists, so return values need no explanation. The description covers preconditions, destructive side effects, refusals, and audit behavior — everything an agent needs to invoke this safely.

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 must compensate. It explains `reason` (optional, written to the audit log) and hints at `object_id` via the get_object precondition, but says nothing about `memory`, leaving one of three parameters undocumented in both schema and prose.

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 ('one object'), and cascade scope ('everything hanging off it'), plus the irreversibility. It explicitly contrasts itself with merge_objects, so an agent can distinguish it from siblings 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 when-to-use ('a wrong fact, a test row, something a person asked to have removed') and when-not-to-use (duplicates → merge_objects, with the reason merge is better). It also prescribes prerequisites: confirm with the user, run get_object first, prefer get_change_impact when dependents may exist.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that this is 'one composite call' aggregating several analysis categories, which hints at cost/behaviour but does not discuss latency, aggregation limits, or empty-result behaviour.

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

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

Two sentences with minimal waste, and the use-case framing is front-loaded before the enumeration of contents. Slightly gimmicky quote framing, but nothing that could be dropped without losing the routing cue.

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

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

An output schema exists and annotations are rich, so return-shape and safety details need not be restated. The description covers purpose, contents, and a param hint; the only real gap is the unexplained object_id, which is minor given the overall coverage.

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% with two required parameters, so the description carries the burden. It clarifies that 'memory' is a slug, which is genuinely useful beyond the bare schema, but 'object_id' is left completely undefined (no hint that it is an integer object identifier from this memory's graph).

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

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

The description states a specific verb (get) and a specific composite resource (change impact), and enumerates what the blast radius contains: event-class neighbours, actions touching it, property conflicts, top related objects, and provenance. This makes it distinguishable from plain lookups like get_object or get_graph, though it never names those siblings directly.

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

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

The framing question ('What should I watch out for if I change this object?') implicitly tells the agent this is a pre-mutation impact check rather than a general read. There is no explicit when-not guidance and no named alternative for simpler lookups, so usage is implied rather than specified.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding non-obvious behavior: the document is NOT sent to the server, no object list is embedded in the prompts, and resolve_names is the mechanism for discovering existing entities. It stops short of permissions/error behavior, but meaningfully exceeds annotation coverage.

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

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

Purpose and step marker are front-loaded, and the numbered flow is efficient for a multi-tool workflow. It is dense but nearly every sentence carries distinct information; the mixed use of prose and STEP parens is slightly repetitive 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?

For a workflow-initiating tool with a rich output schema (so returns needn't be re-explained), the description still sketches the return ('a passes list' with classes/objects passes) and lays out all four steps and the handoff to sibling tools. Nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 0% and the schema only labels the field 'Memory', so the description must compensate. It does: '`memory` is the slug from list_my_memories' tells the agent both the format and where to obtain the value, which is the key unknown for this single parameter.

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

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

States a specific verb and resource ('Add a document to the knowledge graph by extracting it YOURSELF') and explicitly frames itself as STEP 1 of 4, which distinguishes it from the sibling submit_extraction_from_llm that performs the later step. An agent can tell what it produces (prompts) and what it does not do (send the document).

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

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

'Use whenever the user shares a document/notes/transcript and wants it captured in the graph, and you (this assistant) should do the extraction' gives a clear trigger condition. The full 4-step flow names the alternatives (resolve_names, submit_extraction_from_llm) and their ordering, but no explicit when-not-to-use or alternate path 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 already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real behavioral context beyond them: cross-memory ids 404 instead of resolving, ids are not portable, and only APPROVED owners are returned. It does not cover pagination or result-size limits, so not a 5.

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

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

Three tight paragraphs, each load-bearing: what is returned first, then parameter provenance plus the 404 rule, then alternative routing. No filler sentences.

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, yet the description still previews the returned shape, and it closes the remaining gaps for an agent: parameter provenance, a failure mode, and sibling routing. 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 coverage is 0%, so the description must compensate and largely does: 'memory' is sourced from list_my_memories, 'object_id' from semantic_search/list_objects/recall, plus the non-portability rule for ids. It omits type constraints (integer vs string) that the schema carries, hence 4 rather than 5.

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 with enumerated scope: properties, incoming AND outgoing relationships grouped by type, touching actions, and APPROVED owners. This is distinguishable from siblings like get_paths and semantic_search 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?

Explicit routing section: 'Reach for something else when' names three alternatives (semantic_search expand=1 for multi-hit first ring, get_paths for connectivity, get_change_impact for blast radius) with the condition that selects each. Nothing is left to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description goes well beyond them by disclosing that all returned paths are of minimal length, that found:false with frontier_truncated:true means a breadth cap was hit rather than proven disconnection, and the exact step shape {from, rel, direction, to}. That failure-mode disclosure is the kind of context annotations cannot carry.

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 purpose and the connectivity framing are front-loaded, followed by parameter semantics and then the truncation caveat. Every sentence carries distinct information; there is no padding or repetition.

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

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

For a 5-param traversal tool with an output schema, the description supplies the return shape, the minimality guarantee, and the ambiguity caveat, so the agent can interpret results correctly. It stops short of explaining the memory parameter and the meaning/default of limit and max_depth, which are relevant to controlling the search.

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

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

Schema description coverage is 0%, so the description must compensate; it explains that start and target accept an object id or exact name/display name, which is genuinely useful. However, memory, limit, and max_depth are left entirely unexplained, and max_depth in particular interacts with the frontier_truncated behavior described. Partial compensation only.

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

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

The description names a specific operation and resource ('Shortest relationship paths between two objects in a memory') and frames the goal from the agent's perspective ('how are A and B connected?'). It is clearly distinguishable from siblings like get_object or get_graph at a glance.

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

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

It explicitly routes the agent away from an alternative: 'Use this instead of chaining get_object calls hop by hop.' That names the competing approach and the condition (multi-hop connection queries) under which this tool wins, which is exactly the when-to-use guidance needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, fully covering the safety profile. The description adds nothing beyond that (no pagination, no empty-case behavior), but with full annotation coverage a 3 is appropriate.

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

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

One tight sentence with the key clarification (which memory and where to get the slug) front-loaded. Zero waste.

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

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

For a simple 1-param read-only list with an output schema present, the description covers the essential input origin. It lacks disambiguation from sibling list tools, which is the main remaining gap given the tool's low 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 0%, and the single 'memory' param has no description in the schema. The description partially compensates by explaining it's a slug obtained from list_my_memories, which adds real meaning. But it stops short of format or validation details.

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 clear verb+resource (list classes in a memory). The parenthetical '(schema)' adds a useful gloss. However, it doesn't distinguish itself from the many sibling list_* tools (list_class_objects, list_objects, list_my_memories).

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 hints at the upstream step by referencing 'slug from list_my_memories', which implies a workflow. But it offers no when-not guidance or alternatives (e.g., list_class_objects vs list_classes), leaving selection among sibling list tools to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description adds the workflow dependency (other tools require a slug from this call), which annotations cannot express, but omits pagination or result-scoping details.

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

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

Two sentences, zero filler, front-loaded purpose followed by the required next action. Every clause earns its place.

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

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

For a zero-param list tool with an output schema, this is complete enough: it explains purpose, ordering, and how to consume the returned slug. The output schema covers return shape, so no omission is critical.

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?

No input parameters, so baseline is 4. The description usefully describes the OUTPUT key ('slug') that callers must reuse as the 'memory' argument, bridging to sibling tools' 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?

States a specific verb and resource ('List the memories') with a scope qualifier ('YOU can read and ingest into'), which distinguishes it from sibling list_* tools like list_objects or list_classes.

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 sequencing: 'Call this first, then pass the chosen slug as the memory argument to every other tool.' This is precise when/when-not and inter-tool workflow 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?

Beyond the annotations, the description discloses meaningful behavior: storage-order traversal, no semantic ranking, exclusion of descendants for class_name, approved-ownerships-only filtering, and the meaning of status ('defer on unapproved') and recall ('how much is waiting for review'). These are exactly the behavioral traits an agent needs that annotations do not 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 dense but every sentence earns its place: it front-loads the core purpose, then proceeds through parameters, behavior, and routing to alternatives. It is well organized with clear paragraph breaks and no filler or restatement of the tool name.

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

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

With an output schema present and annotations covering read-only/idempotent safety, the description fully supplies the remaining context: parameter semantics, traversal order, status interpretation, and when to choose a sibling tool. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters, and it meets it. It explains memory as a slug from list_my_memories, class_name as an exact canonical snake_case class name with descendants excluded, class_id as an equivalent filter, owned_by as a PERSON ownership filter, and limit's default of 50. Every parameter receives functional meaning beyond the raw schema.

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

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

The description states a specific verb and resource: 'ENUMERATE objects in a memory — the population, not the best matches.' It explicitly differentiates itself from semantic_search and recall by framing this tool as population enumeration rather than ranking or matching, so an agent can tell it apart from its siblings immediately.

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

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

The description gives explicit when-to-use guidance: use semantic_search when the question is 'what do we know about X?' and use list_objects when the goal is the population itself. It also names the upstream tools that provide valid inputs (list_my_memories for the memory slug, list_classes for class_name), leaving little to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real substance beyond them: exactly what is destroyed (the loser and its id), what is relocated (properties, edges, mentions, ownership), edge-cleanup behavior (self-loops and exact duplicates dropped), irreversibility, and the write-access requirement.

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

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

Front-loaded with the core action, then rationale, mechanics, and caveats in a logical order where each sentence adds operational value. It is somewhat long, and the extraction-cap rationale could be trimmed without losing callability, but for a destructive irreversible tool the detail is defensible.

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

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

An output schema exists, so return values need not be described. Given the destructive, cross-class-validated nature of the operation, the description covers everything needed to call it safely: preconditions, effects, auth, and post-condition (loser id stops resolving).

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 must carry the load, and it largely does: winner_id is 'the one to keep', loser can be given by loser_id or by loser_name with its resolution rule ('canonical snake_case name, resolved within the winner's class'). The `memory` parameter is never explained, and the precedence/mutual exclusivity of loser_id vs loser_name is left implicit.

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 ('fold a DUPLICATE object into the object it duplicates, then delete it') with the exact scope of the operation. It is trivially distinguishable from siblings like get_object or resolve_names, which are referenced as part of the workflow.

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

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

Explicitly says when to use it ('two objects of the SAME class denote one real thing'), why the situation arises (extraction coins near-duplicates because the known-objects hint is capped at newest rows), names the alternative to verify with (get_object on both), and states an exclusion (refuses a cross-class pair).

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds critical behavioral context: nothing is written until human approval, it requires write scope, and it queues exactly ONE action. This meaningfully extends beyond annotations, though rate limits and duplicate-handling are not covered.

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 crucial approval-gate fact in the first sentence, then breaks down parameter semantics cleanly. Slightly dense with the parenthetical registry pointer, but every section earns its place.

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

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

Covers the workspace_write kind thoroughly and mentions outbound kinds exist, but leaves their field schemas to an external registry. Output schema exists, so return values needn't be explained, but an agent still lacks a full picture of the kind parameter's valid values.

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

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

Schema description coverage is 0%, so the description must compensate, and it does — defining target, body, extra.class_name, extra.properties, and extra.relationships for workspace_write. But `memory` is only described as 'the slug' and `kind` semantics rely on 'see the API's action registry', leaving gaps.

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 (propose ONE action for human approval) and explicitly clarifies that nothing is executed until approval. This distinguishes it from sibling tools like submit_extraction_from_llm, which appear to execute directly.

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

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

The description clearly states the human-approval gate, defining when this tool applies versus direct-execution alternatives. However, it doesn't explicitly name which sibling to use for non-approval flows or when an agent should skip proposal entirely.

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 include readOnlyHint=true and destructiveHint=false, so the bar is lower; the description adds meaningful behavior beyond that: resulting `status` values, what 'unapproved' means, how `review_queue` counts pending human approvals, and that conflicts should be surfaced without taking a side. 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?

The description is front-loaded with the most important directive, organized into logical sections, and every sentence earns its place. It covers purpose, parameters, status semantics, and alternatives without unnecessary 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 read-only briefing tool, the description is complete: it explains what the tool returns, how parameters modify the call, the meaning of status fields, and when to prefer sibling tools. Since an output schema exists, the description need not enumerate exact 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 description coverage is 0%, so the description carries full responsibility. It describes all three parameters: `memory` as the slug from list_my_memories, `topic` as an optional addition that runs hybrid search and inlines hits, and `limit` as a bound on the recent list. This fully compensates for the missing schema descriptions.

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

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

The description states a specific verb and resource: 'brief me on this memory' and enumerates exactly what the composite read returns (classes and counts, recent additions, conflicts, approval queue, checkpoint). It also explicitly differentiates from siblings by naming semantic_search, get_object, and list_objects as alternatives for narrower lookups.

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 an explicit when-to-use instruction: 'CALL THIS FIRST, before working in a memory.' It also provides when-not-to-use guidance: 'Reach for something else when you already know what you are looking for' and names the specific sibling tools for those cases. The optional `topic` behavior is also explained as a conditional use case.

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

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

No annotations cover the key behaviors, and the description fills the gap richly: writes land unapproved and require human approval, name collisions cause updates rather than duplicates, new classes are auto-created, and near_duplicates in the response should be handled with merge_objects. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core action and follows a logical progression: core fields, write semantics, naming, session handoff, alternatives. Dense but every section earns its place. Slightly long, and the handoff section could be tighter, but it is well-structured and purposeful.

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

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

With an output schema present, the description doesn't need to explain return values, and it still points to the one response field that matters (near_duplicates). It covers all eight parameters, behavioral semantics, routing alternatives, and a key workflow (session handoff), making it complete for a rich, non-idempotent write tool.

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

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

Schema coverage is 0%, so the description carries the full burden and does so well: it explains text, class_name (with kind examples and default), properties (with a concrete example), relationships (with JSON shape and target_class behavior), and name semantics (derivation vs. update). It even covers source_doc and display_name indirectly through the update-vs-create pattern for name, though those two are less explicitly tied to their parameter names.

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

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

States a specific verb (record) and resource (one thing worth keeping), and explicitly scopes to ONE fact per call. It clearly distinguishes itself from siblings by naming the extraction pair as the alternative for whole documents.

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 guidance for session handoff, tells the agent when to use the extraction pair instead, and explains the update-vs-create rule via name collision. It also instructs the caller to report results to the user rather than treating writes as settled.

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, and non-destructive, so safety is covered; the description reinforces this with 'Read-only' and adds operational context the annotations don't: the 200-item batch cap and the two-part result structure (exact vs. scored matches). It stops short of describing rate limits, pagination, or what happens when the memory is empty.

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 usage directive is front-loaded ahead of the mechanical detail, and every sentence contributes something. The trailing 'Read-only' duplicates the annotation, and the parentheses around the items example make the middle dense, but there is 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?

With an output schema present, the description needn't enumerate return fields, and it still summarizes `exact` and `matches` usefully. Combined with the workflow placement and reuse rule, an agent has enough to call this correctly in the extraction pipeline; only the `memory` and `top_k` semantics remain unaddressed.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does well for `items` — spelling out the object's shape (kind/name/class_name) and the max of 200. However, `memory` and `top_k` are never explained, leaving two of three parameters undocumented in both schema and prose.

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 — check whether candidate names already exist in the memory — and frames the operation as a batch dedupe/resolution step rather than a search. This clearly separates it from siblings like semantic_search, list_objects, or merge_objects.

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 timing and cardinality: 'call ONCE per document during extraction, after drafting candidate entities and before emitting the final JSON.' It also states the decision rule — reuse returned canonical names, create only names with no hits — which is exactly the when/when-not guidance an agent needs.

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/idempotent/non-destructive, but the description adds substantial behavior beyond them: two fused rankers, the `via` field indicating which leg matched, newer-row tie-breaking, and graceful degradation with a `note` when the memory was never embedded.

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

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

Front-loaded with the core mechanic and then progressively detailed, with every sentence carrying information. Slightly ornate phrasing ('the rare token a vector smooths away') costs a little density but remains purposeful.

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

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

An output schema exists, so return formatting need not be spelled out, yet the description still explains the meaningful return-shape signals (`via`, `note`, `status`). For a 5-param search tool this covers everything an agent needs to invoke it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does for most params: `memory` (slug from list_my_memories), `kind` ('class'|'object'|omit), and `expand=1` (inlines first-ring properties and relationship groups). It leaves `top_k` and `query` semantics unstated, a minor gap.

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

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

States a specific verb+resource (search a memory's classes and objects) and immediately explains the dual-ranker mechanism, which differentiates it from siblings like recall or list_objects. An agent can distinguish it from get_object/get_paths 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?

Explicit routing: 'Prefer expand=1 whenever you intend to follow relationships; for reach beyond one ring, use get_paths instead of hopping get_object calls.' Also gives prerequisites (memory slug from list_my_memories, check status and defer on 'unapproved').

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=false, destructive=false, idempotent=false; the description adds genuinely new behavior — new rows land status='unapproved' — plus the two response conditions an agent must handle. It does not cover permission/auth requirements or what happens on partial failure, so it is strong but not exhaustive.

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

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

Workflow position is front-loaded, then per-parameter meaning, then response handling — each sentence earns its place and the parameter block is compact rather than padded. No redundancy with the annotation block.

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 an output schema exists, return values need not be re-specified; the description instead supplies what the schema cannot — the unapproved-row state and the required agent handling of validation_errors and near_duplicates. Nothing an agent needs to call and follow up correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: `memory` is the slug, `results` maps each pass `key` to that pass's JSON with a concrete example ({"classes": {...}, "objects": {...}}), and `source_doc` is an optional provenance label. All three parameters are given meaning absent from the schema.

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

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

States a specific verb+resource ("Save the extraction you produced") and situates it precisely in the workflow relative to siblings get_extraction_prompt and resolve_names. An agent can distinguish it from merge_objects, list_unapproved, and resolve_names 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?

Explicitly declares it is the LAST step after get_extraction_prompt and exactly one resolve_names call, and routes follow-up work: report validation_errors to the user, review near_duplicates and fold confirmed pairs with merge_objects. Both when-to-use and when-to-follow-up-with-an-alternative are named.

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