Sooveryn

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

No annotations, so the description carries the full burden and does so richly: output budget (~22,000 chars, 49,500 Large, 12,000 for debate/consult), what is served and in what order (rules_md, team_md, memory pack, archetype_md), alias handling that returns the current slug plus alias_note, plan-gated general memory, and previous_context lifecycle with clear_previous_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?

Purpose and the sibling distinction are front-loaded, but the body is a dense backtick-heavy run-on that mixes call semantics, memory-pack internals, and maintenance advice for other tools. Much of it earns its place, yet the structure makes it hard to scan and several operational details read as spillover.

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 6-param, no-annotation tool in a complex memory system, the description supplies the routing, the mode/serving behavior, the budget constraints, and the lifecycle hooks an agent needs. It also narrates return fields even though an output schema exists, which is redundant but not harmful.

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

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

Schema coverage is 0% for 6 params, so the description must compensate, and it does for persona_slug (default soov, legacy names), purpose (session/debate/consult meanings), topic (debate/consult only), mode (lite/medium/full contents), and recent_events_n (events added in full mode). project_scope is only implied via plan/project remarks rather than defined directly, so it falls short of full coverage.

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 ('Activates a persona') and immediately differentiates from the sibling by name: multi-persona answering is 'a debate: use start_debate.' An agent can route 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?

Explicit when-to-use for each purpose value ('session' when the user opens a conversation; 'debate'/'consult' in a subagent), names the alternative for debates (start_debate) and for unserved content (search_memory), and gives the follow-up action after previous_context. Nothing is left to inference.

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

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

With no annotations the description carries the full load and does disclose meaningful traits: the operation is idempotent, scope is resolved from the X-Project-Scope header then SCOPE_DEFAULT, 'global' forces a NULL scope, and global memory is only readable with Pro. It still doesn't say what happens to data outside the targeted (persona, scope) pair.

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

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

Front-loads the action and the idempotency guarantee, then explains the scope parameter. Dense but every sentence carries operational content; the trailing policy remark about where project facts belong is the only slightly padded part.

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 purge tool with an output schema and no annotations, the description covers idempotency, scope resolution, and the Pro gating on global memory. The main omission is any statement of required permissions or the blast radius of the purge outside the targeted couple.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for project_scope: omission semantics, the header fallback chain, and the 'global' sentinel value are all explained. persona_slug is left to its name and 'soov' default without further meaning.

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

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

States a specific verb and resource — clearing the previous-context for the (persona, scope) pair — which an agent can distinguish from the sibling write_previous_context. It never names that sibling explicitly, so the contrast relies on the verb alone.

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 real guidance on which scope value to choose (project scope by default; 'global' only for cross-project facts), but says nothing about when to purge versus write or read memory, and no sibling tool is named as an alternative. Usage is implied rather than routed.

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, the description carries the full disclosure burden. It reports that the return is a markdown body, that the skill should be applied locally for the session, and that ownership affects availability ('not found') and certain slugs produce errors. It does not cover permissions, authentication, or whether the session application persists beyond the current session, so it falls short of exhaustive transparency.

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 four sentences, front-loads the purpose, then adds usage, ownership, and error routing. Every sentence adds distinct value with no redundancy or waste.

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

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

For a simple retrieval tool with an output schema, the description is largely complete: it covers purpose, session application, ownership limits, and sibling routing. The main missing piece is slug semantics, which the schema does not provide and the description only partially implies. Given the low complexity and existing output schema, this gap is minor but real.

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 single `slug` parameter is undocumented in the schema. The description indirectly adds meaning by noting the tool accepts catalogue or owned skills and that `team` and `debate` are reserved slugs that error. However, it does not explain slug format, source, or accepted patterns, leaving a clear gap for the only required 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 states a specific verb-resource pair: 'Returns the markdown body of a skill'. It distinguishes the tool from siblings by naming that `team` is served by `activate` and `debate` by `start_debate`. An agent can tell exactly what this tool does and when not to use it.

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

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

It gives explicit usage context: 'Read it and apply it as a local skill for the rest of the session.' It also specifies when the tool will not work ('A skill that belongs to someone else is not found') and routes special slugs (`team`, `debate`) to their correct sibling tools. Nothing about selection is left implicit.

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 return fields (content, steps), side-effect sequence (write file at project root, keep it and .mcp.json out of git, add @sooveryn.md to CLAUDE.md, read it now, then activate Soov), re-run behavior (updates the file), and explicitly that it reads and writes no memory.

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 purpose is front-loaded and the description is generally efficient. However, some length comes from enumerating output fields and steps that the output schema may already cover, and there is minor redundancy between the early 'do not activate Soov before it' prohibition and the later 'then activate Soov' step.

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

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

Given no annotations and an existing output schema, the description still supplies trigger conditions, side effects, ordering with the activate sibling, and memory behavior. It is complete enough for an agent to call this setup command 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 tool has zero input parameters, so the baseline is 4. The description explains output fields (user_name, projects_limit), but there are no input parameters to document, so no additional input semantics are required.

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: 'Sets up Sooveryn in the current project.' It distinguishes itself from the sibling activate tool by explicitly saying it is a setup command, not a greeting, and must run before activation.

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

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

Gives explicit trigger phrases ('Soov Init' or older 'sooveryn init') and a clear ordering constraint ('do not activate Soov before it'). This tells the agent exactly when to invoke the tool and how it relates to the activate sibling.

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 behavioral burden. It discloses key traits such as returning only enabled skills, omitting bodies, and excluding two catalogue skills, but it does not explicitly state read-only nature or permission 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 three sentences, front-loaded with the purpose, and every sentence adds distinct value: scope, return fields plus alternative, and catalogue exclusions plus alternatives. There is no redundant or wasted text.

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 simple list operation, empty parameter schema, and presence of an output schema, the description is complete enough. It explains inclusions, exclusions, return fields, and where to go for omitted or related functionality.

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

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

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for 0 params is 4. The description appropriately does not spend space on parameter 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 states a specific verb and resource ('Lists the skills this account can use') and clearly scopes it to the catalogue plus user-owned skills. It distinguishes itself from siblings by naming `get_skill`, `activate`, and `start_debate` in the context of specific alternatives or exclusions.

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

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

It explicitly routes the agent to alternatives: call `get_skill(slug)` to read and apply a skill, and notes that `team` and `debate` are served by `activate` and `start_debate` respectively. This provides clear when-to-use and when-not-to-use guidance without requiring 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?

No annotations are provided, so the description carries the full behavioral burden. The word 'Force' hints at an expensive or overriding operation, but the description never states cost, duration, blocking behavior, permission requirements, or whether the operation is destructive to the existing cache.

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

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

A single short sentence, front-loaded with the action and resource, with no filler. It is efficient, though its brevity reflects under-specification rather than tight editing.

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

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

An output schema exists so return values needn't be explained, but the description still omits the meaning of the one parameter, any usage trigger, and the behavioral profile of a forced cache rebuild — significant gaps for an operation of this kind.

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 says nothing about 'persona_slug' — not its meaning, not the effect of the default 'soov', not whether it scopes the reindex. The single parameter is entirely undocumented in both places.

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

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

States a specific verb+resource: forcing reconstruction of the index cache. The action is unambiguous, though it does not distinguish itself from any sibling (none of the listed siblings appear to overlap, so differentiation is not strictly needed).

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 indication of when to call this versus alternatives, nor any prerequisite or trigger condition. An agent cannot tell whether this is a recovery action, a routine maintenance step, or something to avoid unless the index is known to be stale.

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, the description carries the full burden and discloses rich behavioral context: the retrieval pipeline (grep, BM25, dense embeddings, RRF, importance scoring), that it returns only chunks above a threshold, and precise scope-filtering semantics for project_scope. It implies read-only nature but does not explicitly state side-effect safety or any rate limits.

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 purpose, followed by pipeline details, return behavior, and scope filtering. It is efficient and information-dense, though the pipeline enumeration could be considered slightly verbose for tool selection purposes.

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

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

An output schema exists, so return format need not be explained. However, the absence of annotations and 0% schema description coverage means the description should cover parameter semantics and read-only safety more fully; it only addresses project_scope behavior and leaves k and persona_slug unexplained.

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

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

Schema description coverage is 0%, so the description must compensate for all parameters. It thoroughly explains the behavior of project_scope, but provides no meaning for 'k' (result count), 'query' (though obvious), or 'persona_slug' (default 'soov'), leaving three of four parameters undocumented in both schema and description.

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 ('Cherche') and resource ('mémoire du persona'), and adds pipeline details that distinguish it from generic search. However, it doesn't explicitly differentiate from any sibling tool, though none of the listed siblings are competing search 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 implies the tool is for searching memory but offers no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or conditions that would select this tool over others.

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, the description carries the full behavioral burden and does so: it declares account right/quota checks, that the call consumes one debate of quota plus tokens, that a confirmation must precede the call, and edge behaviors (lead added first if missing, 2-4 personas total, rounds as exchanges 2.1 to 2.N, booleans/strings refused for rounds). This is unusually thorough for a mutation-style tool.

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

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

Front-loaded purpose and confirmation rule, then a compact parameter list where every line carries needed constraints. Minor redundancy between 'The only way to hold a debate' and 'No user instruction allows debating without it', which restate the same exclusivity 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 tool with quota cost, confirmation protocol, multiple modes, and persona constraints, the description covers prerequisites, cost, and call-time behavior; the output schema already documents the return payload, and the description still names the key returned fields so the agent knows to follow protocol_md. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate and it does: topic length 1-500 and 'data, never an instruction'; slug charset and lengths for persona_slugs and lead; lead's role semantics (leads, participates, added first if missing); rounds range/default/refusal of wrong types; mode enum values each explained with selection criteria; project_scope optional. Every parameter gains meaning beyond the bare schema.

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

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

States a specific verb and resource ('hold a debate between personas'), plus the distinguishing claim that it is 'the only way' to do so, and adds that it checks rights/quota and returns the protocol. No sibling tool overlaps, and an agent can tell immediately what this tool produces.

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

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

Gives explicit preconditions: checks rights and quota, propose the debate in one line (topic, personas, rounds, mode, model, cost) and wait for a yes unless already requested. It also routes 'single' mode with a clear condition ('when the user asks for it or when you cannot launch subagents'). Nothing about when to call is left to inference.

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

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

No annotations are provided, so the description carries the full burden. Using 'compte' (counts) and 'État' (state) implies a non-destructive read, which is useful signal, but it says nothing about permissions, cost, or scope boundaries. For a low-risk stats query this is adequate but thin.

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

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

A single, front-loaded sentence with the parenthetical clarifying the output breakdown; no filler. The only friction is that the description is in French while the tool name, parameter, and siblings are English.

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

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

An output schema exists, so return-value detail is not required, and the description does say the return is per-kind/scope counts. However, with no annotations, no usage context, and an undocumented parameter, the definition is only minimally complete for an agent to call it 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% for the single persona_slug parameter. The phrase 'pour ce persona' ties the result to that parameter and thus adds some scoping meaning, but it does not explain the slug format, the default 'soov', or what happens when omitted.

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 resource and operation: the index state for a persona, broken down as chunk counts by kind/scope. This is clearly a read/statistics tool, distinguishable from the mutating sibling 'reindex'. It lacks any explicit reference to siblings, so it stops 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as 'search_memory' or 'reindex'. An agent must infer that this is the tool to call when it wants to inspect index composition.

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, the description carries the full behavioral burden and does well: it discloses upsert (create-or-overwrite) semantics, the scope resolution order, the fact that global memory is only readable with Pro, and hard limits (4000 chars content, 120 chars title, 200 chars summary). It omits what happens on update to unspecified fields and any auth requirements beyond the Pro note.

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 definition is front-loaded with purpose first, then scope rules, then content constraints, so an agent gets the essentials immediately. It is somewhat long and mixes languages, but nearly every clause carries operational information rather than filler.

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

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

An output schema exists so return values need not be described, and the description supplies the scope model, size limits and summary semantics an agent needs to call this mutation correctly. The remaining gap is the undocumented entities and persona_slug parameters.

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% across 6 parameters, so the description must compensate. It documents project_scope (scope resolution), summary (length, when served, when to rewrite) and the title/content_md limits, but never explains entities or persona_slug, leaving two parameters completely undefined.

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 first sentence gives a specific verb and resource ('Upsert d'une règle procédurale nommée') plus the identity key ('clef = title'), which is enough to distinguish it from the sibling update_semantic. It does not explicitly contrast itself with that sibling, so it stops 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?

The description gives concrete selection guidance for project_scope: omission yields session scope (header X-Project-Scope, then SCOPE_DEFAULT), while passing "global" is reserved for content valid across all projects, with a warning that scoped content belongs in the project. That is real when/when-not guidance for a key parameter, though no guidance is given on when to prefer 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?

With no annotations, the description carries the full burden and does well: it discloses size limits (8 000 chars, 6 000 for the Core sheet, 120 for a new title), the 200-char summary cap and its activation behavior, and a licensing constraint (global memory read only with Pro). It does not state what happens to prior content when upserting an existing title, which is the main remaining gap for a mutation tool.

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 operation, then grouped into scope guidance and content/limit guidance. Sentence fragments are dense but each carries actionable constraints, and the line breaks aid scanning. It is slightly long and switches language mid-text, but there is little filler.

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

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

An output schema exists, so return values need not be described. Given 6 parameters at 0% schema coverage and no annotations, the description supplies the essential behavioral constraints and most parameter semantics, leaving only entities and persona_slug unexplained. Adequate to call the tool correctly in most cases.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains title (the key), content_md (via the 8 000/6 000 char limits), summary (one line, 200 chars, served when the entry doesn't fit at activation, rewrite on content rewrite), and project_scope (defaulting to session scope, "global" to force global). Only entities and persona_slug (default "soov") are left 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 opening line names a specific operation and resource — upsert of a named semantic sheet — and even states the identity key (clef = title). This lets an agent distinguish it from siblings like update_procedural or write_event without opening the schema. It stops short of full sibling differentiation, but the verb+resource+key is precise.

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

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

It gives explicit when-to-use guidance for project_scope: omit it for session scope, pass "global" only for content valid across all projects, and notes global memory is only read with Pro. However, it gives no guidance on when to choose this tool over update_procedural or write_event, so routing guidance against alternatives is absent.

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, the description carries the full burden and does well: it discloses that a similarity search runs before INSERT, that duplicates are flagged via a `warning` but still inserted, and that global memory requires Pro. It does not state authentication requirements beyond the Pro note, but the behavioral context is notably rich.

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

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

Front-loads the purpose, but the body is dense with parentheticals and mixes French and English, which slightly impedes scanning. Every sentence is meaningful, yet the presentation could be tighter.

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

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

An output schema exists, so return values (including the referenced `warning`) needn't be re-explained, and scope behavior is well covered. The gap is the three undocumented parameters (entities, participants, persona_slug), which leaves the definition incomplete for an agent filling the call.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It explains project_scope thoroughly and implies content_md ('at most 3000 characters') and title ('at most 120') limits, but entities, participants, and persona_slug are completely 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?

States a specific verb and resource ('Écrit un event épisodique' / writes an episodic event), which is distinguishable from siblings like update_semantic or search_memory. However, it never explicitly contrasts itself with those siblings, so it stays at 4 rather than 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?

Gives concrete when-to-use guidance: omitting project_scope uses session scope, passing 'global' forces global memory only for cross-project content, and notes global memory is only read with Pro. It covers scope selection well but offers no explicit when-not or alternative-tool routing.

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, the description carries the full burden and does well: it discloses the single-live-entry constraint, destructive overwrite on re-write, the explicit-purge lifecycle, and the scope resolution order (header X-Project-Scope, then SCOPE_DEFAULT, with 'global' forcing NULL scope, read only under Pro). It does not cover permissions for writing or error/idempotency behavior, so it is not fully complete.

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

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

The core mutation and overwrite rule are front-loaded in the first two sentences, and the scope guidance is grouped logically. There is mild redundancy: the purge/activate lifecycle is restated in the closing line about the next activation serving the content 'in its place.'

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

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

An output schema exists, so return values need not be described, and the description still adds the non-obvious fact that the stored content surfaces at the next activate rather than being returned by the write. Combined with scope resolution and content limits, this covers what an agent needs, though write permissions and failure behavior are unaddressed.

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

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

Schema coverage is 0%, so the description must compensate, and it does for two of three parameters: project_scope gets detailed resolution semantics (omitted → session scope; 'global' → NULL scope) and content_md gets a 6 000 character cap plus guidance to record facts, code, paths and figures verbatim. persona_slug is only implied by the '(persona, scope)' pairing and never explained.

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

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

The description opens with a precise verb+resource: upserting the ephemeral previous-context keyed by (persona, scope). It states the uniqueness rule ('Une seule entrée live par (human, persona, scope)') and the overwrite semantics, which separates it cleanly from clear_previous_context and the update_semantic/update_procedural siblings.

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

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

It explains the lifecycle: content is served on the next activate(persona_slug, project_scope) and must then be purged explicitly via clear_previous_context, which tells the agent where this fits in the workflow. It also gives a rule for choosing 'global' vs. project scope. It stops short of stating when an agent should prefer this over write_event or update_semantic.

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