haki

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that consolidation is synchronous in dev so the fact is immediately recallable, that content over MAX_JSON_BYTES is rejected, and that a typed error is returned. This goes beyond the minimal mutation signal and is genuinely useful to an agent.

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: purpose first, then usage, then key behavioral constraints. Every sentence earns its place, and the technical size limit is stated efficiently without padding.

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 two-parameter tool with an output schema present, the description covers purpose, timing, exclusions, storage behavior, and size rejection. The main gap is the unexplained 'kind' parameter, which prevents full completeness but does not undermine the core invocation path.

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, but it only indirectly addresses the 'content' parameter via the size limit and never explains the 'kind' parameter or its default 'agent.observation'. An agent cannot learn from the description what values 'kind' accepts or when to override the default.

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 ('Memorize') and resource ('a durable project fact') and gives concrete examples: technical decision, convention, resolved error. It does not explicitly distinguish itself from sibling tools like haki_context, but the durable-fact framing is specific enough to be actionable.

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 at the END of a task') and clear exclusions ('Never memorize secrets, tokens or ephemeral data'). It does not name alternative sibling tools or describe when to prefer them, so it falls just short of full routing guidance.

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

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

No annotations are provided, so the description carries full behavioral disclosure. It explains the return structure (block with dates, sources, trace_id, status), the meaning of status values, and warns against misinterpreting degraded/failed as 'no known facts'. It also discloses pagination behavior via exclude_ids.

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 and usage instruction, then adds behavioral warnings and pagination details. Every sentence serves a purpose, with no fluff. It is appropriately sized for the complexity.

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 the description explains the status field, pagination, and usage context, the description is complete for an agent to call the tool correctly. It covers what to do on failure and how to interpret results.

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

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

Schema coverage is 0%, so the description must explain parameters. It clearly explains query (implicitly) and exclude_ids (pagination), but budget_tokens is not mentioned. However, budget_tokens is an optional integer with a default, and its purpose is reasonably inferable. The description adds significant value for the key parameters.

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

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

States a specific verb and resource: recalls project memory (decisions, conventions, preferences) relevant to a task. It is clear about the function, though it does not explicitly differentiate from sibling tools like haki_capture or haki_forget. However, the 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?

Explicitly instructs to call BEFORE planning or editing code, and provides detailed guidance on failure handling: call again with the same query and exclude_ids, and warns against rewriting the query. This is strong, actionable usage guidance with clear conditions.

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

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

No annotations are provided, so the description carries the full burden. It discloses that rating='incorrect' moves a fact to disputed and that haki_context will never recall it again, that 'useful'/'irrelevant' only logs feedback without changing the fact, and that the effect is identical via the API path. It also mentions scope resolution via API key or HAKI_MCP_PROJECT_ID. This covers the key behavioral aspects, though it doesn't mention error handling or idempotency.

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

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

The description is dense but not bloated. It front-loads the primary purpose and then details rating effects, target requirements, API equivalence, and scope. Every sentence contributes to understanding how to use the tool correctly. Slightly longer than minimal, but justified given the need to explain the conditional behavior.

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 complexity (4 parameters, no schema descriptions, no annotations), the description is complete enough for an agent to call the tool correctly. It covers what it does, how to select targets, scope resolution, and the API equivalence. An output schema exists, so return values are not required in the description. Missing details like error conditions are minor given the provided context.

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 the meaning of rating ('incorrect', 'useful'/'irrelevant'), fact_id (one precise fact), trace_id (one whole haki_context call), and implies the purpose of comment via 'logs feedback'. It adds meaningful context beyond the bare schema, covering all parameters except comment, which is adequately implied.

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: correcting memory from within a conversation. It specifies the exact behavior for each rating value ('incorrect' moves a fact to disputed, 'useful'/'irrelevant' logs feedback) and distinguishes it from siblings by focusing on feedback/correction rather than capture, recall, or forgetting. This is a specific verb-resource pairing with clear scope.

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 usage conditions: exactly one target required (fact_id for a precise fact, trace_id for a whole haki_context call). It also explains the effect on haki_context (won't recall disputed facts) and mentions equivalence to POST /v1/feedback. It doesn't explicitly contrast with sibling tools like haki_forget, but the mechanism is clear enough for an agent to infer when 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that 'disable' is reversible (facts move to disabled) and 'delete' is a real erasure of facts, embeddings, events, and traces, and that it returns an erasure receipt and counters. This is transparent about the mutation and its consequences, though it does not mention permissions or reversibility of delete (which is implied by 'real erasure').

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, two sentences long, and front-loaded with the core purpose. Every sentence adds value: the first defines the action and the second explains the modes and return value. No 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?

For a tool with a single parameter, the description is highly complete. It explains both modes, their effects, and the return value. The presence of an output schema means the return format doesn't need detailing. It lacks explicit mention of prerequisites (e.g., that a subject must be configured) but this is likely context-specific and not critical for 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?

The schema only provides the parameter 'mode' with a default and no description or enum. The description compensates fully by explaining the two allowed values ('disable' and 'delete') and their distinct semantics. This adds meaning beyond the bare schema, making the parameter clear for the agent.

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 'forget' and the resource 'configured subject's memory in this project', making the purpose unambiguous. It also distinguishes the two modes, which adds specificity. While it doesn't explicitly name sibling tools, the action of forgetting is inherently distinct from capture, context, correct, and inspect, so an agent can easily identify the correct tool.

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 two modes and their effects (disable vs delete), giving some usage guidance on mode selection. However, it does not mention when to use this tool versus its siblings, nor does it provide any exclusions or prerequisites. The context of when to use forgetting is implied but not explicit, so the agent must infer 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?

The description discloses that the tool returns inclusion/exclusion/blocking details with reason codes and provenance proof, implying a read-only inspection. However, it does not mention potential side effects, errors, or authorization requirements.

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 that front-load the core action and then summarize the output. No redundant wording.

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 gives a good overview of the tool's purpose and output, but lacks parameter-level detail and usage context. Given the minimal schema and no annotations, it is adequate but not fully 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 only parameter, trace_id, has no schema description. The tool description mentions a trace but does not explain how to obtain trace_id, its format, or its relationship to a haki_context call.

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 with a specific verb ('Inspect') and object ('the trace of a haki_context call'), and distinguishes it from siblings by focusing on provenance and reason codes.

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 is given about when to use this tool versus the sibling tools (capture, context, correct, forget). It implies use after a haki_context call but does not state alternatives or conditions.

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