Operational Notes

Operational Notes

Eight Box-side quirks the plugin works around. Read this if you're hitting unexpected behavior — most are upstream (Box, OAuth, MCP) rather than plugin bugs.

Full reference at references/operational-notes.md. This page is the index.

Quick reference

#	Title	Severity	Workaround in plugin?
1	search_files_metadata MCP tool returns empty	High	Yes — use search_files_keyword + mdfilters
2	OAuth scope doesn't widen on tier upgrade	High	Yes — box-tier-detect detects + suggests reconnect
3	Fresh metadata templates have ~10 min warm-up	Medium	Yes — box-init surfaces; box-recall falls through to index
4	search_files_keyword requires non-empty query	Low	Yes — pass "the" as pseudo-wildcard
5	gt comparison on float metadata is inclusive	Low	Yes — use epsilon (> 0.9001) for strict
6	Template name boxMemory vs legacy agentMemory	Low	Yes — read from workspace config, not hardcoded
7	Box Hubs have ~10 min indexing warm-up	Medium	Yes — box-ai-recall falls through to multi-doc
8	SDK v10.6.0+ tags content-type breaking change	Medium	N/A — plugin doesn't use this content-type

Detail per note

1. search_files_metadata MCP wrapper returns empty when data exists

The Box MCP's dedicated search_files_metadata tool returns empty results even when matching files exist with correct metadata. Use search_files_keyword with mdfilters instead — that path works.

Plugin handling: box-recall routes Business+ structured queries through search_files_keyword + mdfilters (never the broken tool).

2. OAuth token scope does not widen on tier upgrade

Upgrade your Box plan → metadata-template-create operations fail 403 even though your account now has permission. The pre-existing OAuth token is still scoped to the old plan.

Fix: disconnect and reconnect the Box MCP in your platform's MCP configuration. Forces a fresh OAuth flow.

Plugin handling: box-tier-detect detects capability mismatches and surfaces the disconnect/reconnect recommendation.

3. Fresh metadata templates have a ~10-minute warm-up window

Create a metadata template, apply it to a file, query via mdfilters → empty result. Box docs say Metadata Query is real-time; empirically it isn't for freshly-created templates.

Workaround: track metadata_template_created_at in workspace config. If <10 min, prefer the _index.json path over Metadata Query.

Plugin handling: box-init surfaces; box-recall auto-falls-through during warm-up.

4. Keyword search requires a non-empty query parameter

search_files_keyword rejects empty query strings — mdfilters alone isn't enough. Pass a stopword like "the" as a pseudo-wildcard. Virtually every memory body contains it.

5. gt comparison on float metadata fields is inclusive

mdfilters: {confidence: {gt: 0.9}} returns files with confidence == 0.9. Use epsilon (> 0.9001) when strict exclusion matters.

Affects lt, gte, lte similarly.

6. Metadata template name drift

The repo's canonical template is boxMemory. Some deployments used agentMemory (early prototype). The plugin reads metadata_template_key from _box-memory.json — supports either by configuration.

7. Box Hubs have a ~10-minute indexing warm-up window

Parallels Note 3. Newly-created Hubs and recently-added items take ~10 min before AI Ask returns non-empty results.

Plugin handling: box-ai-recall tracks hub.created_at / last_item_added_at; falls through to multi-doc Q&A during warm-up.

8. Box SDK v10.6.0+ search content-type tags is a breaking change

April 2026 SDK release corrected content_type='tags' behavior to match the public API. If you're wrapping the plugin via the SDK and using tags filter, audit your code after upgrading.

Plugin handling: not used internally; informational for users.

Where to add new notes

If you discover a Box-side quirk we don't document:

1. Open an issue at https://github.com/mrdulasolutions/BOX/issues
2. PR: add to references/operational-notes.md following the same shape (Symptom / Cause / Workaround / Implementation impact)
3. Note will sync to the on-prem repo via its .schema-pin mechanism on next release

See also

• Full reference: references/operational-notes.md
• Troubleshooting — diagnostic flows for common errors
• Box AI Integration — Box AI quirks (1, 7) live here too