essay.projects

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

With no annotations, the description carries the full disclosure burden, and it does state the read-only nature plus per-view behavior, row contents (essay_id/sequence_id), roll_forward_ask, and the sequence_pick handoff. It omits error/permission behavior and says nothing about how conflicting or missing modules are reported, and phrases like 'File work does not own the chat' are opaque.

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 text is a long, run-on block that mixes purpose, output shape, follow-up calls, and user-facing instructions without headings or front-loading. Sentences such as 'Say this list to the user' and 'File work does not own the chat' add noise and slow parsing of the view semantics.

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 no annotations, no output schema, and 0% schema description coverage, the description does useful work by describing row fields and the sequence_pick flow, but it leaves the valid view set ambiguous and omits error handling and what other views exist. For a 2-parameter, multi-mode listing tool it is partially, not fully, sufficient.

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 0% for both parameters, so the description must compensate. It implies view values ('continue', 'roll-forward', 'archive', 'delete', 'unarchive') without an explicit enumeration and never states whether these are the only valid strings, and it only obliquely explains module ('view roll-forward with module names one module'), so an agent cannot reliably construct valid arguments from it.

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 says the tool is read-only and that 'view continue lists every active module', which identifies a verb and resource, but the overall purpose is fragmented across four differently-behaving views (continue, roll-forward, archive/delete/unarchive). It never states in one place that this is a multi-mode module/project listing tool, and the archive/delete/unarchive wording risks being confused with the sibling tools essay.project.archive and essay.project.delete.

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 concrete procedural routing: after 'view roll-forward' sets sequence_pick and the user picks a parent, 'Then call essay.sequence.new with that parent', and it tells the agent to surface the list to the user. It does not, however, say when to use this tool rather than the sibling essay.project.* mutation tools, nor any exclusions.

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