code_activity

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the 'empty unless a code folder is being watched (automatic-capture.json, code_workspaces)' caveat is a non-obvious precondition an agent must know to interpret empty results correctly. Return format is left to the output schema.

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 core purpose, then follows with examples and a caveat. Three sentences with little waste. Minor redundancy between the filter list and the example questions, but overall tight and well-ordered.

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 explanation is unnecessary. The description supplies the essential usage framing and the empty-results precondition, making it largely complete for a read-only query tool. The only shortfall is the undocumented limit/max_diff_chars 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 description coverage is 0%, so the description carries the param burden. It compensates well for six of eight params by naming the filter concepts (project, file, symbol, kind) and explicitly calling out happened_from/happened_to with ISO format. However, limit and max_diff_chars are never mentioned, leaving two parameters unexplained.

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: 'Code changes the capture service recorded, with diff excerpts,' making clear it returns recorded code changes rather than memory items. This cleanly distinguishes it from every sibling (brain_remember, brain_recall, etc.), all of which are memory tools. An agent can identify its domain without opening the 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?

Provides concrete example questions ('what did I change in auth.py last week?', 'when did the parser change?') that map directly to use cases, plus a critical precondition: results are empty unless a code folder is being watched. It doesn't explicitly name an alternative sibling, but the sibling set is a different domain, so routing guidance is effectively implicit.

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