get_settlement_status

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns a full audit record with listed fields, confirming it is a read-only lookup. However, it does not explicitly state that it is idempotent, non-destructive, or whether authentication is required. The lack of behavioral detail (e.g., error handling) is a gap, but the return list adds some 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?

The description is two sentences long, front-loaded with the core purpose, and immediately follows with a clear list of return fields. Every word adds value, and there is no redundant or superfluous information.

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 tool has one parameter and an output schema (not provided). The description covers the key aspects: purpose, parameter origin, and return fields. However, it lacks context on failure modes (e.g., what if settlement ID is invalid or settlement not found), rate limits, or any prerequisites. Given the simplicity, the missing details are not critical but prevent a higher score.

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?

The schema already provides full coverage (100%) for the single parameter with a description matching the tool description. The tool description only restates the parameter need ('by settlement ID') without adding new meaning or constraints beyond what is in the schema, so the value is baseline.

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 clearly states the verb 'Look up' and the resource 'a previous DPX settlement', and lists the specific return fields. This distinguishes it from sibling tools like 'settle' (creates) and other get tools by emphasizing it retrieves a full audit record for a specific settled transaction.

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 that the tool should be used after a settlement is created, as it references 'Settlement ID from the settle tool'. However, it does not explicitly state when to use this tool versus alternatives (e.g., getting a quote or ESG score), nor does it mention any prerequisites or conditions for use.

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