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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real value with the consent requirement and the clarification of what "Trades" means, but it says nothing about the return shape or the field-directory navigation that the path parameter implies.

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?

Three short sentences with the resource scope front-loaded first, followed by the consent prerequisite and then the negative constraints. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 read tool with no output schema and four parameters, the description covers scope, consent and semantic disambiguation well. However, it omits how pagination (limit/offset) behaves and how the path drill-down works against the returned field directory, both of which an agent needs to use the tool 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?

Schema coverage is only 25%: path is documented in the schema while limit, offset and section carry no description. The description adds no parameter guidance at all, and critically never explains the two-step pattern implied by path ("Object keys or array indices from the returned field directory"), which an agent must understand to traverse results.

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?

"Read your saved Rules, Notes and Trades from Playbook, or your saved Security Snapshot" gives a specific verb plus an enumerated set of resources, and the clarification that Trades are written strategies rather than brokerage executions implicitly steers the agent away from read_portfolio. No sibling is named outright, so the differentiation is inferred rather than stated.

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 sets a clear precondition ("Requires explicit Workspace consent") and an explicit negative scope ("Never edits content or generates/emails reports"), which routes report generation to read_report. It stops short of naming which sibling to call instead for portfolio or archive data, leaving some inference to the agent.

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