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

Annotations already declare readOnlyHint and idempotentHint, making the safe-read nature clear. The description adds behavioral context beyond annotations by explaining the claim command relay behavior and the consequence ('keeps all memories') in agent mode. 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 two sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds a crucial conditional instruction. Every clause earns its place, and the structure is easy to parse.

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

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

For a zero-parameter status tool with annotations and an output schema present, the description is complete. It explains what the tool reports, when to act on the result, and what the act achieves. The output schema can handle field-level details, so the description doesn't need to repeat them.

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 has zero parameters, so the schema already covers everything (100% coverage trivially). Baseline for 0 params is 4; the description doesn't need to add parameter semantics since none exist. It correctly focuses on the output and the conditional action.

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

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

The description clearly states the tool's purpose: it reports 'Tier, usage, limits, and expiry' for the agent's account. This is a specific verb+resource combination and distinguishes it from sibling memory/action tools. The additional instruction about relaying the claim command is a secondary actionable, but the core purpose is unambiguous.

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

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

The description provides clear context for when to use the tool in agent mode: 'relay the claim command to the human when usage status is "warning" or worse.' It gives a concrete condition and subsequent action, but does not explicitly name alternatives or exclusions. This is strong contextual guidance, though not a full when/when-not matrix.

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 read-only, idempotent, non-destructive annotations, the description discloses that the tool synthesizes answers with an LLM, cites the memory ids used, inherits the safety envelope of hebbrix_search, and fails closed with no citations if reasoning or evidence receipt is unavailable. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with a concise one-sentence summary, followed by a clear example, alternatives, and failure mode. The inline return JSON is somewhat redundant given the output schema, but the overall structure is scannable and each sentence 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?

The description covers purpose, usage, return shape, and failure behavior well, but the unexplained collection_id and include_graph parameters are a real gap for an agent deciding how to invoke the tool. The output schema mitigates return-value ambiguity, but parameter-level guidance is still 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 input schema has three parameters but 0% description coverage, and the tool description does not explain collection_id or include_graph at all. It only indirectly implies what the question parameter should contain through the natural-language example, which is insufficient for correct invocation.

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

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

The description clearly states the verb ('Answer'), the resource ('a natural-language question from memory'), and the key constraint ('in ONE call'). It explicitly differentiates itself from sibling tools by naming the orchestration it replaces (hebbrix_search + hebbrix_graph_query + profile), so an agent can easily tell what it does.

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

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

The description provides an explicit example of when to use the tool ('who works with me on Atlas and what did we decide?') and names the alternative composition it avoids. It does not include a 'when not to use' clause, but the substitution guidance is direct and unambiguous.

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

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

With annotations only declaring false hints, the description carries full responsibility. It reveals behavioral traits: records the action, recommends conservatively, never grants permissions, censors missing outcomes (not failures), and limits exploration to ≤0.2. These are meaningful and go beyond the schema. 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 well-structured into paragraphs that flow logically: purpose, usage modes, exploration constraints, and follow-up workflow. It front-loads the main purpose and avoids redundancy, though it is longer than minimal due to the complexity. Every sentence adds value without unnecessary fluff.

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 the complete decision-recording loop: choose, get decision_id, perform action, report outcome later. It explains the main parameters and the safe baseline. Given that an output schema exists, return values are not required. Missing parameters like idempotency_key and collection_id would benefit from brief notes, but overall it is nearly complete for the tool's intended use.

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 description explains key parameters (policy_key, actions, context, baseline_action, chosen_action, action_probability, exploration_rate) with semantic context (e.g., 'actions are stable machine keys', 'context contains only factors that may change which action works'). However, it omits details for user_id, collection_id, and idempotency_key, which are left entirely to the schema. Since schema description coverage is 0%, the description compensates for most but not all.

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?

Clearly states the tool's purpose: 'Choose and RECORD an action before its result is known.' It lists specific use cases (reply strategy, workflow, etc.) and differentiates from siblings like hebbrix_log_decision and hebbrix_report_outcome by focusing on the decision recording before outcome.

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?

Provides explicit guidance: normal use (omit chosen_action) vs logging an external choice (pass chosen_action and action_probability), sets an exploration_rate cap (≤0.2), and instructs to call hebbrix_report_outcome later. It also clarifies that outcomes are censored when missing, giving clear when-to-use vs when-not-to-use information.

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?

Annotation contradiction: The description explicitly states 'nothing is migrated or reset,' while annotations declare destructiveHint: true. This directly contradicts the system's destructive behavior hint, which could confuse the agent about the tool's safety profile. The description also usefully mentions sending a six-digit code, but the contradiction overrides this positive contribution.

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

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

Three sentences, front-loaded with the purpose, no filler. Every sentence adds essential information: what the tool does, when to call it, and what side effects to expect. This is a model of concise, structured writing.

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 prerequisites, the code-sending side effect, and the carry-over of memory/guest credential. The output schema handles return values, so no need to describe them. However, the contradiction with destructiveHint creates a slight gap in safety context, and it doesn't address potential error cases (e.g., invalid email). Still, for a simple one-parameter tool, it is fairly 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?

With a single parameter (email) and 0% schema coverage, the description adds meaning by explaining that the email is where the six-digit code is sent and that the human must provide it. This goes beyond the bare schema, though it does not specify format or validation rules.

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

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

The description clearly states the action: 'Keep an accountless guest memory permanently by starting email claim.' It uses a specific verb (start) and resource (email claim), and distinguishes itself from the sibling tool hebbrix_claim_verify by explaining that this tool initiates the process and the verification code is passed to verify.

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?

Provides explicit when-to-use guidance: 'Only call this after the human explicitly asks to claim/keep the guest memory and provides the email address.' It also explains the follow-up step (pass the code to hebbrix_claim_verify), giving clear context for how this tool fits into the overall flow.

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?

Since the annotations are only false flags, the description defines the actual behavioral effect: same memories remain available, and guest expiry/caps are replaced by a regular claimed-account tier. It doesn't describe failure modes, but the main success state and the state mutation are made clear.

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 concise sentences: the first states the operation, the second gives the comparator and postcondition. Everything is front-loaded and every sentence contributes; no unnecessary detail.

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?

Although the description is short, it includes the mandatory predecessor, the user-code precondition, the success state, and the type of security tier change. Since the output schema is provided the description does not need to explain the return value, and it is sufficient for a simple verification step.

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

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

The schema merely defines a required code string with format password, so the description adds crucial semantics by stating the code is 'emailed' and 'six-digit'. This is enough for a single parameter, though it doesn't literally map the parameter name in the 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?

The description uses the specific verb 'Finish claiming' and identifies the target resource as 'guest memory with an emailed six-digit code', which makes its purpose clear. It should be executed after hebbrix_claim_start, so it is unambiguous when compared with that sibling.

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

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

It explicitly says 'Only call after hebbrix_claim_start and after the human supplies the code', giving a definitive ordering and an exact precondition. This tells the agent exactly when to use the tool and not to use it beforehand.

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 indicate readOnly, idempotent, non-destructive behavior. The description adds valuable context: it returns a confidence score and recommended action, and it handles constraint violations with a dedicated block and do_not_act recommendation. This goes beyond annotation-provided safety info, with no contradictions.

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 concise and well-structured: first paragraph covers purpose and usage, second paragraph details a special edge case. No redundant sentences; every sentence 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?

Given the tool's moderate complexity and the presence of an output schema, the description covers purpose, when to use, return value, and conflict behavior. The main gap is parameter semantics, but overall it is sufficiently complete for an agent to select the tool confidently. Slightly docked for not explaining query/collection_id.

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. However, it never explains what the 'query' parameter should contain (e.g., the proposed action or situation) or the purpose of 'collection_id'. The high-level phrasing implies query is the action, but this is not explicit, leaving agents guessing at invocation 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?

The description clearly states the tool's function: asking how confident the agent should be before acting, grounded in stored memory and past outcomes. It distinguishes itself from siblings by specifying the return of a confidence score and recommended action, and the constraint_conflict block for numeric rule violations.

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

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

The description provides an explicit when-to-use directive: 'Call this before a consequential autonomous action.' It does not explicitly name alternatives or exclusion cases, but the context makes the intended usage clear. A minor gap versus naming a specific alternative tool.

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 and idempotent behavior. The description adds value by specifying scoping behavior (one memory vs. full scan) and an example of what constitutes a contradiction. 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?

Two concise sentences that are front-loaded with purpose and usage. No redundant phrases or filler. Every clause contributes meaning.

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

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

Given the output schema exists, return details are not needed. The description covers the main functionality and usage modes, but misses explaining the second parameter (collection_id). Slight gap but overall sufficient for a read-only 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%, so the description must compensate. It explains 'memory_id' as an optional filter, but 'collection_id' is not mentioned at all, leaving its role ambiguous. This partial clarification earns a 3.

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

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

The description clearly states the verb 'surface' and resource 'contradicting facts in the knowledge graph' with a concrete example ('two different values for the same attribute'). This is specific and distinguishes it from sibling tools like heaprix_confidence or heaprix_ask.

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?

Provides explicit contextual guidance: 'Use before trusting a fact that feels ambiguous.' Also explains the two usage modes (pass a memory_id or omit to scan), which is a clear condition for invocation. Though no alternatives are named, the situational cue is strong.

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

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

The description correctly indicates a write operation, consistent with readOnlyHint=false, and adds that the object is tenant-scoped. However, it does not explain creation semantics such as duplicate behavior, required tenant context, or how 'learned' affects persistence, so it adds only modest context beyond the annotations.

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

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

The description is a single front-loaded sentence with no redundant words. It loses one point because the phrase 'canonical API fields' is vague and could mislead, but it is otherwise economically structured.

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 identifies the resource type and tenant scope, and output schema provides return-shape context, but it is far too thin for a 10-parameter create tool with two free-form nested objects. The agent is left without guidance on required field semantics, relationships between run_id/user_id/agent_id, or how condition and action are structured.

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 10 parameters and 0% schema description coverage, the description needed to explain the open-ended condition/action objects and the optional identifiers, but it only says 'canonical API fields' without identifying any of them. An agent cannot determine what to place in name, condition, action, parameters, or collection_id.

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 clear action ('Create'), a specific resource ('tenant-scoped learned procedure'), and the required input style ('canonical API fields'). It is readily distinguished from siblings like hebbrix_update_procedure, hebbrix_delete_procedure, and hebbrix_get_procedure.

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

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

No when-to-use guidance is provided: it does not say when to choose this over hebbrix_update_procedure, hebbrix_remember, or hebbrix_execute_procedure, and it gives no prerequisites or constraints. The intended usage must be inferred solely from the sibling names.

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 explains that the API returns the same 204 for deleted, absent, and foreign-tenant ids and that this prevents disclosure of another tenant's procedure identity. This adds meaningful behavioral context that annotations alone do not provide.

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

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

Two short sentences, zero filler, and the core operation is front-loaded. Every clause adds value, especially the security-relevant 204 note.

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

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

For a one-parameter destructive tool, the description, annotations, and output schema cover what an agent needs: the delete semantics, idempotency, tenant scoping, response-code uniformity, and privacy guarantee. No material gap remains.

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. While it does not explicitly restate that procedure_id identifies the procedure, the second sentence clarifies important semantics: foreign or absent ids are treated identically, and the idempotent delete behavior directly affects how the result of any procedure_id should be interpreted.

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

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

The opening phrase 'Idempotently delete a tenant-owned procedure and its executions' names a specific verb, resource, and scope, making it unmistakable and distinct from sibling create/update/get/list/execute procedure tools.

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 establishes the tool's use case: removing a tenant-owned procedure and its executions. It does not explicitly name alternatives or exclusions, but the delete semantics are unambiguous and sufficient to route an agent to this tool over siblings.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds the meaningful 'bi-temporal' semantic (dual time dimensions — valid time and assertion time), clarifies the scope ('one entity'), and reveals the case-insensitive matching behavior. This enriches the agent's understanding beyond the structured annotations.

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

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

Three tight sentences. The crucial purpose is front-loaded in sentence one, usage guidance in sentence two, and a valuable behavioral note (case-insensitivity) in the final sentence. Zero filler, every sentence 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?

The tool has moderate complexity (2 params, output schema present). The description covers core purpose and usage, and the case-insensitivity detail is useful, but collection_id is completely unaddressed, which is necessary for a complete picture. The output schema mitigates return-structure concerns, but the param gap makes this only minimally 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%, so the description must compensate. It partially documents entity_name ('for one entity', 'case-insensitive') but never mentions collection_id, its purpose, or its effect on the query. With two parameters and zero schema descriptions, this is a significant gap leaving the optional parameter undocumented.

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

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

The description clearly states the tool's purpose: 'Bi-temporal timeline for one entity: what facts were true about it and when.' This is a specific verb+resource (timeline of a single entity) and distinguishes it from siblings like hebbrix_get (current state) and hebbrix_list (multiple entities). However, it doesn't explicitly contrast with hebbrix_history, which could be overlapping, preventing a 5.

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 usage context: 'Use this for "what changed" / "what was true at time X" questions about a person, company, or thing.' This tells the agent when to invoke the tool. However, it doesn't state when NOT to use it or name alternative sibling tools, so the guidance is clear but not exhaustive.

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

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

The description adds 'record its execution,' a behavioral detail not present in the annotations, and notes the tenant-ownership constraint. It does not mention authentication needs, what happens on failure, or whether execution may mutate external state beyond the record, so transparency is only partial.

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

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

The description is a single front-loaded sentence that conveys the core purpose and the key side effect without filler. It loses one point because its brevity leaves important operational detail unstated.

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 tool with three parameters, no schema descriptions, and only minimal annotations, the description is incomplete: it does not clarify what goes into 'parameters' versus 'input_state', whether the procedure must already exist, or what execution entails beyond being recorded. The presence of an output schema reduces the need to describe return values but does not close these gaps.

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 needed to explain the free-form 'parameters' and 'input_state' objects, but it does not. It adds no meaning beyond the parameter names and procedure_id requirement already visible in 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?

The description states a specific action ('Execute'), a clearly bounded resource ('one tenant-owned procedure'), and a distinctive side effect ('record its execution'). This separates it from procedure-management siblings like hebbrix_get_procedure, hebbrix_create_procedure, and hebbrix_list_procedures.

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 intended use is implied: call this when you want to run a tenant-owned procedure. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as viewing a procedure first with hebbrix_get_procedure or choosing an action via hebbrix_choose_action.

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 define it as read-only, idempotent, and non-destructive. The description adds that 'nothing is locked in' and explains the markdown return format, corroborating the annotations. It lacks details on potential pagination or output size limits, but the core behavior is transparent.

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 concise, consisting of two sentences that deliver purpose and key parameter details. It is well-structured, with no redundancy or irrelevant 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?

Given the absence of an output schema and minimal description of collection_id, the description is not fully complete. It mentions 'structured data' for JSON but does not detail the structure or specify how collections are identified. The markdown return key is noted, but overall context for a complex export operation is lacking.

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 description explains the 'format' parameter (json vs markdown) and its impact on the return structure. However, the 'collection_id' parameter is not described beyond the vague 'collection' in the purpose, leaving ambiguity about its role (e.g., what happens when null, or whether it is required for non-default collections).

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

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

The description clearly states the tool exports everything in a collection (memories, knowledge-graph entities, compiled profile), making its core function unambiguous. This distinguishes it from sibling tools like get, list, or search which handle subsets.

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 explicitly mentions data portability for backup or migration, giving a clear use case. However, it does not explicitly contrast with alternatives or state when not to use it, though the purpose is clear enough.

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

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

The description reveals behavior beyond the safe annotations: it describes the status lifecycle (queued/processing/indexing_until terminal), what happens at completion vs failure, and a retention-window expiration. This gives the agent crucial information about repeated polling and timeout risks that would otherwise be invisible.

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 crisp sentences, not a single redundant word. The main purpose is front-loaded, then state-transition and expiration hazards are explained in two more lines. Ideal for parsing by an agent and compared to verbose descriptions.

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 polling tool with an output schema available, the description fully covers the workflow context: how the job is created, what states it transitions through, the terminal results, and the warning about expiry. No critical context appears to be 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 parameter semantics. It only implies that job_id is the job returned by hebbrix_remember, but it never mentions collection_id, its purpose, or usage. Two parameters, one optional, are left mostly undocumented semantically.

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

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

The description opens with a specific action, 'Poll a smart-ingestion job returned by hebbrix_remember(extract=True)', which clearly defines the resource and provenance. This makes the tool obvious distinct from all sibling memory-management tools, which focus on reading, writing, searching, or deleting rather than polling a job.

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 tells users exactly when to invoke this tool: after hebbrix_remember(extract=True). It also gives an imperative 'poll promptly' because jobs expire. It doesn't list alternatives or explicit when-not scenarios, but this is naturally the only polling tool in the set, so the context is clear enough.

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

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

The description goes beyond the annotations by detailing the exact successful response (deleted=true and id), the already-absent edge case (structured 404 plus already_absent=true), and response-body independence. This gives an agent a stable model of both success and failure behavior, which is highly valuable for a destructive operation.

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

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

The description is short and front-loaded with the core purpose, followed by two compact sentences covering response semantics and an important edge case. Every sentence adds distinct and useful information without redundancy.

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

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

For a one-parameter delete tool, the description plus the destructive and idempotent annotations give a complete picture of what happens on success, what happens on missing id, and what type of error to expect. No critical selection or invocation behavior 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 schema has one obvious parameter, memory_id, and the description reinforces that it is the identifier of the memory being deleted. It adds little format or constraint detail, but the low complexity and self-explanatory parameter name make this a minimally acceptable level.

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?

"Delete a memory by id" uses a specific action verb and clear resource, and the semantic distinction from sibling tools like hebbrix_update or hebbrix_remember is obvious. The purpose is immediately understandable and not redundant with the tool name.

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 implies the tool should be used when a memory needs to be deleted by its id, and the error handling text adds operational context. However, it does not explicitly contrast with alternatives or say when not to use it, e.g. when only marking a memory used or updating it 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns 'full content and metadata,' providing useful behavioral context beyond the annotations. No contradictions.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It states the action, resource, and return content efficiently.

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 single-parameter get tool with strong annotations and an output schema, the description is complete. It covers the core functionality and return content, and the output schema handles detailed return format. No major gaps.

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

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

Schema description coverage is 0% and the description only says 'by id,' which largely repeats the parameter title 'Memory Id.' It does not explain the format, example, or how to obtain a valid memory_id, failing to add meaningful semantics beyond 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?

The description clearly states 'Fetch one memory by id, including its full content and metadata.' It specifies a precise verb (fetch) and resource (memory by id), distinguishing it from sibling tools like hebbrix_list (which likely lists multiple) or hebbrix_search (which searches).

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

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

The description implies usage when you have a specific memory id, but it does not explicitly mention when not to use it or provide alternatives such as hebbrix_list or hebbrix_search. Context is clear but lacks explicit exclusions or alternative guidance.

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

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

The annotations already communicate readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It does add the tenant-ownership scoping, but provides no further behavioral context such as errors, permissions, or absence of side effects beyond what the annotations imply.

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

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

The description is a single sentence with no filler. The verb, resource, and retrieval method are front-loaded, making the tool's purpose immediately obvious.

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 single-entity fetch tool with one well-named parameter, a supporting output schema, and safety annotations, the description is nearly complete. It could be stronger by explicitly naming sibling alternatives or noting what happens when no procedure matches, but no critical information 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?

There is a single parameter, procedure_id, with 0% schema description coverage. The description's 'by id' clarifies that the parameter is the lookup key, but it does not describe the ID format, how to obtain it, or any constraints, so the description only partially compensates for the missing schema documentation.

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

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

The description uses a specific verb ('Get'), a specific resource ('one tenant-owned procedure'), and a clear retrieval method ('by id'). The singular scope and resource type distinguish it from sibling tools like hebbrix_list_procedures, hebbrix_search, and hebbrix_execute_procedure.

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 'by id' phrase implies this tool is for retrieving a single known procedure rather than listing or searching, and 'tenant-owned' scopes the use case. However, there is no explicit guidance on when not to use it or which alternative to choose when an ID is unavailable.

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 indicate a read-only, idempotent, non-destructive operation. The description adds useful behavior context beyond annotations by explaining bi-temporal timestamp semantics and depth range (1-5), which are not inferable from the schema alone.

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

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

Two concise paragraphs: the first introduces the core function and key parameters; the second provides a clear use-case differentiation. No word is wasted, making it easy to scan and understand quickly.

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

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

For a graph traversal tool with an output schema present, the description covers the essential usage: what it does, how to use the primary parameters, and when to choose an alternative. Minor omissions like relation_type and collection_id filtering options prevent a perfect score, but these are intuitive from their names.

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 illuminate parameters. It effectively explains 'timestamp' (ISO format, bi-temporal) and 'depth' (graph hops, 1-5), but omits 'relation_type' and 'collection_id' which are left entirely to the schema. This partially compensates for the missing parameter documentation.

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?

Clearly states the tool traverses a knowledge graph from a named entity to find relationships and facts, with a specific verb-resource pairing. It explicitly distinguishes itself from hebbrix_ask by contrasting entity-based traversal vs free-text querying.

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?

Provides explicit when-to-use guidance by directing free-text questions to hebbrix_ask while clarifying this tool is for known entities. This direct comparison with a specific sibling alternative makes the usage context unambiguous.

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

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

The description goes well beyond the readOnlyHint and idempotentHint annotations by explaining that ready requires durable enrichment plus a successful graph read, that related_memory_count counts neighboring memories rather than extracted relationships, and that a zero count does not imply missing edges. It also discloses that the tool never fabricates edges from spelling conventions and that wait_seconds is capped at 30 seconds. This is substantial behavioral context.

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

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

The description is compact and front-loaded with the core purpose. Every subsequent sentence adds decision-relevant clarification: the definition of ready, the polling bound, the count semantics, and the fabrication caveat. There is no filler or redundant restatement.

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

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

Given the output schema exists and annotations already declare the operation read-only, idempotent, and non-destructive, the description supplies the remaining context an agent needs: async readiness semantics, polling behavior, and the meaning of a potentially confusing count field. Nothing critical is missing 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 parameter meaning. It explains wait_seconds as optional bounded polling up to 30 seconds, which is not inferable from the schema alone. memory_id is not elaborated, but its role as the target memory identifier is clear from the opening sentence and parameter 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?

The description opens with a specific verb and resource: "Check whether one memory's asynchronous graph enrichment is ready." This clearly distinguishes the tool from siblings like extraction_status by targeting graph enrichment readiness rather than extraction progress. It further defines what "ready" means, so an agent knows exactly what state is being tested.

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

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

The description implies a clear usage context: poll or check the status of asynchronous graph enrichment for a single memory. It also documents bounded polling via wait_seconds. However, it does not explicitly explain when to prefer this tool over similar siblings such as hebbrix_extraction_status or hebbrix_graph_query, leaving some routing 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that it shows historical changes and supersessions, providing additional behavioral insight beyond the annotations without contradiction.

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 concise and to the point—two sentences with no redundancy. It efficiently communicates purpose and use case.

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 (not shown), return values are covered. The description explains the operation's purpose and behavior sufficiently for a memory history tool, though it omits edge cases like ordering or deleted versions, which are minor.

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 only parameter 'memory_id' has no description in the schema, and the description does not clarify its meaning, format, or any constraints. It relies solely on the parameter name, offering no added value.

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

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

The description clearly states the tool shows version history of a memory, including supersessions, and its use case ('see what a fact used to be'). This distinguishes it from siblings like get, list, or update.

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

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

It provides a clear use case ('useful to see what a fact used to be'), implying when to use it. However, it doesn't explicitly contrast with alternatives (e.g., 'use get for current value') but the intent is clear given the sibling names.

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

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

The description details accepted data types, transformation rules (e.g., bullets stripped, non-heading lines become memories), and return format, adding substantial behavioral context beyond the sparse 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?

Concise and front-loaded, with each sentence adding value. The description is free of fluff while covering critical usage details.

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

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

Covers the primary input formats and return values, but the lack of documentation for `collection_id` and `wait_for_index` leaves minor gaps. Given the output schema exists and the main parameter is well-covered, it's mostly 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?

The `data` parameter is thoroughly explained with multiple accepted formats and transformations, but `collection_id` and `wait_for_index` are not described at all. With 0% schema coverage, the description compensates strongly for one parameter but ignores the other 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?

The description clearly states 'Import memories into a collection' and identifies itself as the inverse of hebbrix_export, distinguishing it from siblings. It also lists concrete use cases like restoring a backup, migrating, and seeding from notes.

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 provides use cases and positions itself against hebbrix_export, giving clear context for when to use it. However, it doesn't mention alternatives for similar operations (e.g., hebbrix_remember) or state when NOT to use it.

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 indicate read-only, idempotent, non-destructive. The description adds details about the readiness check and refusal behavior, enhancing transparency beyond 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 concise, with two clear sentences. It structures purpose first, then return details and the extra check. No redundant 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?

The description covers output and the evaluate_readiness behavior, but omits explanations for several optional parameters. Given the relatively simple tool (read-only analytics), it partially fulfills context but has gaps.

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

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

Only policy_key and evaluate_readiness are implicitly or explicitly described. Other parameters (actions, context, user_id, collection_id) are not explained despite having no schema descriptions. The description references 'tenant/user/context' but does not map to specific parameters.

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

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

The description clearly states the tool's purpose: explaining what a policy has learned, with uncertainty. It differentiates from siblings by focusing on learning insights with probabilistic outcomes.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not mention sibling tools or provide contextual triggers for usage.

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, and destructiveHint, covering the main behavioral aspects. The description adds minimal extra context (recent, collection) without contradicting 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 a single, clear sentence with no unnecessary words. It is well-structured and directly to the point.

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 having an output schema, the description is minimal. It does not explain what 'memories' or 'collection' refer to, nor does it provide any filtering or pagination details beyond the parameter names. The overall context is insufficient for a complete understanding.

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 parameters limit and collection_id are not explained in the description. With zero schema descriptions, the description fails to clarify their purpose or constraints, leaving the agent without adequate information.

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

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

The description clearly states the action (list), the resource (memories), and the scope (recent, in a collection). It effectively distinguishes from sibling tools like hebbrix_get or hebbrix_search.

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

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

The description does not indicate when to use this tool versus alternatives such as hebbrix_search or hebbrix_history. It lacks contextual guidance on appropriate use cases or boundaries.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive; the description adds scoping context (API key) which is useful but not extensive beyond what annotations 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?

Single concise sentence, no fluff, direct and to the point.

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 parameter-less list operation, the description is fully sufficient, and output schema is present to cover return details.

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 parameters exist, so there is nothing to clarify; the description adds no ambiguity.

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

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

The description clearly states the tool lists collections and clarifies that they are memory spaces/tenants scoped to the API key, distinguishing it from other list operations.

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

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

The description implies usage for enumerating collections but does not explicitly mention when to prefer this over alternatives or provide exclusion criteria.

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

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

The annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds that the result is scoped to the current tenant and only to learned procedures, which is useful context. However, it does not disclose behavior such as pagination semantics, default filtering by active_only, or how category and collection_id interact.

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

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

The description is a single front-loaded sentence with no filler. It efficiently communicates the action, object, and scope, and every word 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?

The output schema covers the return shape and all parameters have defaults, so a basic call is feasible without further info. Still, the overall context is thin: five filtering parameters are undocumented, and no usage guidance or behavior details are provided, leaving an agent to infer important semantics.

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

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

Schema description coverage is 0%, and the description does not explain any of the five parameters. Parameter names like skip, limit, category, active_only, and collection_id are somewhat self-explanatory, but the description itself adds no parameter-level meaning, so it does not compensate 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 clearly states the verb ('List'), the resource ('learned procedures'), and the scope ('owned by the current tenant'), which distinguishes it from procedure-specific siblings like hebbrix_get_procedure and hebbrix_delete_procedure. However, it does not explicitly contrast itself with similar list/search siblings such as hebbrix_list or hebbrix_search, so it falls just short of a 5.

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

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

No guidance is provided about when to use this tool versus alternatives like hebbrix_get_procedure, hebbrix_list, or hebbrix_search_entities. The listing purpose is implied, but no exclusions or alternative routing are stated, which is a significant gap given the large sibling tool set.

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 are all false, so description must carry the transparency burden. It discloses that logs feed hebbrix_confidence, affecting future recommendations—a key side effect. It also explains the auto-fill shortcut behavior. It doesn't mention database persistence, overwrites, or other edge cases, but for a logging tool this is reasonable. No contradictions 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 two short paragraphs: the first states the core purpose, the second provides a usage shortcut. It's front-loaded with the main purpose, and every sentence adds value. Slightly repetitive (mentions outcome twice) but overall efficient.

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 that annotations offer no hints (all false, though readOnly is correctly false as it's a write), the description does explain the side effect on hebbrix_confidence, which is important. It doesn't detail output or error conditions, but for a logging tool with output schema available, this is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'decision' and 'outcome' with allowed values (success | failure | partial) but does not explain the other parameters (collection_id, decision_type presumably). The shortcut hints at omitting description when outcome is provided, but doesn't clarify what each parameter contains or requiredness. The description under-explains the parameter 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?

The description clearly states the tool logs a decision and its outcome, with a specific verb (record) and resource (decision). It distinguishes itself from siblings like hebbrix_choose_action (which likely selects an action) and hebbrix_report_outcome (which may report results separately). The link to hebbrix_confidence adds purpose context.

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 explains the primary use case (logging decisions and outcomes to improve confidence) and provides a shortcut for logging right after a confidence check. It lacks explicit 'when not to use' or comparisons against alternatives like hebbrix_report_outcome, but the context is clear enough for most scenarios.

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

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

The description explains the Hebbian learning effect where memories are strengthened or weakened based on feedback—an appropriate side effect for the tool. However, it lacks explicit disclosure of whether the operation is a write-ahead log, partial update, or appends; it just says 'strengthens it' without detailing back-end behavior. No contradiction with annotations found.

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

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

The description is a single, moderately long paragraph without line breaks or bolding to aid scanning. It front-loads the most important information but adds a somewhat conversational 'if handy' at the end, which slightly dilutes the formality. It's adequate but not elegantly structured.

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 straightforward feedback tool with 3 parameters (1 required), the description covers the key dimensions: the `helpful` side effect, the `query` purpose, and the meta-insight about memory ranking. Since an output schema exists, the lack of return-value documentation is not a gap.

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

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

With 0% schema coverage, the description carries the full burden, and it delivers well. It clarifies the `helpful` boolean as a strengthen/weaken switch and describes `query` as 'the question it helped answer.' However, it only implicitly covers memory_id by referring to 'a memory' without explicitly naming the 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?

The description uses clear action verbs like 'Reinforce a memory you actually USED' and explains the mechanism of strengthening/weakening, distinguishing it from sibling tools like hebbrix_remember or hebbrix_log_decision. It could be more explicit by using the tool's name 'mark_used' directly, but it's unambiguous about the core action.

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

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

The description provides explicit when-to-use guidance: 'call this when a retrieved memory was helpful... or was noise.' However, it fails to mention exclusions or alternatives like 'use hebbrix_get for retrieval instead.' The guidance is implied from sibling names but never confirmed.

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 establish write, non-idempotent, non-destructive semantics; the description adds the full async behavior: extraction polling up to 20s with a job_id result, the searchable flag meaning indexing is still pending, and knowledge-graph enrichment being asynchronous (~30s) and NOT covered by wait_for_index. It also discloses the return contract ({'id','status','searchable','graph_enrichment',...} or {'error'}) and warns against repeating writes, all consistent with idempotentHint=false, so there is no contradiction.

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?

Around 350 words, but every unit earns its place: purpose and trigger first, then one focused explanation per boolean flag, then async graph caveats, the multi-fact efficiency rule, and the return format. The density is justified by the tool's complexity (three behavioral flags, tracked jobs, async indexing), and there is no filler or repetition.

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

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

For a six-parameter tool with async jobs, indexing, and graph enrichment, the description covers the full decision tree: when to call, which flags to set in which scenario, how to interpret searchable and graph_enrichment in the response, how to follow up via the documented poll tools, and when to avoid blocking serial writes. The only residual gaps are the semantics of tags and collection_id and an explicit cross-reference to hebbrix_remember_many, both minor against an output schema that already documents the return shape.

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%, and the description compensates for the three behavior-controlling booleans: extract (exact-store vs fact-extraction with job_id polling), wait_for_extraction (defer to hebbrix_extraction_status), and wait_for_index (searchable semantics, bulk-write advice). However, tags and collection_id are never mentioned in the description, so two of six parameters rely solely on their generated 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?

Opens with the crisp verb+resource pair 'Store a memory' and immediately broadens into a triggering condition ('user shares a fact, decision, or preference worth recalling later'). It differentiates itself from the obvious alternative (writing notes to files) and, via the multi-fact guidance, carves out when heavy extraction is preferred, so an agent can tell this apart from hebbrix_remember_many without opening either schema.

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

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

Gives an explicit when-to-use trigger ('user shares a fact, decision, or preference worth recalling later') and an explicit precedence rule ('prefer it over writing notes to files'). It routes follow-up work to named siblings hebbrix_extraction_status(job_id) when wait_for_extraction=False and hebbrix_get(id) when searchable=false, and tells the agent not to repeat the write, preventing duplicate-memory mistakes.

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 are minimal (non-read-only, not idempotent), so the description carries the burden. It discloses return fields, the wait_for_index default and blocking behavior, the tier-based fallback to sequential writes, and the 'fallback': 'sequential' result field. This adds substantial context beyond 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 compact and front-loaded with the most important point. Each paragraph adds distinct value: usage guidance, parameter behavior, and tier-specific fallback. No fluff or redundant restatement of the schema.

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

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

Given the tool's moderate complexity, the presence of an output schema, and sibling-tool context, the description provides sufficient operational context: when to use it, what it returns, how wait_for_index works, and the tier caveat. Only minor param detail (collection_id) is left to the schema, which is acceptable here.

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 clearly explains the facts array format and wait_for_index behavior, but collection_id is not mentioned in the description. Since 2 of 3 parameters receive meaningful semantic elaboration, this is strong but not complete.

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

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

The description's first sentence, 'Store MANY facts in one call,' uses a specific verb and resource while immediately distinguishing this batch tool from the single-fact sibling hebbrix_remember. It clearly states the batching purpose and avoids ambiguity.

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

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

Explicit guidance is provided: use this tool when extracting several distinct facts from one user message instead of calling hebbrix_remember N times. It also explains the trade-off, including one round-trip and one rate-limit hit, and notes the tier-dependent fallback behavior.

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 indicate destructiveHint=true and readOnlyHint=false, but the description adds specific behavioral details: how to avoid double-counting via correction, safe reuse of idempotency_key, and rejection of conflicting reuse. It also clarifies that this is a writing operation for outcomes. These details go beyond the raw annotation flags, providing operational context that helps agents handle side effects appropriately.

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 core purpose in the first sentence, followed by structured parameter-specific guidance. It consists of six sentences, each adding distinct value (value ranges, metrics prerequisite, final/correction semantics, idempotency). It is slightly lengthy but remains efficient and organized, avoiding redundancy.

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

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

Given the high parameter count (8) and zero schema coverage, the description is notably complete: it explains most parameters, their interactions, and prerequisites. It does not describe the output (though an output schema exists) or detail confidence, but these gaps are minor. Overall, the description provides enough context for an agent to use the tool 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?

With schema description coverage at 0%, the description takes over parameter explanation entirely. It covers success/reward values, metrics declaration requirement, final and correction flags, and idempotency_key behavior. Though it omits confidence and decision_id, these are self-explanatory from names and the required status of decision_id. The description 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 clearly states it 'Report the REAL delayed result of a prior hebbrix_choose_action', specifying the exact verb ('report') and resource ('prior hebbrix_choose_action'). This distinguishes it from siblings like hebbrix_choose_action (which selects actions) and hebbrix_remember (which stores general memories). It precisely communicates the tool's role in 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?

The description gives clear context: use after a hebbrix_choose_action, with explicit options for early vs. final reporting ('Set final=false for an early signal and report the settled value later') and correction ('Set correction=true to replace previously learned evidence'). It also mentions a prerequisite for custom metrics (must be defined via REST API). While it doesn't name alternative tools, it clearly frames this as the outcome-reporting tool, making when-to-use unambiguous.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds significant behavioral detail: zero-relevance padding rows are always dropped, automatic verification with calibrated retrieval is disclosed, and the meaning of the min_score parameter is explained ('absolute relevance floor'). This goes well beyond what annotations provide.

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

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

Three well-structured paragraphs flow from top-level purpose to behavior to parameters, then output format. Every sentence adds value with the most critical usage directive positioned first after the summary. Zero wasted words.

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

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

The description fully compensates for the 0% schema coverage by documenting the key parameter (min_score), return format, edge behavior (zero-relevance row dropping, noise suppression), and use case. With annotations confirming read-only, non-destructive behavior and an output schema present, the description fills all remaining gaps.

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 does explain min_score ('Raise min_score (0.0-1.0) to request an explicit absolute relevance floor'), but doesn't elaborate on query, limit, or collection_id. The return format is documented, and the 0% coverage means the description carries the full burden, which it mostly does for the most important 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?

The description uses specific verb+resource ('Semantic search over memories') and clearly differentiates from siblings by stating when to use it: BEFORE answering questions depending on prior context, decisions, or preferences. This strongly distinguishes it from sibling tools like hebbrix_history, hebbrix_get, and hebbrix_list.

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

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

The description explicitly says 'Always call this BEFORE answering questions that depend on prior context, decisions, or user preferences.' This is a clear when-to-use directive. It also contrasts with alternatives by noting this is the primary semantic search entry point among many siblings.

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

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

Beyond the readOnly and idempotent annotations, the description discloses non-obvious behavior: entities are enriched asynchronously after a write, not covered by hebbrix_remember's wait_for_index, and may appear within ~30s. This explains why an empty result right after a write is expected, adding valuable context beyond the schema.

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 compact and well-structured: a clear purpose sentence with optional filter, followed by a relevant note about asynchronous behavior. Every sentence adds value and there is no redundant or filler content.

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 purpose, usage, and the key behavioral caveat, while the output schema likely handles return-value details and annotations cover safety. However, collection_id remains unexplained, which is a minor gap for a tool that otherwise feels 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?

The schema has 0% description coverage for its parameters. The description clarifies only entity_type (as an optional filter with examples) but does not explain collection_id or limit. Since the description fails to compensate for the low schema coverage, especially for collection_id, the parameter semantics are insufficiently defined.

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

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

The description clearly identifies the tool's action ('List') and resource ('entities in the knowledge graph'), with concrete examples of entity types (people, organizations, tools, places). It effectively distinguishes this tool from siblings like hebbrix_search or hebbrix_graph_query by focusing on entity listing for 'who/what do I know about' questions.

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 explicitly gives usage context with 'Use for "who/what do I know about" questions' and provides a crucial caveat about asynchronous enrichment after writes. It does not name alternative tools or explicitly say when not to use it, but the guidance is clear enough for an agent to decide.

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 indicate destructiveHint=true and readOnlyHint=false, so mutation is disclosed. The description adds meaningful behavioral context: it preserves version history and may perform an indexing wait. It does not fully describe side effects of updating importance/content, but the description goes beyond annotation basics.

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 compact and front-loaded with the core purpose before diving into indexing behavior. The wait_for_index guidance is a bit dense but earns its place as it prevents repeated update calls.

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 the core purpose, the alternative tool relationship, the indexing wait behavior, and the fallback polling method. Given the output schema exists and annotations describe destructiveness, this is complete enough for an agent to call the tool 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?

The input schema has no descriptions for parameters, and schema description coverage is 0%, so the description carries the burden. It explains content meaning implicitly (new content), and explicitly explains wait_for_index semantics. It does not explain memory_id or importance, but memory_id is self-evident and importance is reasonably inferable as a numeric priority.

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

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

The description clearly states the tool updates a memory in place while keeping version history, and explicitly distinguishes it from remembering a contradicting copy. Among siblings like hebbrix_remember and hebbrix_forget, this distinguishes the corrective update 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?

It explicitly says when to use it: to CORRECT a stored fact instead of remembering a contradicting copy. It also provides guidance on the wait_for_index behavior and tells the agent to poll hebbrix_get(id) if searchable is false, which is actionable usage guidance.

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

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

The annotations already mark this as destructive, so the description's added context about tenant ownership, mutability of fields, and immutable scope is valuable. It clearly tells the agent that not everything on the procedure can be changed, which is a meaningful behavioral trait beyond the structured fields.

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

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

The description is a single focused sentence with no filler. The core operation, resource type, and the key immutability constraint are all front-loaded and easy for an agent to parse quickly.

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

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

For a tool with eight parameters, zero schema description coverage, and a large sibling set, this description is too sparse. It provides no guidance on parameter semantics, no usage differentiation, and no hints about how the optional fields interact. The output schema helps, but the agent still lacks enough context to call this tool confidently.

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 should compensate for the eight parameters, but it only says 'mutable fields' generically. It does not explain procedure_id as the required scope identifier, nor the meaning of action, condition, or parameters objects, leaving the agent with only parameter names and types.

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

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

The description states a specific verb ('Update'), a specific resource ('tenant-owned procedure'), and a clear scope ('mutable fields' vs immutable scope). It also distinguishes itself from related siblings like create/delete/execute by focusing on updating only mutable fields of an existing procedure.

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

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

The description implies the tool is for updating existing tenant-owned procedures and that the procedure scope cannot be changed. However, it does not explicitly state when to choose this over hebbrix_update, hebbrix_create_procedure, or hebbrix_execute_procedure, nor does it specify any exclusions or prerequisites.

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