Capital increases, listings and market transfers

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add what structured fields cannot: that capital increase amounts are raw as displayed with units unstated (probably millions of rial) and that windows are short Jalali "from to" strings while other dates are Jalali. Those are exactly the caveats that prevent an agent from misreading the output.

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?

Front-loads purpose, then usage examples, then data caveats, then next-step routing — a sensible order with little waste. The line breaks fragment the prose slightly and the caveat sentence is dense, but every sentence 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?

With no output schema, the description should convey return shape; it implies rows of symbols plus amounts/windows and documents the date and unit quirks, which is the main risk. It does not state the fields present per row or default ordering, leaving a modest gap for a list tool.

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% and the enum values are already documented in the schema itself, so the description rightly does not repeat them. It adds no parameter-level detail beyond what the schema provides (no note on limit/ordering behavior or symbol_contains matching rules), so the baseline 3 applies.

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 and resource ("List corporate actions on Fara Bourse") and immediately enumerates the three/four covered categories, which map exactly to the enum values in the schema. An agent can distinguish this from ifb_ipos or ifb_underwritings without opening the schema.

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?

Gives three concrete user-question framings ("which companies are raising capital and when is the rights window", "which symbols changed board recently", "what listed here lately") that map to actual invocation, plus an explicit follow-up chain (symbol -> ifb_search -> ifb_instrument/ifb_quote). It stops short of naming exclusions, e.g. that detailed IPO mechanics belong to ifb_ipos rather than this tool.

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