list_opportunity_entries

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

Annotations already mark the operation as read-only and non-destructive, so the description adds useful behavioral context beyond that: it discloses the sort order, the per-entry structure, and the allowed type values. It does not cover pagination or embed behavior, but for a read-only list operation this is sufficient extra transparency.

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 sentences deliver the core purpose, return format, ordering, and routing guidance with no filler. The most important scope information is front-loaded, and each sentence earns its place.

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 tool with no output schema, the description usefully summarizes the response contents (type, content, timestamps) and ordering. It could go further by mentioning pagination defaults or embed options, but the essential calling context—what resource, what filters, what result shape—is present.

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 only 25%, and the description does not compensate by explaining page, perPage, or opportunityId semantics. It mentions 'for an opportunity' but not the required identifier format, pagination controls, or how embed affects results. The embed parameter has a schema description, but the other three params are effectively undocumented.

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: lists timeline entries for an opportunity, enumerates the entry types (notes, emails, task records), and notes the newest-first ordering. It also explicitly distinguishes itself from list_party_entries and list_project_entries, making the tool's purpose unmistakable.

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 clear guidance on when to use this tool ('what's the latest on deal X?') and explicitly points to alternatives for party and project timelines. It does not mention the broader list_entries sibling or other edge cases, but the given use case and exclusions are strong enough for an agent to route correctly.

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