[bobleer]

Summary

Make the GenOfficeFile contract say clearly that it only produces Office files, and send agents that need to read or analyze an existing .docx/.xlsx/.pptx to the Read tool.

Type and Areas

Type: bug fix (agent tool contract)

Areas: Rust core (GenOfficeFile tool), office-documents engine

Motivation / Impact

When a user attached an .xlsx and asked for insights, the agent called GenOfficeFile twice (both failed) before falling back to Read.

• The description listed read as a peer action with sheet/range support. The only restriction it gave was "Only files created by this tool are editable", so the model treated the tool as an Office reader. In fact read opens only files this tool generated, because they carry its embedded source model.
• The not_generated failure ended with "Use action=guide for the format's contract.", and the engine message said "create a new file instead". Both pushed the model to keep trying inside the same tool.

Changes:

• Add a Scope paragraph at the top of the description: use the tool only to produce or change Office files. Read and edit open only files it generated. Every other Office file (attachments, uploads, files saved by other programs) goes to Read, and the agent should not probe it with GenOfficeFile first.
• Mark read as verification-only in the description, the action schema, and the short description.
• Give not_generated its own recovery text: do not retry (discard_external_changes does not apply), use Read. Drop the guide hint from externally_modified, whose message already explains what to do. Other errors keep the guide hint.
• Reword the engine's not_generated message so it no longer suggests creating a new file.

User impact: fewer failed tool calls and less wasted context when users ask for analysis of attached Office files. Generation and edit behavior are unchanged.

Verification

• cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,tools-office-documents --lib agentic::tools::implementations::gen_office_file_tool::tests: 7 passed, including the new contract_routes_reading_existing_office_files_to_read_tool.
• cargo test --locked -p openbitfun-office-documents: all passed.
• pnpm run fmt:rs, git diff --check: clean.

Not verified: I have not re-run the original attachment scenario against a live model, so the effect on tool choice comes from the reasoning above and has not been measured. Remote scenarios are unaffected: only prompt and error text changed, and no file IO paths changed.

Reviewer Notes

The text the model sees changed in three places: the tool description, the action schema description, and short_description. No i18n catalogs or generated capability files reference the changed strings.

Checklist

• This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
• Relevant verification is recorded above, or skipped checks are explained.
• User-facing strings, docs, and locales are updated where applicable.