resolve_name

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It does so comprehensively: it explains the 4-tier resolution chain (curated reagent DB → condensed formula parser → ChemScript IUPAC → PubChem), the exact return dict keys, the error behavior ({ok: False, error: ...}), and the network dependency for PubChem (via the use_network parameter). No aspect of the tool's behavior is left to the agent's guess, and there is no contradiction with any annotations (since none exist).

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 multi-paragraph and includes an Args section and a Returns section, which makes it longer than a typical one-liner. However, every sentence contributes: the opening sentence front-loads the purpose, the examples are invaluable, and the return dict documentation is essential given there is no output schema. It is structured with clear headings and is not padded with fluff. It earns a 4 because it is detailed but not excessively verbose for a tool of this complexity.

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?

This tool has no output schema and moderate complexity (2 parameters, one optional). The description covers all necessary context: the input resolution rules, the exact output keys, the error condition, and even pointers to downstream usage (modify_molecule, draw_molecule, render_scheme). Nothing an agent needs to call it correctly or interpret its result is missing. Given the rich content of the returns dict, the written documentation is fully sufficient.

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 0% — the schema only shows bare types (string, boolean) with no descriptions. The description compensates richly: for 'query' it defines what constitutes a chemical identifier, gives examples across all accepted forms (aspirin, Cs2CO3, 2-chloropyridine, CAS number, Et3N), and for 'use_network' it explains the purpose (PubChem lookup) and the requirement (internet) plus default. This additional meaning is exactly what an agent needs to correctly construct inputs.

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 opens with a specific, action-oriented statement: 'Resolve any chemical identifier to a rich molecule descriptor.' It then enumerates the exact input types (name, abbreviation, condensed formula, CAS number) and the output structure (SMILES, formula, MW, etc.), which makes the tool's purpose unambiguous and clearly distinguishes it from sibling tools like search_compound or parse_reaction. The 'Do NOT hand-construct SMILES' instruction further cements its role as the canonical resolver.

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 direct usage guidance: 'Do NOT hand-construct SMILES — use this tool instead' and explains how the returned dict can be fed into other tools (modify_molecule, draw_molecule, render_scheme). This tells when to use it and provides context for integration. However, it does not explicitly state when *not* to use it or name an alternative tool (e.g., search_compound) for similar identifier lookups, leaving room for an agent to wonder about overlapping tools. So it is strong but not fully exhaustive.

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