Api contracts retrieve

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds one genuinely new behavioral fact: unauthorized related fields are masked in the response. It stops short of saying masking depends on the caller's role or which fields are affected.

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?

A single short sentence with no filler, front-loaded and readable. It is efficient, though the brevity reflects under-specification rather than disciplined editing.

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?

This is a simple read-by-id tool whose annotations cover safety and which has no output schema, but the description still omits the resource identity, the id format, and what masking means for downstream use. Throwaway sub-clauses like 'unauthorized related fields' are left undefined.

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% and the sole required parameter id has no description at all, so the description carried the full burden and supplied nothing — not even the identifier format (UUID vs integer) or whether it is the contract id. The one useful detail an agent needs is missing.

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?

"Return a single object" restates the name's retrieve verb without naming the resource (a contract) or the identifying key. It never says this fetches one contract record by id, so an agent must infer the subject from the tool name and the crowded sibling list.

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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternatives such as contracts_list, contracts_object_retrieve, or contracts_cascade_info_retrieve. The agent gets no help choosing between this and the several near-identical retrieve siblings.

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