add_equation

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

With no annotations provided, the description carries the full behavioral burden, and it excels: it discloses that the document is NOT modified on unconvertible LaTeX, that equations are invisible to text-finding tools, that backup behavior is automatic unless backup=False, and that Word-open documents are refused. It also details specific side effects such as align* being rewritten to aligned. This is unusually transparent and covers failure, safety, and persistence behavior.

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 long, but every sentence carries operational weight: native math vs image, display/inline modes, supported TeX repertoire, error/safety guarantees, interaction with text tools, backup behavior, and open-document refusal. There is no filler or repeated verbosity; content is dense and front-loaded with the core purpose before expanding into modes and caveats. For a 9-parameter tool, this length is warranted.

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?

Given the tool's complexity and zero annotations, the description is remarkably complete: it covers input format, positioning rules, occurrence semantics, supported math constructs, failure behavior, read-back strategy, backup behavior, and a refused precondition. The output schema exists, so return-value documentation is not required from the description. An agent has everything needed to invoke this tool correctly and predict side effects.

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 — and it does. It explains the semantic roles of display, after_index, after_anchor, at_end, anchor_text, occurrence, backup, and latex content, including the 'exactly one of' positioning constraint and the occurrence-based match behavior. Only file_path is left to obvious inference, which is acceptable. This fully compensates for the schema's lack of parameter descriptions.

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 verb and resource: 'Insert a LaTeX equation as NATIVE Word math,' and immediately clarifies it is 'not an image' and is editable in Word's equation editor. It further distinguishes itself by explaining that equations are invisible to get_text/find_text and should be read with list_equations. An agent can confidently tell this apart from sibling insertion tools such as add_image or insert_paragraphs.

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 clear context for when to use this tool: when native, editable LaTeX math is needed, with explicit display and positioning semantics. It also gives a complementary alternative for reading equations ('read them with list_equations') and notes a hard constraint ('Refuses documents open in Word'). However, it stops short of explicitly stating when not to use this tool in favor of alternatives like add_image or insert_paragraphs.

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