insert_glossary

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

With no annotations, the description carries the full behavioral burden and handles it well. It discloses auto-backup with prev/anchor slots, the precise meaning of backup=False, atomic validated saving, refusal of documents open in Word, and the graceful [DEFINITION NEEDED] fallback. This goes well beyond what the schema or annotations provide.

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 front-loaded with the main purpose, and every clause adds useful information: detection source, format, fallback behavior, placement, backup, save semantics, and a refusal condition. It is dense but not padded; the semicolon-heavy single paragraph is still easily scanable.

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?

The core behavior, edge cases, placement, backup, and document-open refusal are well covered, and an output schema exists to fill return-value details. However, key parameters such as heading_level and definition_patterns remain undocumented, and the relationship to check_defined_terms could be more explicit for a fully self-contained definition.

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 backup semantics and placement related to at_end/after_index, but it leaves heading, heading_level, and definition_patterns semantically unexplained. For a 7-parameter tool, this is only partial compensation for a schema with no 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 states a specific action and resource: 'Build a glossary section from the document's defined terms.' It also distinguishes itself from the sibling check_defined_terms by referencing 'same detection as check_defined_terms' while describing a distinct output artifact. The expected structure is detailed: heading, alphabetized paragraphs, bold terms, and harvested definitions.

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 useful context such as placement options and the Word-open refusal, and it references check_defined_terms as the detection sibling. However, it never explicitly says when to use this tool versus check_defined_terms or other insertion tools, so the usage boundary is implied rather than stated.

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