find_formatted

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

With no annotations, the description fully carries the behavioral burden. It discloses Word's resolution order (run properties, character style, paragraph-style chain, document defaults), that matches report the resolution level, that query matching is case-sensitive, that text-box content is excluded, that theme references are counted rather than guessed, and that the tool is read-only. This is rich, non-obvious 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 dense but every sentence adds value: purpose, resolution model, query behavior, scope, exclusions, theme handling, and mutation twin. It is front-loaded with the core purpose and then provides exactly the caveats an agent needs, with no filler.

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 high complexity — nested formatting object, inheritance semantics, multiple scopes, exclusions, and a sibling mutation tool — the description covers every decision point. The presence of an output schema means return-value documentation is unnecessary, and the description still notes that matches report the satisfied formatting level.

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 explain the parameters itself. It does: query semantics (null vs case-sensitive string), scope values ('body' with tables, 'all' with footnotes/endnotes), and formatting keys with value types. The only under-explained parameter is file_path, which is self-evident from its name.

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 uses a specific verb ('Find') and a distinct resource ('text by its EFFECTIVE formatting'), listing concrete criteria (bold/italic/underline/strike, font, size_pt, color, highlight, style). It clearly separates this tool from plain text search and mentions the mutation twin replace_formatted, so an agent can identify its unique role.

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 explicit usage semantics: query=None vs a query string, scope='body' vs 'all', and the text-box exclusion with named alternatives (get_textbox_text or get_text include_textboxes). It also names replace_formatted as the mutation twin, clarifying when not to use this read-only version.

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