Ontonym

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

Annotations only declare write/idempotent/non-destructive. The description adds the operational details an agent actually needs: the ~25s wall-clock budget, the fact that the call usually returns unfinished with objects_remaining/classes_remaining counters, the safety of immediate re-invocation, the background worker, and the write-scope 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?

Four tight paragraphs with parameter names in code font, front-loaded with the purpose and ending with the practical loop-control advice. The all-caps emphasis and slight repetition of the backlog idea cost a little, but every sentence carries usable 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?

An output schema exists, so return-shape explanation is optional, yet the description still names the counter fields an agent must read to decide whether to call again. Combined with the write-scope note and the sibling relationship to semantic_search, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden. It documents two of three parameters concretely — force (skip already-embedded entities for the current model) and kinds (default ['object','class']). The 'memory' parameter is only implied as the graph target and is never named or explained, leaving a real 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 ('build (or top up) the vector index') and ties it directly to the consuming sibling tool, semantic_search. An agent can immediately tell this apart from recall, remember, and semantic_search itself.

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 ('Run this once per graph, and again after a large ingestion') plus the consequence of skipping it (every query returns ZERO results). It also gives an explicit when-not-to-loop: you do not have to drive the counter to zero because a background worker drains the backlog.

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, but the description goes well beyond: it enumerates exactly what is cascaded (properties, relationships, actions, mentions, ownership rows), states there is no undo and no tombstone, notes `reason` is written to the audit log, lists refused target classes (graph plumbing, `_system.*`), and requires write access.

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 action and IRREVERSIBLE warning in the first two lines, then organized into usage, exclusion, and mechanics. Dense but nearly every sentence adds actionable information; slightly longer than strictly necessary.

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

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

An output schema exists so return values need no explanation, and the description covers safety, cascade behavior, alternatives, refusals, and permissions. The only omission is the meaning of the required `memory` parameter.

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 parameter meaning. It explains `reason` (optional, written to audit log) and implies `object_id` via 'delete one object', but the required `memory` parameter is never explained, leaving a meaningful gap for a required field.

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 with cascade scope ('Delete one object and everything hanging off it'), and explicitly distinguishes itself from the merge_objects sibling. An agent can tell exactly what this does without opening the schema.

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

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

Explicit when-to-use cases ('what should never have been recorded: a wrong fact, a test row, something a person asked to have removed'), an explicit when-NOT case (duplicates belong to merge_objects), and prerequisite workflow (confirm with user, get_object first, prefer get_change_impact).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds real behavioral context by telling the agent this is 'one composite call' that bundles several analyses, which affects cost and result shape. It stops short of describing result size, latency, or whether missing objects error out.

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?

Extremely tight: one framing question, a compact enumeration of outputs, and one clarifying note on `memory`. The purpose is front-loaded and no sentence is filler, though the em-dash list reads slightly telegraphic.

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 explained, yet the description still sketches the payload categories — helpful for tool selection. Combined with the `memory` clarification and the composite-call note, an agent has enough 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 description coverage is 0%, so the description has to carry the burden. It clarifies that `memory` is the graph's slug, which is genuinely useful for a string param that would otherwise be ambiguous, but `object_id` is left entirely undocumented beyond its self-evident name.

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 composite read operation ('change impact') and enumerates what it aggregates: event-class neighbours, actions touching the object, property conflicts, related objects, provenance. That is far more than a restatement of the name and clearly distinguishes it from narrow siblings like get_object or get_paths, though it never names those siblings explicitly.

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

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

The framing question ('What should I watch out for if I change this object?') implies the pre-change analysis use case, so intended usage is inferable. But there is no explicit when-to-use statement, no exclusion, and no pointer to alternative tools such as get_object or get_paths for simpler lookups.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), but the description adds meaningful context beyond them: the document is NOT sent to the server, no object list is embedded, and resolve_names must be called ONCE. These are real behavioral facts an agent could not derive from annotations alone. Minor gap: it doesn't describe the return/pass format in detail, though an output schema exists.

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 opening line and the STEP-framing are front-loaded and each step earns its place, giving a usable workflow. It is dense but not padded; the only cost is length from enumerating all four flow stages, which is close to justified for a multi-tool orchestration.

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

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

Given a single parameter, an output schema (so return values need no prose) and a read-only annotation set, the description is complete: it covers when to use, the data-flow contract (nothing sent to server), and the required downstream calls. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0% for the single `memory` parameter, so the description carries the burden — and it does: '`memory` is the graph's slug from list_my_memories.' This gives both meaning and provenance for the value, which the bare schema property does not. Not a full 5 only because it doesn't state the slug format or a concrete example.

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 gives a specific verb+resource ('Add a document to the knowledge graph by extracting it YOURSELF') and explicitly positions the tool as 'STEP 1 of 4' in a named flow. It distinguishes itself from siblings like resolve_names and submit_extraction_from_llm by describing exactly what each does. An agent can tell this apart from the rest of the toolset 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?

It states the precise trigger: 'Use whenever the user shares a document/notes/transcript and wants it captured in the graph, and you (this assistant) should do the extraction.' The 'YOURSELF, in this chat' phrasing implicitly excludes the server-side alternative, and the workflow tells the agent what to do next rather than leaving it 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds a genuinely useful trait beyond that: an id belonging to a different graph 404s rather than resolving, and ids are not portable between graphs. It stops short of describing pagination or output volume, but the annotations carry most of the load.

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

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

Three short paragraphs, each front-loaded: return contents first, then parameter provenance and the 404 caveat, then routing to alternatives. Every sentence earns its place, though the block is slightly longer than strictly necessary for a two-parameter read 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?

With an output schema present, the description needn't enumerate return values, yet it still signals what comes back. Parameter provenance, the cross-graph 404 behavior, and sibling routing are all covered, leaving no material gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it states that `memory` is the graph slug from list_my_memories and that `object_id` comes from semantic_search, list_objects or recall. It also warns that ids cannot be reused across graphs. Only the integer type/format detail is left to the schema.

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

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

States a specific verb and resource plus the exact payload returned: properties, incoming and outgoing relationships grouped by type, actions that touch it, and approved owners. This is precise enough to distinguish it from siblings like get_paths and get_change_impact 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?

Dedicated 'Reach for something else when' block names three alternatives and the condition selecting each: semantic_search expand=1 for the first ring around many hits, get_paths for how two objects connect, get_change_impact for blast radius. Explicit when-not guidance with named alternatives.

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 safety (readOnly/idempotent/non-destructive), yet the description adds real behavioral context: the returned step shape {from, rel, direction, to}, the guarantee that paths are minimal length, and the crucial caveat that 'found: false' with 'frontier_truncated: true' is a breadth-cap artifact rather than proof of disconnection. That last detail materially changes how an agent interprets 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?

Front-loads the core purpose, then packs the input formats, output shape, and the frontier_truncated caveat into tight sentences with no filler. Every clause earns its place.

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

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

An output schema exists so return values need not be restated, yet the description still flags the interpretation trap in the results, which is the most likely source of agent error. Combined with the named alternative, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It does explain start/target semantics ('accept an object id or an exact name/display name') but leaves memory, limit, and max_depth entirely undocumented — including the max_depth that drives the frontier_truncated behavior it describes.

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 ('Shortest relationship paths between two objects in a graph') and adds a plain-language framing ('how are A and B connected?'). It clearly distinguishes itself from hop-by-hop get_object chaining and from unrelated siblings like list_objects or 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 routes the agent: 'Use this instead of chaining get_object calls hop by hop,' naming the alternative and the reason. It lacks any when-not guidance (e.g., cases where resolve_names or semantic_search should be tried first), so it falls just short of fully prescriptive.

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 the notion that the result is a schema/class listing scoped to a single graph, which is mild added value rather than rich behavioral context.

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

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

A single compact sentence with the action front-loaded and no padding. It is efficient, though the parenthetical is doing double duty and could be slightly clearer without adding length.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains thin is the identifier semantics and the absence of any routing guidance among the many sibling list/get tools, making the definition minimally adequate rather than 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 coverage is 0% with one required parameter named 'memory', so the description must carry the load and does partially: it says the value is a graph slug obtained from list_my_memories. However, this contradicts the schema's naming ('memory' vs 'slug'/'graph'), leaving the identifier's exact form somewhat ambiguous.

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: listing the classes (schema) within a graph. It also ties itself to the ecosystem by pointing at list_my_memories as the source of the graph identifier, which helps distinguish it from siblings like list_objects. It stops short of explicitly contrasting its scope with those 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?

Usage is only implied: the parenthetical reveals a prerequisite (obtain the slug via list_my_memories), which is useful context for invocation. There is no explicit statement of when this tool should be chosen over list_objects or get_object, nor any exclusion 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, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds genuine value beyond that: it discloses the access-scoping behavior ('graphs YOU can read and ingest into') and the bootstrap role in the toolchain. It does not discuss pagination or result size, which keeps it short of a 5.

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

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

Two short sentences, no filler. The identity/scope statement comes first and the workflow instruction second, so the most important framing 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?

An output schema exists, so return values need no further explanation, yet the description still highlights the one output field that matters for chaining (`slug`). For a zero-parameter discovery tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero input parameters, so the baseline is 4. The description adds cross-tool semantics by explaining that the returned `slug` is fed into the `memory` argument of every other tool, clarifying the intended use of the output field even though it is not an input.

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

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

States a specific verb and resource ('List the graphs') and immediately disambiguates the naming mismatch by making clear that 'memories' are graphs the caller can access. The permission scope ('YOU can read and ingest into') tells the agent this is a scoped, personalized listing, distinct from any sibling operation.

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

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

Explicitly routes the agent: 'Call this first, then pass the chosen `slug` as the `memory` argument to every other tool.' This gives both the sequencing (first) and the follow-up action, which is exactly the guidance a discovery tool needs. No competing sibling performs this function, so no exclusion is required.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. Beyond that, the description discloses storage-order traversal (not ranked by meaning), that each row carries a status field, that unapproved rows should be deferred, that recall shows pending review volume, and that class_name excludes descendants and owned_by returns approved ownerships only — rich behavioral context the annotations cannot 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?

Front-loaded with the key distinction, then organized by filter, then by sibling routing. Despite being longer than average, every sentence earns its place given five parameters at 0% schema coverage and the need to route against semantic_search.

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 gives the minimum return context an agent needs (status field, unapproved deferral, recall count). Combined with the exhaustive parameter guidance and sibling routing, nothing required to call 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?

With 0% schema description coverage, the description carries the full burden and does so: memory is the slug from list_my_memories, class_name is one exact canonical snake_case name from list_classes (descendants NOT included), class_id is the same filter by id, owned_by lists approved ownerships for one PERSON, and limit defaults to 50. All five parameters are explained with format and semantics.

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 ('ENUMERATE objects in a graph') and immediately distinguishes the result from ranked semantic search ('the population, not the best matches'). An agent can tell this apart from semantic_search and list_classes 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 names the alternative (semantic_search) and the condition that selects it ('what do we know about X?' vs 'the population itself: everything of one class, a count, a sweep, one person's responsibilities'). It also tells the agent when to defer ('defer on unapproved') and how to narrow filters.

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

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

Annotations already declare destructive=true and idempotent=false, but the description goes well beyond: irreversibility, the loser id ceasing to resolve, movement of properties/edges/mentions/ownership, dropping of resulting self-loops/exact duplicates, cross-class refusal, and the write-access requirement. This is rich behavioral context an agent could not infer 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?

Front-loads the core action in the first sentence, then layers mechanism, identification, and warnings in a logical order. Length is justified by the operation's dangerousness; no sentence is filler.

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

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

For a destructive mutation with an output schema present, the description covers everything an agent needs before calling: direction, irreversibility, identifier resolution, refusals, and access requirements. Only the 'memory' parameter is left to the schema.

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 must compensate, and it largely does: it explains winner_id as the keeper, and loser_id / loser_name as mutually-candidate identifiers, including that loser_name is a canonical snake_case name resolved within the winner's class. The 'memory' parameter, however, is never explained.

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 (fold a duplicate object into the object it duplicates, then delete it) and precisely names the direction of the operation (winner vs loser). An agent can distinguish it from siblings like forget or remember 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?

Gives an explicit when-to-use condition ('when two objects of the SAME class denote one real thing'), names the prerequisite action (confirm with get_object on both before calling), and states a hard exclusion (refuses a cross-class pair). Routing and preconditions are fully 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 declare readOnly=false, idempotent=false, destructive=false, and the description adds substantive context beyond them: the action is queued, not executed, until an owner approves, and it requires write scope. The 'Queue ONE action' phrasing also implies each call creates a distinct pending proposal, consistent with non-idempotency.

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 approval-gating behavior is front-loaded and every sentence carries parameter or behavioral information. The framing phrase 'The kind that makes this powerful from an AI client' is a bit of unearned filler, but the rest is dense and useful.

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

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

For a mutation tool with annotations and an output schema, the description covers the approval workflow, scope requirement, and per-field semantics of the primary kind well enough for correct invocation. It leaves outbound kind fields to the API registry, which is a documented gap but not a blocking one.

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: it maps target=record title, body=record body, extra.class_name=app class, extra.properties={property:value}, extra.relationships=[{type,target_name}], and memory=graph slug. Only `kind` is left to an external registry rather than enumerated inline, which keeps it from a 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: 'Queue ONE action for HUMAN APPROVAL,' and immediately clarifies the scope ('nothing is sent or written until a graph owner approves it'). No sibling tool performs this staged-approval function, so it is readily distinguishable.

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?

Explains the operating context (actions are gated by human approval) and distinguishes the `workspace_write` kind from outbound kinds (jira_comment, slack_message, gmail_send) and `memory`. It notes the write-scope requirement. It stops short of explicit when-not-to-use guidance (e.g., when to call a direct write tool instead).

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), and the description goes well beyond them: it explains the 'status' semantics ('unapproved' rows are human proposals), that review_queue counts pending approvals, and that conflicts must be surfaced rather than resolved. That is exactly the interpretive context an agent needs to avoid inventing facts.

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 imperative 'CALL THIS FIRST', then organized into return contents, parameter meanings, and exclusions. Every sentence carries load; length is justified by the breadth of the composite read.

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

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

The description covers trigger, contents, parameter semantics, and interpretation guidance for the returned fields. Although an output schema exists, the description still provides the interpretive layer (status handling, conflicts) that raw schema alone would not convey.

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 and does so for all three params: memory is the graph slug from list_my_memories, topic additionally runs hybrid search and inlines hits, and limit bounds the recent list. It even explains the design rationale for topic being a single call rather than two.

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 ('composite read that answers what a cold agent actually needs') and enumerates exactly what it returns: classes and counts, recent activity, conflicts, review queue, and session checkpoint. This clearly distinguishes it from the sibling reads an agent might otherwise pick.

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 'CALL THIS FIRST, before working in a graph' sets the when, and the closing line names when not to use it plus the specific alternatives: semantic_search for a topic, get_object for one thing, list_objects for a population. 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 only give the generic safety profile (readOnlyHint=false, idempotentHint=false); the description goes far beyond by disclosing that writes land status='unapproved', that the agent cannot read the row back until a human approves, that session_checkpoint is the exception, and that reusing an existing name performs an UPDATE rather than a create. These are precisely the nontrivial behaviors an agent must know before calling.

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

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

Front-loads the core action and then organizes the rest into labeled concerns (Naming, SESSION HANDOFF), so it is scannable. It is long for a tool description, but nearly every sentence carries operational information rather than filler.

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

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

For a complex 8-param mutation tool with an output schema, the description covers the mutation semantics, approval workflow, upsert dedup path, handoff use case, and even points at the near_duplicates field to check. Since an output schema exists, return-value detail is correctly omitted.

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

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

Schema coverage is 0%, so the description carries the burden, and it does so well for text, class_name, properties, relationships and name (including the upsert semantics and the relationships target_class trick). However, `memory` is a required parameter and is never explained, and source_doc/display_name are also unaddressed, leaving clear 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 ('Record ONE thing worth keeping, in a single call') and explicitly scopes what belongs here versus the extraction pair (get_extraction_prompt → submit_extraction_from_llm). An agent can distinguish this from recall, merge_objects and semantic_search without opening a schema.

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

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

Names alternatives and the condition selecting them: whole documents go to the extraction pair, duplicates get folded with merge_objects, and the SESSION HANDOFF paragraph gives an explicit when-to-use trigger ('before you run out of context'). Exclusions are stated, not inferred.

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 hints. The description adds genuinely useful context beyond that: the batching behavior (max 200, call once per document), and the result fields described in prose. It doesn't detail, so a 4 fits.

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 question, then usage timing, then input/output shape, then action guidance. The structure is logical and mostly tight; it's a bit dense but every sentence carries instruction.

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 needn't be fully explained, yet the description usefully pre-summarizes `exact` and `matches`. For a 3-param read-only tool this is nearly complete; only the `memory` and `top_k` params remain unexplained.

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% (no field descriptions), so the description must compensate. It does well for the central `items` param, documenting exact/extraction consumers the description names: `memory`, `top_k`, and the envelope shape aren't described in prose, leaving a 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 ('Ask which of your candidate names already exist in the graph') and distinguishes it from creation siblings like remember/merge_objects by emphasizing deduplication before emitting the final JSON.

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 instructs 'call ONCE per document during extraction, after drafting candidate entities and before emitting the final JSON' and clarifies the create-new alternative ('only names with no hits should be created new'), giving clear when-to-use and when-to-create-instead 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: two rankers fused, the `via` field indicating which legs matched, tie-breaking toward the NEWER row, and graceful degradation with a `note` when the graph 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 purpose, then mechanisms, then parameters, then routing guidance — a logical order. It is dense and long, and the expand paragraph could be tightened, but nearly every sentence carries actionable information.

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

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

With an output schema present, return-value details need not be explained, and the description still covers fallback behavior, status deferral, and expand semantics. An agent has everything needed to call it correctly and to route to siblings when appropriate.

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 explains three of five parameters well (memory = graph slug from list_my_memories, kind = 'class'|'object'|omit, expand=1 = inline first ring with counts and previews). top_k is left unexplained and query is only implicit, so it falls just short of fully compensating.

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 ('Search a graph's classes and objects') with explicit scope ('meaning AND keywords'). It distinguishes itself from retrieval siblings like get_object, get_paths, and list_objects by defining the hybrid vector+keyword fusion it performs.

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 routing: prefer expand=1 when you intend to follow relationships, use get_paths for reach beyond one ring instead of hopping get_object calls, and check `status` and defer on 'unapproved'. Alternatives are named with the conditions that select them.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, non-idempotent, non-destructive). The description adds substantial context the annotations cannot: new rows land status='unapproved' pending human review, approval is recorded under the user's name as "settled without review", is reversible in one click, and is refused with 403 unless the caller is an owner or owner-delegated approver. That is exactly the operational detail an agent needs before mutating graph state.

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 purpose and workflow position before the mechanics, and each paragraph covers a distinct concern (params, approve semantics, response handling). The approve paragraph is somewhat verbose and repeats the consequence framing, but the risk it mitigates justifies most of the length.

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

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

Despite a nested-object `results` parameter and no schema descriptions, the description covers inputs, workflow placement, approval authorization, and the two meaningful response fields (validation_errors, near_duplicates) even though an output schema exists. An agent has everything needed to call this correctly and handle its result.

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: `memory` is the graph's slug, `results` maps each pass `key` to that pass's JSON with a concrete example, `source_doc` is an optional provenance label, and `approve` has both a default (false) and a strict conditional trigger. Format and intent are supplied for every 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+resource ("Save the extraction you produced") and immediately positions it in the workflow as the LAST step after get_extraction_prompt and resolve_names, explicitly naming two siblings. An agent can place this tool in the pipeline 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?

Gives explicit sequencing (after get_extraction_prompt and your single resolve_names call), an exclusion rule for approve ("ONLY when the user explicitly asked... Never set it on your own judgement"), and routing for response anomalies (report validation_errors, fold near_duplicates with merge_objects). 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.