manage_beliefs

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

With no annotations, the description carries the burden of behavioral disclosure and does add meaningful mechanics: TTL-based expiration sweeps, exponential confidence decay, and category filtering. However, it does not disclose mutating or destructive aspects such as what 'expire' or 'reconcile' actions actually do, whether operations are reversible, or what side effects updates trigger.

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 dense sentence with no filler or repetition. It front-loads the core concept and packs three meaningful behavioral details into a compact structure.

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?

This is a complex tool with 12 parameters, four action enum values, and no output schema or annotations, so the description needs to explain action semantics, return behavior, and usage context. The current one-sentence teaser omits how the action parameter drives behavior accordion-style, what each action returns, and when a caller should choose management over querying.

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 compensate, but it only hints at a few parameter clusters: expires_at via TTL sweeps, confidence/decay_rate via confidence decay, and category via filtering. The remaining parameters—action, object, source, project, subject, belief_id, predicate, and client_request_id—receive no explanatory support from the description.

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 identifies the resource as a structured belief state and highlights key behaviors: TTL expiration sweeps, exponential confidence decay, and category filtering. It is not a tautology and evokes a distinct maintenance role compared with siblings like query_knowledge and manage_intentions, though 'maintain' is somewhat broad and does not enumerate the action families from the schema.

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 about when to use this tool versus alternatives such as query_knowledge, manage_intentions, or manage_reasoning_db. The description implies a general maintenance purpose but offers no exclusions, prerequisites, or routing criteria.

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