Calculate age in years, months, days, and total days from a Jalali birth date; defaults to today when no as-of date is given.
Age (years, months, days, total days) from a Jalali birth date. asOf defaults to today.
| Name | Required | Description | Default |
|---|---|---|---|
| asOf | No | Jalali date as {year,month,day} or text like '1405/07/24' | |
| birth | Yes | Jalali date as {year,month,day} or text like '1405/07/24' |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the return shape (years, months, days, total days) and the default value of asOf, which is real behavioral context. It does not say what happens with invalid Jalali input, a future birth date, or whether any permission/rate constraints apply, leaving edge behavior unspecified.
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 short sentences, zero filler, with the core purpose front-loaded and the optional-parameter default appended where it belongs. Every clause carries 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?
There is no output schema, but the description enumerates the returned fields, which covers the main return-value need. For a two-parameter calculator with 100% schema coverage this is nearly sufficient; only edge-case behavior (invalid dates, future birth dates, negative results) is missing.
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 100%, so the baseline is 3, and the description genuinely adds meaning by documenting that asOf defaults to today — a default the schema itself does not declare. It does not add further syntax detail beyond the schema's '{year,month,day} or text' examples, so it earns a modest bump above baseline rather than a top score.
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?
States a specific verb (compute age) and resource (Jalali birth date), and enumerates the output units (years, months, days, total days), so the agent knows exactly what it gets back. It is distinguishable from the broader date arithmetic siblings, but it never names jalali_diff, which could also be used for age-like math, 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 note that 'asOf defaults to today' implies the intended usage (age as of now, or as of an arbitrary date), which is useful. However, there is no explicit when-to-use vs alternatives guidance and no mention of exclusions or error conditions (e.g. a birth date in the future, or an invalid Jalali date).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.