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

Annotations already signal readOnly, idempotent, and non-destructive behavior, and the description adds meaningful context: rates are sourced live from the database rather than approximated. It also discloses that without marriage_year the cash portion stays nominal and must not be labeled 'ارزش روز', which is important behavioral detail not present in the schema.

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 three sentences with no filler. The purpose is front-loaded, the data-source warning is explicit, and the conditional user input requirement is stated clearly. Every 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 calculator with no required parameters and no output schema, the description explains the inputs, the external data dependency, and the user question the agent should ask. It could explicitly state the return format or currency, but the 'Toman' parameter and the phrase 'present-day value' make the output reasonably inferable.

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 100%, so the baseline is 3. The description adds value by clarifying the conditional role of marriage_year: it is required whenever there is a cash portion, and omitting it leaves the cash unadjusted. This goes beyond the schema's simple 'needed to adjust' phrasing.

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 states a specific verb and resource: calculate the present-day value of مهریه from coin count at live market rate plus cash adjusted by the Central Bank index. The term 'مهریه' and the cited legal provision clearly distinguish this from the sibling calculators such as calculate_delay_penalty and calculate_diyeh.

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 gives clear procedural guidance: never guess coin prices or the adjustment index because the tool reads them from the database, and ask for marriage_year when a cash portion exists. It does not explicitly list when-not-to-use alternatives, but the calculation context is specific enough that an agent can infer when this tool applies.

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