create_price

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

With no annotations provided, the description carries the burden of behavior disclosure. It transparently reveals the upsert semantics, the currency default interaction with book currency, and default values for date, price_type, and source. The behavior that updates rather than duplicates is a significant disclosure not inferable from the schema. It doesn't describe return values, but output schema exists to cover that.

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 well-structured using Args blocks, which aids scanning. It's thorough, covering all 7 parameters plus upsert behavior. It's slightly long but every sentence earns its place given the 0% schema coverage. No wasted words.

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 7-parameter tool with zero schema description coverage and no annotations, the description thoroughly compensates. It explains defaults, edge cases (currency), and value formats. The worked example for currency is especially valuable. Output schema exists so return values need not be explained. It's complete for an agent to invoke correctly.

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 fully compensate — and it does. Every parameter is explained: commodity as symbol, namespace as commodity namespace, value as decimal string, currency with a worked example of the default-currency behavior, date as ISO format, price_type with enumerated meanings, and source identifier default.

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 ('Record a price') and resource ('commodity (stock, NAV, exchange rate)'). It clarifies the critical upsert behavior — existing price with same commodity/currency/date/source is updated rather than duplicated. This distinguishes it from sibling tools like create_prices (batch) and get_prices (retrieval).

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 provides clear context around currency defaults, explaining the natural reading for default-currency behavior and instructing when to pass currency explicitly (cross-currency pairs not involving the book default). It also documents defaults for date and source. It lacks explicit when-not-to-use guidance or alternative tool names, but the context given is substantive and actionable.

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