export_project_notes

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description adds meaningful extra context: the feed is incremental, pagination uses continueFrom/hasMore, hasMore false means wait before polling again, and includeRecentChanges may return records sooner but can repeat them. This is valuable behavioral detail beyond what annotations and schema alone provide.

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 three dense, purposeful sentences. The first sentence front-loads what the tool does and why, the second provides the pagination runbook, and the third flags an important edge-case behavior. There is no filler or redundant repetition of schema content.

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 covers the full lifecycle of an incremental feed: starting, continuing, waiting, and the recent-changes duplication caveat. Return shape is left to the output schema, which is reasonable. The main gap is that it never explicitly states that continueFrom from the output should be passed back into the from parameter, so an agent must infer that mapping.

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?

Both parameters are already described in the input schema, so the baseline is 3. The description adds further semantic value by explaining that from is optional and can be omitted to start at the beginning, and by revealing the duplicate-risk tradeoff of includeRecentChanges. It could be stronger by clarifying the continuation token format and the default value of includeRecentChanges.

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 a specific action ('Read'), a specific resource ('the incremental project notes export feed'), and the intended purpose ('for bulk synchronization'). It does not explicitly differentiate from sibling feeds such as export_projects or dispatch_projects_notes_list, so it stops short of a 5.

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 clear operational instructions: start from a date or omit from to begin, continue with continueFrom while hasMore is true, retain the token and wait before polling when hasMore is false, and understand includeRecentChanges can return duplicates. It provides clear context for using this feed, though it does not name alternatives or explicitly state when not to use it.

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