congress_amendment_details

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

Annotations already carry the read-only, idempotent, non-destructive safety profile, so the description only needs to add behavioral context beyond that. It adds that the result includes actions/timeline, a useful return-content signal, but says nothing else about response shape, pagination, or error behavior. This is a modest contribution, not a rich behavioral disclosure.

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?

Two sentences with no filler: the action, the headline return content, and the required parameters are all front-loaded. Every clause earns its place, making this an appropriately sized definition.

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 three-parameter detail lookup the description is minimally adequate: it names the entity and the required identifiers. But with no output schema and many closely related amendment sibling tools, the vague 'detailed information' plus one example ('actions/timeline') leaves the agent to infer the full response contents and when this tool is preferable to congress_amendment_text, congress_amendment_cosponsors, or congress_amendments.

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?

All three parameters have schema descriptions ('Congress number', 'Amendment type', 'Amendment number'), so schema coverage is 100% and the baseline is 3. The description merely repeats the required parameter names and adds no format or semantic nuance; its parenthetical '(hamdt/samdt)' even omits the valid 'suamdt' enum value present in the schema.

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 'Get detailed information about a specific amendment,' a clear verb-resource pairing, and singles out 'actions/timeline' as included content. It is therefore recognizable as the detail variant of the amendment family, but it never names sibling tools such as congress_amendment_text or congress_amendment_cosponsors, so differentiation is implicit rather than explicit.

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 implies the right situation—a known congress, amendment type, and amendment number—by listing the required inputs, and the 'specific amendment' phrasing signals this is not a list/search tool. However, it gives no explicit when-to-use versus alternatives and does not mention that discovery should go through congress_amendments or that text-only needs should use congress_amendment_text.

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