art.memory.resolve_references

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

There are no annotations or descriptions of side effects, return format, or error behavior. The tool is named 'resolve' but it is unclear whether it performs any mutations, caches results, or is purely read-only. The statement 'Returns categorized results' is too generic to convey the actual output structure.

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 concise and front-loaded with the main verb and object. It avoids fluff and directly states the input (context) and output (categorized results). However, the brevity contributes to ambiguity, which slightly reduces the score, but structurally it is efficient.

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 description lacks critical contextual details: no output schema is provided, no examples, no explanation of how the parameters affect the results, and no mention of which categories are returned. Given the existence of more specific memory tools, this generic description leaves the agent incompletely informed about the tool's full capability and behavior.

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?

Each parameter has a brief description (e.g., 'Asset type filter', 'Style ID (defaults to latest)'), but their relationship to the resolution process is not explained. For instance, how do 'type' and 'category' interact? What does 'dimensions to match' mean in the context of resolving references and anchors? The descriptions are skeletal and do not clarify the parameter roles beyond generic filters.

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 is vague: 'resolve relevant references, anchors, decisions, and rejections' does not clearly define the action or distinguish it from the existing find_* sibling tools (e.g., find_references, find_anchors, find_decisions, find_rejections). The term 'relevant' and 'given context' are ambiguous, and the parameters (type, category, style_id, dimensions) are not explicitly tied to that context.

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?

No guidance is provided on when to use this combined resolver versus the dedicated find functions for each memory type. The description does not mention preferred scenarios, fallback logic, or differences from the alternatives, leaving the agent without clear usage criteria.

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