Recent Opportunity Changes

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses keyset-based pagination, the performance characteristic ('depth doesn't degrade performance'), and the sync-cursor protocol: sync.server_time is returned and should be passed as since on the next call. It also caps the page size, adding real behavioral context.

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?

Every sentence contributes either to usage, parameter rules, or the sync protocol. Bullet points make the parameter semantics scannable, and the instructions are front-loaded with the core purpose before details.

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 sync loop is fully specified: since, limit, response fields, and the save-and-pass server_time instruction. The only notable gap is the unaddressed offset parameter, which could confuse an agent given the 'keyset-based' claim; a brief clarification on whether offset is supported or unnecessary would make it complete.

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?

With 0% schema_description_coverage, the description compensates well for since (ISO 8601 format plus concrete example) and limit (max 1000 per page), both absent from the schema. However, offset is left undocumented even though it appears in the schema, so parameter semantics are not fully complete.

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 opens with 'List opportunities added or updated since a timestamp', providing a specific verb, resource, and time-scoped filter. This clearly distinguishes it from sibling search tools like search_opportunities, which retrieve arbitrary result sets rather than incremental changes.

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?

'Use this for incremental sync instead of paginating through search results' explicitly states when to use the tool and what alternative pattern it replaces. The keyset-based note reinforces why this tool is appropriate for deep incremental walks.

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