extract_insights

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

With no annotations provided, the description carries the full behavioral burden. It clearly states 'This tool does NOT write to the database' and explains the two-step workflow. It also describes what it loads (knowledge base context, existing tags) and what it returns (context block + extraction instructions). However, it doesn't explicitly state whether this is a read-only or side-effect operation in annotation terms, though the text implies read-only preparation.

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 with a clear purpose statement, a workflow explanation, a negative constraint, and trigger phrases. It is slightly verbose with some redundancy (e.g., repeating the extraction flow), but every section serves a purpose and is front-loaded with the core action.

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 complexity (two-phase workflow, no annotations, 0% schema coverage), the description is largely complete: it explains purpose, parameters, behavioral constraints, and the follow-up tool. However, it doesn't describe the output schema details (though output schema exists, so that's acceptable) and could clarify error conditions or rate limits. It is sufficient 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 compensate. It documents both parameters: session_text ('Full or partial transcript of the research session') and source_platform ('Platform where session occurred... Leave blank if unknown'). This adds meaningful guidance beyond the bare schema, though it doesn't specify format constraints or examples for session_text.

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 ('Prepare an AI research session for insight extraction') and clarifies the two-phase flow: load context, return instructions, then Claude performs extraction. It explicitly names the sibling tool commit_aiex() as the follow-up step, distinguishing this preparation step from the commit step.

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 trigger phrases ('Extract insights from this session', 'Run AIEX on this conversation'), states when to use commit_aiex() (after user reviews extracted insights), and clarifies that this tool does NOT write to the database. This is comprehensive when-to-use and when-not-to-use guidance.

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