get_quote

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

With no annotations, the description carries the full burden of behavioral disclosure. It goes beyond the obvious by revealing that results are 'stamped with freshness: market_open + staleness_seconds,' which tells the agent that quotes may be slightly stale and carry a freshness marker. This is meaningful non-obvious behavior, though it could still mention rate limits, error behavior, or whether it is strictly read-only.

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 short sentences with no fluff. The core purpose is front-loaded, and the freshness detail is concise and relevant. Every word 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 single-parameter tool this is adequate: the agent knows what it gives and that freshness is included. However, without an output schema, the agent is left wondering what fields the quote actually returns, how staleness_seconds is represented, and how to obtain an insCode. It is enough to call if the insCode is already known, but not fully complete.

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 0%, so the description must compensate, but it only restates the parameter name: 'by insCode.' It does not explain what an insCode is, its format, how to obtain it, or that search_symbol could be used to resolve it. The parenthetical '(Rial)' refers to currency, not the parameter semantics, leaving the required parameter under-explained.

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: 'Live quote for an instrument by insCode.' It adds distinguishing details—currency (Rial) and freshness stamping—that separate it from siblings like get_price_history and get_market_watch. This is unambiguous and immediately actionable.

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 when to use the tool—when a live quote is needed—but it does not explicitly mention alternatives or exclusion criteria. It could have noted that get_price_history is for historical data or that search_symbol should be used first to resolve an insCode. The usage context is clear but not explicit enough for a higher score.

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