generate_tof

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

With no annotations provided, the description must fully disclose behavioral traits. It mentions insertion location and collection criteria, but lacks details on side effects (e.g., overwriting existing fields), permission requirements, or whether the document must have certain styles present.

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 sentences, front-loaded with the core action. Concise and informative, though could possibly mention output schema or usage notes in a second sentence.

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?

While the description covers the insertion location and collection logic, it omits important context such as required document state (e.g., existence of caption styles, valid para_id), error handling, or the structure of the output schema (which exists but is not referenced).

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. It explains the anchor parameter (para_id) by referencing 'the paragraph with para_id' and implies the title default, but does not explicitly describe each parameter's meaning or format.

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?

Clearly states the action: 'Insert a Table of Figures field block after the paragraph with para_id.' It also explains what it collects ('caption-styled paragraphs starting with 'Figure' as entries'). This separates it from similar tools like generate_list_of_figures by specifying it's a field block.

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?

No explicit guidance on when to use this tool versus alternatives (e.g., generate_list_of_figures). The description implies it's for inserting a field block, but does not indicate prerequisites or when not to use it.

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