remirror (返照） — psyche audits for AI agents

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

With no annotations, the description carries the full burden and does so: it discloses cost ($79.00 in prepaid credits), refund behavior for unreachable targets, the security posture of target_auth_token (held in memory only, never stored), the conditional signature requirement with REMIRROR_REQUIRE_SIGNATURES=1 and which arguments are signed, and the return shape (audit_id + access_token). This is exactly the kind of context annotations cannot supply.

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 action and cost are front-loaded ahead of conditional logistics, and each clause adds operational information rather than filler. It is a single dense paragraph, though, with the signature rules and protocol semantics running together with no structural separation, which hurts scannability for a 10-parameter tool.

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?

With no output schema and no annotations, the description steps up by documenting the return value and the polling handoff, plus auth, cost, and failure semantics. The only real hole is the unexplained teleology_name/teleology_statement pair, which an agent would otherwise have to guess at.

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; it explains teleology_weights (must sum to 1.0, match trial objectives), teleology_id with an example, target_protocol values and their mechanics, api_key, signature, and trial_id's override role. However, teleology_name and teleology_statement are never mentioned, leaving two of ten parameters undocumented anywhere.

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 first sentence states a specific verb and resource ('Create a psyche audit against a target agent endpoint') and immediately characterizes the operation (dilemma trial, self-reports, three-source mirror). It is trivially distinguishable from the read-only siblings remirror_get_report and remirror_list_trials.

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?

It gives explicit routing: 'Supply exactly one of teleology_weights or teleology_id', names the alternative path (shipped telos loaded from the registry on the telos's own dilemma trial 'unless trial_id is given explicitly'), and tells the caller to poll remirror_get_report for the result. When-not conditions and alternatives are both spelled out.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one useful fact beyond the schema — the access_token comes from creation — but says nothing about whether this is read-only, whether the report may be unavailable/partial when polled, or any rate limits.

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?

Two tight sentences with no filler, and the core purpose is front-loaded ahead of the parameter note. Nothing is redundant.

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?

There is no output schema and no annotations, so the description should carry more of the return-value story than it does — it never says what a 'status' versus a 'final report' response looks like. For a simple two-param fetch tool it is adequate but leaves a clear gap.

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 coverage is 0% and both parameters are bare strings, so the description must compensate. It adds real meaning for access_token by stating it is 'returned at creation,' but gives no elaboration on audit_id beyond its name.

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?

States a specific verb (fetch) and resource (the status or final mirror report of an audit session), which is distinct enough from sibling remirror_create_audit. It does not explicitly name a sibling to differentiate against, but the resource itself is unambiguous.

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?

Usage is only implied: the phrase 'status or final report' hints at a lifecycle where status is polled before the final report exists, and the token requirement implies it follows remirror_create_audit. There is no explicit when-to-use, when-not-to-use, or alternative named.

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

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

With no annotations, the description carries the full burden but only partly meets it: "List" implies a read-only discovery call and "Free" discloses cost, and the returned fields are named. It omits permissions/auth requirements, pagination behavior, and any statement that nothing is mutated.

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?

A single front-loaded sentence with the verb first, the scope second, and the returned fields compactly enumerated. No filler and nothing repeated from structured data.

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?

With no annotations, no output schema, and no parameters, the description must carry all context and largely does: it names the returned attributes (id, version, objectives covered, dilemma count) and the domain. Missing only auth/pagination and an explicit pointer to the tool that consumes the trial ids.

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?

The tool takes zero parameters, so baseline 4 applies; there is nothing for the description to explain beyond the schema's empty object. The field list describes outputs rather than inputs, which is a separate concern.

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?

States a specific verb and resource ("List available dilemma trials"), narrows scope to "psyche audits," and enumerates the fields returned. An agent can distinguish it from remirror_create_audit and remirror_get_report, though it never names them explicitly.

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 when-to-use statement, no prerequisites, and no mention of the sibling tools. The workflow role (discover trial ids before calling create_audit) is only inferable, and "Free" is the sole decision-relevant hint.

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