log_session

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly mentions that nodes start PENDING and are invisible to retrieve_context until admin approval, which is a deliberate review gate. It also explains how agent_id/task_id can trigger auto-approval. It doesn't mention error handling or idempotency, but the critical behavior is covered.

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 longer than necessary but every sentence provides value. It front-loads the purpose, then explains the approval mechanism, then parameter roles. The structure is logical and the length is justified given the tool's 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?

The description is quite complete for a log tool with 6 parameters and an approval flow. It covers the PENDING state, auto-approve rules, and parameter purposes. It doesn't describe the return value, but for a logging action without an output schema, that is acceptable. Minor gaps like error scenarios or idempotency exist but are not critical.

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 explain each parameter. It does so thoroughly: title as a searchable anchor, body as content, tags/links as retrieval aids, and agent_id/task_id for auto-approval and scoping. This fully compensates for the lack of 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 tool's purpose: 'Log what happened this session as a memory node for the team to reuse.' It specifies the verb (log), the resource (session memory node), and the intent (reuse). It also distinguishes from siblings by implying that retrieve_context is for retrieval, not storage.

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 when-to-use guidance: 'Call this once at the end of a session that learned something worth keeping.' It also explains the approval gate and references related tools like retrieve_context and create_auto_approve_rule. However, it doesn't explicitly state 'use retrieve_context for retrieval' but the contrast is clear enough.

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