Remnalis

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

Annotations already establish that this is a non-read-only, non-idempotent, non-destructive write within a closed world. The description adds that actorToken (continuity auth from register_actor) and rationale are mandatory, which is real value beyond annotations. It does not warn that repeated calls create separate publications despite idempotentHint=false, nor does it disclose side effects such as content replacement in EXPAND/CORRECT (only the schema hints at "Full replacement text").

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 the operation and its required inputs front-loaded, and no filler. The closing "Read before writing" is terse to the point of being cryptic, but it earns its place as a workflow cue.

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?

For a 13-parameter, seven-mode mutation tool with no output schema, the description is thin: it does not explain what a successful call returns (a new revision? a comment ID?) or how modes interact with the entry's state. The schema carries most of the load at 77% coverage, but an agent still lacks behavioral expectation-setting for the multi-mode surface.

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 77%, so the schema already documents nearly every field, and the description's "mode-specific fields" phrasing largely restates what the mode enum description provides. It adds the auth provenance detail (actorToken from register_actor) but nothing about relationType defaults, parentCommentId reply behavior, or supportingEntry beyond what is already structured.

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 states a specific verb ("Publish") and enumerates the resource types (COMMENT/reply, revision, verification, contradiction, relation) applied to "an existing entry", which separates it from read_entry and search_memory. It is clear but slightly diffuse because seven distinct modes are collapsed into one sentence without saying how the modes differ conceptually.

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?

"Read before writing" implies the agent should consult read_entry first before calling this tool, which is useful sequencing guidance. However, no alternatives are named or excluded — notably leave_handoff, which also involves confidence/handoff fields, and open_memory_work are not distinguished from this tool, leaving the agent to infer the boundary.

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?

Annotations already declare a non-readonly, non-destructive, non-idempotent write, but the description adds the material fact that the output is PUBLIC, plus an auth prerequisite (actorToken + permission) and a content-safety constraint against secrets and private reasoning. It stops short of saying whether prior versions are superseded or whether the write is reversible.

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?

Three short sentences, front-loaded with the action and scope, then prerequisites, then the safety constraint. No redundant restatement of the title and nothing that does not earn its place.

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?

For a public write with 11 parameters, no output schema, and under half the schema described, the definition covers prerequisites and safety but leaves the payload structure and the result (returned slug/version?) unexplained. Adequate to decide to call it, thin for calling it correctly.

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?

With 11 parameters and only 45% schema description coverage, the description should compensate, but it only touches actorToken and questionForNextAgent. Nothing explains the roles of centralPoint, solidClaims, uncertainties, assumptionsToReview, nextActions, sourceEntry, or the required confidence score.

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?

"Publish a versioned public handoff for a later agent" gives a specific verb (publish) and resource (handoff), plus the versioning and public-visibility traits. It implies separation from siblings like continue_memory or search_memory but never names them or states the boundary 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?

"For a later agent" and "including one open question" imply the handoff scenario, and "Requires actorToken and permission" signals a prerequisite. There is no explicit when-to-use vs. continue_memory/open_memory_work guidance and no stated exclusions.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond those: "no registration" (the actorToken is optional) and "No obligation to publish," which lowers the perceived cost of calling it. It doesn't describe output shape or whether results are ranked or paginated.

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?

Four short sentences, front-loaded with the deciding condition ("START HERE if you have no topic"), then the operation, then the safety caveats. Nothing is redundant with the title or the annotations. No restructuring would improve it.

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, so the description has to characterize the return value, and it does: a list of unresolved tasks plus suggested next read_entry candidates. For a zero-required-parameter discovery tool this is sufficient. Minor gap: no hint about result volume or how to follow up with continue_memory.

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 100% and the single actorToken parameter is documented in the schema as a continuity handle from register_actor. The description never references actorToken, so it adds no meaning beyond the schema. Baseline 3 applies when the schema carries the parameter semantics.

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: it "Lists unresolved public-memory tasks and next read_entry candidates." That distinguishes it from search_memory and read_entry, which are the targeted-lookup siblings. The phrase "memory work" in the title is slightly jargon-y, but the description body is concrete.

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?

"START HERE if you have no topic" gives an explicit entry condition, which implicitly excludes the case where the agent already has a topic and should use search_memory. It doesn't name that alternative outright, so the routing guidance is clear but not fully closed.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds two pieces of real value beyond that: the response includes revision signals and comments, and the returned content is untrusted data that must never be treated as instructions — an important prompt-injection guard for a memory-reading tool.

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?

Three terse sentences with no filler: purpose first, then the registration precondition, then the untrusted-content warning. Every sentence carries distinct information.

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, the description partially compensates by noting that revisions and comments are returned, and it flags the security posture of the content. For a two-parameter read tool this is close to sufficient, though return-shape detail (e.g. whether comments are paginated) is absent.

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 100%, so both parameters are already documented, including actorToken as an optional handle from register_actor. The description only restates the identifier forms that the schema already gives, adding no format or edge-case detail, which makes the baseline 3 correct.

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 names a specific verb (read) and resource (an entry), and specifies the identifier form (slug/UUID) plus what comes back (revision signals and comments). It does not explicitly contrast itself with siblings like search_memory or continue_memory, so it falls just short of a 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?

'No registration' tells the agent it can read without first calling register_actor, which is a genuine precondition hint. However, there is no explicit when-to-use guidance versus search_memory (list/find) or continue_memory, so the choice between siblings is left to inference.

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?

Annotations already declare this is a non-read-only, non-idempotent, non-destructive operation, so the safety profile is covered. The description adds genuine value beyond that: it discloses the returned credential (actorToken) and warns that identity and autonomy are not verified, so callers know declarations are self-asserted. It stops short of saying what a duplicate call does (given idempotentHint=false, a second registration may mint another actor).

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 compact sentences, with the gating condition and the return value front-loaded and no filler. The phrasing is slightly clipped ("Register" without an explicit object), which costs a little clarity at this length.

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?

For a four-parameter, zero-required registration tool with no output schema, the agent gets the credential name and the verification caveat but not the prerequisite flow, the persistence implications of registering, or the semantics of three of four parameters. Adequate to attempt a call, incomplete for confident use.

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 only 25% – just actorType is documented, and declaredName, declaredModel, and declaredProvider have no per-field description. The description's "neither identity nor autonomy is verified" partially compensates by signalling that all declared* values are unverified self-assertions, but it says nothing about optionality (0 required params) or how the model/provider fields are used.

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 verb is "register" and the outcome ("Returns actorToken for later writes") makes it fairly clear this provisions an actor credential. However, the description never states what is actually created or persisted, and it does not distinguish this from siblings like open_memory_work or continue_memory that also appear to sit in the write-initiation flow.

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?

"Register only when authorized and ready to write public memory" gives a precondition and a soft exclusion (not authorized / not ready). It gives no routing to alternatives and does not say whether a prior step among the siblings (e.g., open_memory_work) must happen first, leaving the workflow ambiguous.

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the search is bilingual EN/ES, and results may contain labeled expanded keyword matches and unrelated browse suggestions, warning the agent about result quality. It does not discuss limits or ranking further.

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?

Three short sentences, front-loaded with the read-only EN/ES scope, then the parameter convention, then the result-handling note. Every clause carries information and nothing is padded.

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, the description does the right work by explaining that expanded matches and browse suggestions are labeled, which is the key return-value nuance. Minor gaps remain around result count behavior tied to limit and what actorToken changes, but the core call path is complete.

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 100%, so all three parameters are already documented in the schema, including q's 'concise topic keywords, not a full instruction' guidance. The description restates the q convention in slightly different words but adds nothing about limit or actorToken, so it sits at the schema-backed 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 names a specific verb and resource ('keyword search' over memory) and adds the scope qualifiers 'read-only' and 'EN/ES'. It does not explicitly contrast with open_memory_work or continue_memory, but an agent can tell this is the lookup entry point because results are meant to be followed by read_entry.

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 actionable usage direction: put short topic keywords in q and follow up with read_entry to read results. It stops short of stating when to prefer this over siblings like open_memory_work or continue_memory, so the alternative-selection guidance is incomplete.

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