ingest_observation

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

Annotations already indicate this is not read-only, so the description adds value by explaining that it merges detections into the world model, re-identifies objects, and boosts confidence – all behavioral effects beyond the annotations. It also hints at reconciliation analysis. It does not disclose edge cases or failure modes, but the additional context about state mutation is meaningful given annotations are sparse. No contradiction.

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 a single sentence that efficiently conveys the primary and secondary purposes. It is front-loaded with the main action and avoids unnecessary words. Though it is a bit dense due to the 'or' structuring, it is appropriately concise for the complexity.

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 (6 parameters, nested objects, no output schema), the description is incomplete. It does not explain what the tool returns, how observer_pose and field_of_view feed into the merge/reconcile logic, or when each mode should be used. The schema descriptions help somewhat, but the overall behavior and expected outcomes are under-specified, leaving an agent uncertain about invocation and interpretation.

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 83% (high), so the baseline is 3. The description does not elaborate on individual parameters beyond the schema; it only references detections conceptually and reconcile as a mode. It does not add semantics for field_of_view, observer_pose, or visual_state_id, which the schema partially describes. The description adds marginal value over the schema, consistent with the baseline.

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 clearly states a specific action (merge detections into the world model) and a secondary reconciliation mode, distinguishing it from sibling tools like query_entities (query-only) and update_entity (general update). The verb 'merge' and resource 'world model' are specific, and the mention of re-identifying objects and boosting confidence adds precision. However, the dual purpose (merge vs reconcile) slightly dilutes focus, so not a perfect 5.

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 implies usage (when you have vision detections to ingest) but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or comparison to siblings. It does not say 'use query_entities for reading' or 'use update_entity for direct edits'. The guidance is implied rather than explicit, so it meets the minimum but lacks clear routing.

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