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.