rdstation_get_deal

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It only says 'get', which suggests a non-mutating read, but there is no information about what happens if the deal does not exist, whether authoritative permissions are required, what the response structure looks like, or any other run-time behavior. This is minimal compared to what is expected in a stateless tool in CRM 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?

The description is a single, directly targeted sentence. It front-loads the resource, the singular scope, and the lookup key ('id'). There is no waste, no restatement of properties, and no extra phrasing that dilutes the core message.

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 that this is a one-parameter simple read tool, the description is minimal but enough to communicate the immediate purpose. However, it omits what the return value will be (no output schema), any error-handling hints, and the behavioral expectations. For a basic get, the tool might be adequate, but with no annotations and no output schema, an agent benefits when the description explains more than a throwaway sentence.

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 0%, and the description only says 'by id'. This maps the parameter name 'deal_id' to the intended identifier, but adds essentially no richer semantics – it does not specify the format (e.g., numeric vs. UUID), how it is defined by RD Station, or any related constraints. The explanation adds only minimal value, and the schema alone gives name and type only.

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 uses a specific verb ('Get'), a specific resource ('a single deal from RD Station CRM'), and a clear identifier qualifier ('by id'). It obviously distinguishes from sibling deal tools like rdstation_list_deals, rdstation_create_deal, rdstation_update_deal, rdstation_win_deal, rdstation_lose_deal, and follows the same pattern as rdstation_get_contact and rdstation_get_organization.

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 usage is implied: this is the tool to use when an agent needs one deal and has the deal_id. However, the description does not explicitly say when to use it versus list_deals, nor does it state when not to use it (e.g., when you need all filters). No alternative names are mentioned, so the guidance is existing entirely at the implied level.

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